Building, Configuring and Testing Python XPCOM Package

This document attempts to explain how to build, configure and test the Python XPCOM Package. This document assumes you have already successfully built Mozilla from source and your environment is currently set up for such a build - see the Mozilla build documentation for more information.

PyXPCOM can be built on Windows using either the nmake makefile.win process, or the configure; gmake process used by Linux.

configure; gmake Instructions

Preparing for the build

• Apply the patch in bugzilla bug 129216. (If this bug is marked as "FIXED", it probably means there is no need to apply the patch and that these docs are out of date)
• On Linux, you must have Python built for dynamic linking.  ActivePython 2.1 is one such build.
• On Windows, you must have a Python source tree installed and built.  Patches gratefully accepted that allow an installed Python to be used (it should not be hard!)
• Ensure the Python interpreter you wish to use is on your path, such that "python" will execute it correctly.  The configure process uses this to locate the Python support files.

Building

• From the top-level Mozilla directory, execute ./configure --enable-extensions=extensions/pyxpcom. As per the Mozilla build instructions, you may add this option to your .mozconfig file.  If you wish to enable debugging, just enable it as you would normally for Mozilla; PyXPCOM will pick up the same settings.
  (On Windows you will need to execute sh ./configure ... if running from a Command Prompt.  See the Mozilla win32 specific gmake build instructions for more details.
• Build the Mozilla tree as normal; PyXPCOM will automatically be built.  Alternatively, change to the top-level PyXPCOM directory and execute gmake in that directory.

Windows makefile.win Instructions

Windows builds still support the Windows makefile.win build process.  You can build them by performing the following steps

Preparing for the build

• Ensure your machine is setup to build Mozilla and XPCOM itself.
• Set PYTHON_SRC to point to your Python source root directory.  This can either be the root of a "binary" install (with headers and libraries) or a Python source tree.

Building

• Change to the mozilla/extensions/python/xpcom directory.
• Run nmake -f makefile.win.  This should build the extensions and install them into the {mozilla-dist-directory}/bin/Python directory.
• Change to the xpcom/test directory, and run python regrtest.py (or python_d regrtest.py for debug builds)

PyXPCOM outside Mozilla

When you are using PyXPCOM from inside mozilla, no additional configuration options should be necessary.  However, if you wish to use PyXPCOM from stand-alone Python (ie, so you can write simple Python scripts that can be executed normally and use XPCOM), then additional environment variables must be setup.

• PYTHONPATH - PYTHONPATH needs to be set appropriately. You must manually ensure that the mozilla/dist/bin/python directory (which is where PyXPCOM was installed during the build process) is listed.  Note that when PyXPCOM is used from within Mozilla (or any other xpcom process), this path will automatically be added to sys.path.  It is only when Python directly uses xpcom that this step is necessary.
  If anything is wrong here you should get a normal ImportError.

Note that on Windows, the PYTHONPATH is generally maintained in the Registry; however, you can set this variable at a DOS prompt, and it will still be added to the core PYTHONPATH.

• PATH, LD_LIBRARY_PATH, etc - On Windows, you must ensure that the Mozilla bin directory is listed on your PATH, or that you execute your scripts with the Mozilla bin directory as the current directory.
  On Linux, you must set your PATH and LD_LIBRARY_PATH variables appropriately.  However, you may find it simpler and easier to use the run-mozilla.sh script in the Mozilla bin directory.  For example, changing to the Mozilla bin directory and executing:
  ./run-mozilla.sh python ~/src/mozilla/extensions/python/xpcom/test/regrtest.py
  should setup a correct environment and execute the PyXPCOM test suite.

Testing your Setup

The Python XPCOM Package has a complete test suite.

In the rest of this section, we walk through some simpler tests a step at a time, to help diagnose any problems.

Note: We recommend you do all your testing outside of mozilla.exe; it is far simpler to test all of this using the PyXPCOM package stand-alone.

Note: On Windows, if you use a debug build of Mozilla (i.e., in dist\WIN32_D.OBJ\bin), you must use python_d.exe; if you use a release build (i.e., in a dist\WIN32_O.OBJ\bin directory), you must use python.exe.  makefile.stupid.win handles this automatically.

To test your setup:

1. Start Python, and check
   >>> import xpcom
   works. If not, check your PYTHONPATH - the main PyXPCOM package can not be located.  Also check your PATH, and if you are on Linux, remember that executing ./run-mozilla.sh python is the easiest way.
2. Check
   >>> import xpcom._xpcom
   works. If not, then most likely your Mozilla directory is not on your path, or something is wrong with _xpcom(_d).pyd/_xpcommodule.so.
3. Next run a simple test: test/test_misc.py. With a Windows debug build, the command may look like:
   C:\Anywhere> python_d \src\python\xpcom\test\test_misc.py
   or on Linux
   /home/user/src/mozilla/dist/bin$ python /home/user/src/python/xpcom/test/test_misc.py

If you can't get this going, you won't get much further! (You may see a few errors - that is OK, as long as it appears something worked!).  If everything looks OK, the next step is to register our test component and run our full test suite.

Registering the Loader and Test Component

First register the generic Python loader. For instructions, see the architecture document. Do this only once, regardless of how many Python components you have.  Then install the test component itself, and finally you can test it!

Registering the Python Loader and Component

To register the Python Loader and Component:

1. Ensure the build process has put pyloader.dll (or modpyloader.so for Unix), and the files py_test_component.py and py_test_component.idl into the Mozilla bin/components directory.  If not, copy the files there manually.
2. Run regxpcom (or ./run-mozilla.sh ./regxpcom if appropriate). regxpcom is a standard Mozilla executable, found in the bin directory, that detects the new DLL and .py files and registers them accordingly.  You should see a few messages that include the following:

Registering: PythonComponentLoader
Registered 1 Python components in pyloader.dll
nsNativeComponentLoader: autoregistering succeeded
Auto-registering all Python components in F:\src\mozilla\dist\WIN32_D.OBJ\bin\components
Registering: PythonTestComponent
Registered 1 Python components in py_test_component.py

If so (or you see no message at all), you are ready to run the test suite.

Note: If you execute this same step a second time, you will not see any of the above mentioned messages. XPCOM knows that nothing has changed since you last ran regxpcom, so nothing is registered.  If you do not see these messages the first time you run it, there is the possibility that some other process, possibly the build process, has already executed this step.

Running the Test Suite

Before running the test suite, you should change to the mozilla/xpcom/sample directory and build it.  This will build and install a sample component which is used by the test suite.  If you do not have this component available, some of the Python tests will fail.

To run the test suite, run xpcom/test/regrtest.py.  This runs the tests and ensures that the test output is as expected.  If all tests pass, you have a fully functioning Python XPCOM package.  Enjoy!