Building PyXPCOM

  • Revision slug: Building_PyXPCOM
  • Revision title: Building PyXPCOM
  • Revision id: 121910
  • Created:
  • Creator: ObsidianX
  • Is current revision? No
  • Comment /* Testing PyXPCOM */

Revision Content

These are the instructions for building PyXPCOM.

Installing Python

PyXPCOM Requirements

  • PyXPCOM requires Python 2.3 or later (Python 2.3 and 2.4 have both been recently tested).
  • PyXPCOM requires access to a shared Python library.

Linux

For Linux users, the build script should check if you have a suitable shared library version of Python. Jump to Compiling Mozilla, and if you receive an error telling you a shared Python can not be located, then you'll need to compile Python with --enable-shared as outlined below.

Recent Fedora and Ubuntu builds

These distributions generally have a shared Python already available.

Gentoo systems

Building a shared Python library seems to only be possible with python-2.3* or later, so you'll need to upgrade if you're using python-2.2* or earlier. For ebuilds python-2.3* and later the shared library is built and installed by default.

Mac OS X

For OS X 10.3 and 10.4 users, the Python 2.3 Framework is already available. If you want to build against Python 2.4, you will need to build your own from source, build via DarwinPorts or Fink, or install either MacPython or ActivePython. You can then skip to Compiling Mozilla. If you want to distribute your application, you might prefer to use the built-in Python 2.3 Framework at first, since embedding the Python Framework into an application bundle may take some non-standard customizations to the Python build scripts.

Windows

The official Python installer for Windows installs the shared version of the the library automatically, so Windows users can simply install Python and skip to Compiling Mozilla.

Other systems

If you don't use any of the above systems, get the latest stable Python source tarball from python.org and do:

tar xjf Python-2.4.2.tar.bz2
cd Python-2.4.2
./configure --enable-shared --prefix=/usr  # Adjust --prefix to install over your current Python
make
sudo make install

Compiling Mozilla

You should be familiar with the Developer Documentation regarding downloading the source code and building applications in the Mozilla code base (eg. Firefox, XulRunner).

Depending on your needs, you will want to pick an appropriate branch of the Mozilla CVS repository.

  • If you need the most stable code base, and only need Python in backend XPCOM classes, check out Mozilla from the MOZILLA_1_8_BRANCH or the MOZILLA_1_8_0_BRANCH in CVS and build it. Note that this branch may **not** automatically check if you have a suitable shared Python build on Linux systems - you must ensure this yourself.
  • Use the Mozilla trunk. This has the latest version of XPCOM, incorporating work done on the DOM branches (see below)

Note: A DOM_AGNOSTIC2_BRANCH may also be useful for testing - it has the same XPCOM as the trunk, but includes many other changes to make Python a first-class language in the DOM. This branch has been merged with trunk on 2006-06-13, so use the HEAD for builds after that date.

You can build PyXPCOM against any of the applications available in the CVS repository. The example below shows building PyXPCOM for SeaMonkey, with Python DOM support. You can also build against XULRunner on the HEAD or MOZILLA_1_8_0_BRANCH by removing "python/dom" from the options, and of course, changing the branch in the CVS checkout command.

All Platforms

On all platforms, you should first ensure you can build a vanilla Mozilla without any Python extensions. If you can't build Mozilla without Python, you certainly will not be able to build it with Python :)

Once you have a successful build, simply enable the extension python/xpcom (if you wish to use the Python DOM work, also enable the extension python/dom). Once this extension has been enabled, rebuild Mozilla.

In most cases, this extension will be enabled by adding a line:

ac_add_options --enable-extensions=python/xpcom,default

(or if you are using the DOM work):

ac_add_options --enable-extensions=python/xpcom,python/dom,default

to your .mozconfig file.

Nominating the Python version

The configure script will attempt to locate a Python version to use. In most cases, all you need to do is ensure the Python version you wish to use is on your PATH before configuring Mozilla.

Alternatively, you can also set a PYTHON environment variable that points to a Python executable (not a directory - it must be a Python executable). If set, the configure script will use the Python pointed to by the variable.

You can confirm what Python is being used by carefully watching the configure process. You should see a message similar to:

Building PyXPCOM using Python-2.3 from c:/src/python-2.3-cvs

Windows/MSVC users: make sure you don't use cygwin's Python. It is likely to cause compilation errors later.

Linux and OS X

There are no special considerations for Linux. Below is an example build session on Linux, building the DOM_AGNOSTIC2_BRANCH branch.

cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co -r DOM_AGNOSTIC2_BRANCH mozilla/client.mk
cd mozilla
cat > ~/.mozconfig << "EOF"
mk_add_options MOZ_CO_PROJECT=suite
ac_add_options --enable-application=suite
ac_add_options --enable-default-toolkit=gtk2
ac_add_options --enable-xft
ac_add_options --enable-extensions=python/xpcom,python/dom,default
ac_add_options --disable-optimize
ac_add_options --enable-debug
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/suite-debug
EOF
make -f client.mk checkout
autoconf
make -f client.mk build

