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

Building

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

Building

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.

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.

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.exemakefile.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!