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.

This section covers:

• Configuring your Environment

• Building

• Testing your Setup

• Registering the Loader and Test Component
• Running the test suite

Configuring your Environment

In addition to the existing environment requirements for building Mozilla itself, the Python XPCOM package has the following requirements:

• Mozilla Directory - Ensure the Mozilla bin directory is on your PATH (LD_LIBRARY_PATH on Unix) so Python can locate the xpcom.dll module needed for core XPCOM services.
• PYTHONPATH - PYTHONPATH needs to be set appropriately. Ensure the parent to this xpcom directory is on your path so "import xpcom" locates this directory.  Note that the Mozilla components directory does not need to be on the PYTHONPATH, but any modules used by your components must be set correctly.  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.

Building

The initial release of the Python XPCOM package has a very simple, hard-coded build process.  The intention is to include this package in the Mozilla source tree, and integrate the build with the Mozilla build.  Until this happens, perform the following steps:

• Ensure you can successfully build Mozilla itself from source code.
• Unpack this source code, and change to the xpcom directory under the root PyXPCOM directory.
• For Windows, edit makefile.stupid.win, while for Linux, edit makefile.stupid.linux
• As per the instructions at the top of the makefile, edit the MOZ_SRC, INSTALLDIR and PYTHON_SRC definitions appropriately.

Build Example: Building on Windows

For this example, we will assume that the source code for Mozilla is in C:\src\mozilla, the source code for the PyXPCOM package is in c:\src\pyxpcom. Further, we assume that you have Python 2.0 installed in C:\Python20, and wish to install the built Python XPCOM package so it exists in C:\Python20\xpcom.

To build the package in this environment, you would perform the following steps:

• Unpack the PyXPCOM package source code into the appropriate directory
• Edit makefile.stupid.win with the following changes:
  MOZ_SRC=C:\src
  INSTALLDIR=C:\Python20
  PYTHON_SRC=C:\Python20
•  From the top-level Python xpcom source directory (i.e., the directory with makefile.stupid.win), execute the command:
  nmake -f makefile.stupid.win install

NOTE: To build a Debug version of the Python XPCOM library, you can add DEBUG=1 to the nmake command-line.

If everything appears to work and you are brave, you may also like to execute make -f makefile.stupid.win test to execute the test script.  Otherwise, continue to the following section where we confirm the installation step-by-step.

Build Example: Building on Linux

For this example, we will assume that the source code for Mozilla is in ~/src/mozilla, the source code for the PyXPCOM package is in ~/src/pyxpcom. Further, we assume that you have ActivePython 2.0 installed in /usr/local/ActivePython2.0, and wish to install the built Python XPCOM package so it exists in /usr/local/ActivePython2.0/lib/python2.0/site-packages/xpcom.

To build the package in this environment, you would perform the following steps:

• Unpack the PyXPCOM package source code into the appropriate directory
• Edit makefile.stupid.linux with the following changes (substituting username accordingly):
  MOZ_SRC=/home/username/src
  INSTALLDIR=/usr/local/ActivePython-2.0/site-packages
  PYTHON_SRC=/usr/local/ActivePython-2.0
• Build: As a regular user, from the top-level Python xpcom source directory (i.e., the directory with makefile.stupid.linux), execute the command:
  make -f makefile.stupid.linux DEBUG=1
• Install: Log in as a user with permissions to install into the relevant directories (usually the root user).  From the top-level Python xpcom source directory (i.e., the directory with makefile.stupid.linux), execute the command:
  make -f makefile.stupid.linux DEBUG=1 install
• Switch back to a regular user, ready for testing!

NOTE: The instructions above are for a Debug build, as this is the default Mozilla build type.  If you have configured Mozilla to build a Release version of Mozilla, you can drop the DEBUG=1 option.  It is important that PyXPCOM and Mozilla itself are consistent with respect to Release and Debug builds.  For more details, please consult the makefile.

If everything appears to work and you are brave, you may also like to execute make -f makefile.stupid.linux test to execute the test script.  Otherwise, continue to the following section where we confirm the installation step--by-step.

Testing your Setup

The Python XPCOM Package has a complete test suite.  If you are impatient, you can simply execute make -f makefile.stupid.linux test (for Linux) or nmake -f makefile.stupid.linux test (for Windows).  If this command indicates that the tests succeeded, then you can ignore the rest of this section.

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..
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! If you do, 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. regxpcom is a standard Mozilla executable, found in the bin directory, that detects whether the DLL and .py files have been added 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

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!