Note: If you are using any branch other than DOM_AGNOSTIC2_BRANCH, then the autoconf step can be omitted. If you do need to use it, make sure you're using Autoconf 2.13, not 2.59 or some other version. To force this behavior, on Gentoo you would prefix the autoconf command with WANT_AUTOCONF=2.13. On other distros simply run the binary autoconf-2.13 instead of autoconf.

Windows

There are no special build considerations for Windows. Follow the generic instructions above regarding --enable-extensions in your .mozconfig file.

Note that you'll get build problems if you try to make a debug build of Mozilla using the release version of Python. Building in this configuration is still possible, but not without certain workarounds (one of which is commenting out #define Py_DEBUG in <tt>pyconfig.h</tt>).

Testing PyXPCOM

First test your fresh PyXPCOM build from within Mozilla's runtime environment.

Linux and OS X:

cd suite-debug/dist/bin
export PYTHONPATH=$PYTHONPATH:$HOME/mozilla/suite-debug/dist/bin/python # Adjust this to your PyXPCOM build path
./run-mozilla.sh ./seamonkey -chrome chrome://pyxultest/content

Windows:

cd dist\bin
set PYTHONPATH=%PYTHONPATH%;C:\mozilla\dist\bin\python
seamonkey.exe -chrome chrome://pyxultest/content

A window with controls should pop up. Run the tests it contains.

In the same directory you can also perform a simple test of the Python xpcom module from a standalone Python environment.

Linux and OS X:

export MOZILLA_FIVE_HOME=$HOME/mozilla/suite-debug/dist/bin # Adjust this to your Mozilla build path
export LD_LIBRARY_PATH=$MOZILLA_FIVE_HOME
python -c 'from xpcom import components; print components.classes{{mediawiki.external('\"@mozilla.org/file/local;1\"')}}'

Windows:

set PATH=%PATH%;C:\mozilla\dist\bin
set MOZILLA_FIVE_HOME=C:\mozilla\dist\bin
set LD_LIBRARY_PATH=%MOZILLA_FIVE_HOME%
python -c "from xpcom import components; print components.classes{{mediawiki.external('\'@mozilla.org/file/local;1\'')}}"

You should see output similar to the following:

Type Manifest File: /home/you/mozilla/suite-debug/dist/bin/components/xpti.dat
<xpcom.components._Class instance at 0xb7c1be8c>
nsStringStats
 => mAllocCount:            431
 => mReallocCount:          270
 => mFreeCount:             423  --  LEAKED 8 !!!
 => mShareCount:            450
 => mAdoptCount:              0
 => mAdoptFreeCount:          0

If you see Python error messages instead, make sure $PYTHONPATH is still set the same as in the first test.

{{ wiki.languages( { "ja": "ja/Building_PyXPCOM" } ) }}

Revision Source

<p>
</p><p>These are the instructions for building <a href="en/PyXPCOM">PyXPCOM</a>.
</p>
<h3 name="Installing_Python"> Installing Python </h3>
<h4 name="PyXPCOM_Requirements"> PyXPCOM Requirements </h4>
<ul><li> PyXPCOM requires Python 2.3 or later (Python 2.3 and 2.4 have both been recently tested).
</li><li> PyXPCOM requires access to a shared Python library.
</li></ul>
<h4 name="Linux"> Linux </h4>
<p>For Linux users, the build script should check if you have a suitable shared library version of Python.  Jump to <a href="en/Building_PyXPCOM#Compiling_Mozilla">Compiling Mozilla</a>, and if you receive an error telling you a shared Python can not be located, then you'll need to compile Python with <code>--enable-shared</code> as outlined <a href="en/Building_PyXPCOM#Other_systems">below</a>.
</p>
<h5 name="Recent_Fedora_and_Ubuntu_builds"> Recent Fedora and Ubuntu builds </h5>
<p>These distributions generally have a shared Python already available.
</p>
<h5 name="Gentoo_systems"> Gentoo systems </h5>
<p>Building a shared Python library seems to only be possible with <code>python-2.3*</code> or later, so you'll need to upgrade if you're using <code>python-2.2*</code> or earlier. For ebuilds <code>python-2.3*</code> and later the shared library is built and installed by default.
</p>
<h4 name="Mac_OS_X"> Mac OS X </h4>
<p>For OS X 10.3 and 10.4 users, the Python 2.3 Framework is already available.  If you want to build against Python 2.4, you will need to build your own from <a class="external" href="http://www.python.org/download/">source</a>, build via <a class="external" href="http://darwinports.opendarwin.org/">DarwinPorts</a> or <a class="external" href="http://fink.sourceforge.net/">Fink</a>, or install either <a class="external" href="http://undefined.org/python/">MacPython</a> or <a class="external" href="http://www.ActiveState.com/">ActivePython</a>.  You can then skip to <a href="en/Building_PyXPCOM#Compiling_Mozilla">Compiling Mozilla</a>.  If you want to distribute your application, you might prefer to use the built-in Python 2.3 Framework at first, since embedding the Python Framework into an application bundle may take some non-standard customizations to the Python build scripts.
</p>
<h4 name="Windows"> Windows </h4>
<p>The official Python installer for Windows installs the shared version of the the library automatically, so Windows users can simply install Python and skip to <a href="en/Building_PyXPCOM#Compiling_Mozilla">Compiling Mozilla</a>.
</p>
<h4 name="Other_systems"> Other systems </h4>
<p>If you <i>don't</i> use any of the above systems, get the latest stable Python source tarball from <a class="external" href="http://python.org/download/">python.org</a> and do:
</p>
<pre>tar xjf Python-2.4.2.tar.bz2
cd Python-2.4.2
./configure --enable-shared --prefix=/usr  # Adjust --prefix to install over your current Python
make
sudo make install
</pre>
<h3 name="Compiling_Mozilla"> Compiling Mozilla </h3>
<p>You should be familiar with the <a class="external" href="http://www.mozilla.org/developer/">Developer Documentation</a> regarding <a href="en/Download_Mozilla_Source_Code">downloading the source code</a> and <a href="en/Build_Documentation">building applications</a> in the Mozilla code base (eg. Firefox, XulRunner).  
</p><p>Depending on your needs, you will want to pick an appropriate branch of the Mozilla CVS repository.
</p>
<ul><li>If you need the most stable code base, and only need Python in backend XPCOM classes, check out Mozilla from the MOZILLA_1_8_BRANCH or the MOZILLA_1_8_0_BRANCH in CVS and build it. Note that this branch may **not** automatically check if you have a suitable shared Python build on Linux systems - you must ensure this yourself.
</li></ul>
<ul><li>Use the Mozilla trunk.  This has the latest version of XPCOM, incorporating work done on the DOM branches (see below)
</li></ul>
<div class="note">
<p><b>Note</b>: A DOM_AGNOSTIC2_BRANCH may also be useful for testing - it has the same XPCOM as the trunk, but includes many other changes to make Python a first-class language in the DOM.  This branch has been merged with trunk on 2006-06-13, so use the HEAD for builds after that date.
</p>
</div>
<p>You can build PyXPCOM against any of the applications available in the CVS repository.  The example below shows building PyXPCOM for SeaMonkey, with Python DOM support.  You can also build against XULRunner on the HEAD or MOZILLA_1_8_0_BRANCH by removing "python/dom" from the options, and of course, changing the branch in the CVS checkout command.
</p>
<h4 name="All_Platforms">All Platforms</h4>
<p>On all platforms, you should first ensure you can build a vanilla Mozilla <i>without</i> any Python extensions.  If you can't build Mozilla without Python, you certainly will not be able to build it <i>with</i> Python :)
</p><p>Once you have a successful build, simply enable the extension <code>python/xpcom</code> (if you wish to use the Python DOM work, also enable the extension <code>python/dom</code>).  Once this extension has been enabled, rebuild Mozilla.
</p><p>In most cases, this extension will be enabled by adding a line:
</p>
<dl><dd><pre></pre></dd><dd>ac_add_options --enable-extensions=python/xpcom,default
</dd></dl>

<p>(or if you are using the DOM work):
</p>
<dl><dd><pre></pre></dd><dd>ac_add_options --enable-extensions=python/xpcom,python/dom,default
</dd></dl>

<p>to your <code>.mozconfig</code> file.
</p>
<h5 name="Nominating_the_Python_version">Nominating the Python version</h5>
<p>The configure script will attempt to locate a Python version to use.  In most cases, all you need to do is ensure the Python version you wish to use is on your PATH before configuring Mozilla.
</p><p>Alternatively, you can also set a <code>PYTHON</code> environment variable that points to a Python executable (not a directory - it must be a Python executable).  If set, the configure script will use the Python pointed to by the variable.
</p><p>You can confirm what Python is being used by carefully watching the configure process.  You should see a message similar to:
</p>
<pre class="eval">Building PyXPCOM using Python-2.3 from c:/src/python-2.3-cvs
</pre>
<p>Windows/MSVC users: make sure you don't use cygwin's Python. It is likely to cause compilation errors later. 
</p>
<h4 name="Linux_and_OS_X">Linux and OS X</h4>
<p>There are no special considerations for Linux. Below is an example build session on Linux, building the DOM_AGNOSTIC2_BRANCH branch.
</p>
<dl><dd><pre></pre></dd><dd>cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co -r DOM_AGNOSTIC2_BRANCH mozilla/client.mk
</dd><dd>cd mozilla
</dd><dd>cat &gt; ~/.mozconfig &lt;&lt; "EOF"
</dd><dd>mk_add_options MOZ_CO_PROJECT=suite
</dd><dd>ac_add_options --enable-application=suite
</dd><dd>ac_add_options --enable-default-toolkit=gtk2
</dd><dd>ac_add_options --enable-xft
</dd><dd>ac_add_options --enable-extensions=python/xpcom,python/dom,default
</dd><dd>ac_add_options --disable-optimize
</dd><dd>ac_add_options --enable-debug
</dd><dd>mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/suite-debug
</dd><dd>EOF
</dd><dd>make -f client.mk checkout
</dd><dd>autoconf
</dd><dd>make -f client.mk build
</dd></dl>

<div class="note">
<p><b>Note</b>: If you are using any branch other than DOM_AGNOSTIC2_BRANCH, then the <code>autoconf</code> step can be omitted.  If you do need to use it, make sure you're using Autoconf 2.13, not 2.59 or some other version. To force this behavior, on Gentoo you would prefix the <code>autoconf</code> command with <code>WANT_AUTOCONF=2.13</code>. On other distros simply run the binary <code>autoconf-2.13</code> instead of <code>autoconf</code>.
</p>
</div>
<h4 name="Windows_2">Windows</h4>
<p>There are no special build considerations for Windows.  Follow the generic instructions above regarding <code>--enable-extensions</code> in your <code>.mozconfig</code> file.
</p><p>Note that you'll get build problems if you try to make a debug build of Mozilla using the release version of Python. Building in this configuration is still possible, but not without certain workarounds (one of which is commenting out <code>#define Py_DEBUG</code> in <tt>pyconfig.h</tt>).
</p>
<h3 name="Testing_PyXPCOM"> Testing PyXPCOM </h3>
<p>First test your fresh PyXPCOM build from within Mozilla's runtime environment.
</p><p><i>Linux and OS X:</i>
</p>
<dl><dd><pre></pre></dd><dd>cd suite-debug/dist/bin
</dd><dd>export PYTHONPATH=$PYTHONPATH:$HOME/mozilla/suite-debug/dist/bin/python # Adjust this to your PyXPCOM build path
</dd><dd>./run-mozilla.sh ./seamonkey -chrome chrome://pyxultest/content
</dd></dl>

<p><i>Windows:</i>
</p>
<dl><dd><pre></pre></dd><dd>cd dist\bin
</dd><dd>set PYTHONPATH=%PYTHONPATH%;C:\mozilla\dist\bin\python
</dd><dd>seamonkey.exe -chrome chrome://pyxultest/content
</dd></dl>

<p>A window with controls should pop up. Run the tests it contains.
</p><p>In the same directory you can also perform a simple test of the Python <code>xpcom</code> module from a standalone Python environment.
</p><p><i>Linux and OS X:</i>
</p>
<dl><dd><pre></pre></dd><dd>export MOZILLA_FIVE_HOME=$HOME/mozilla/suite-debug/dist/bin # Adjust this to your Mozilla build path
</dd><dd>export LD_LIBRARY_PATH=$MOZILLA_FIVE_HOME
</dd><dd>python -c 'from xpcom import components; print components.classes{{mediawiki.external('\"@mozilla.org/file/local;1\"')}}'
</dd></dl>

<p><i>Windows:</i>
</p>
<dl><dd><pre></pre></dd><dd>set PATH=%PATH%;C:\mozilla\dist\bin
</dd><dd>set MOZILLA_FIVE_HOME=C:\mozilla\dist\bin
</dd><dd>set LD_LIBRARY_PATH=%MOZILLA_FIVE_HOME%
</dd><dd>python -c "from xpcom import components; print components.classes{{mediawiki.external('\'@mozilla.org/file/local;1\'')}}"
</dd></dl>

<p>You should see output similar to the following:
</p>
<pre>Type Manifest File: /home/you/mozilla/suite-debug/dist/bin/components/xpti.dat
&lt;xpcom.components._Class instance at 0xb7c1be8c&gt;
nsStringStats
 =&gt; mAllocCount:            431
 =&gt; mReallocCount:          270
 =&gt; mFreeCount:             423  --  LEAKED 8 !!!
 =&gt; mShareCount:            450
 =&gt; mAdoptCount:              0
 =&gt; mAdoptFreeCount:          0
</pre>
<p>If you see Python error messages instead, make sure <code>$PYTHONPATH</code> is still set the same as in the first test.
</p>{{ wiki.languages( { "ja": "ja/Building_PyXPCOM" } ) }}
Revert to this revision