16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<!-- ***** BEGIN LICENSE BLOCK *****
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The contents of this file are subject to the Mozilla Public License Version
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - 1.1 (the "License"); you may not use this file except in compliance with
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the License. You may obtain a copy of the License at
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Software distributed under the License is distributed on an "AS IS" basis,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - for the specific language governing rights and limitations under the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The Original Code is PyXPCOM.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - The Initial Developer of the Original Code is
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - ActiveState Tool Corporation.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Portions created by the Initial Developer are Copyright (C) 2000-2001
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the Initial Developer. All Rights Reserved.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Contributor(s):
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - Alternatively, the contents of this file may be used under the terms of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - either the GNU General Public License Version 2 or later (the "GPL"), or
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - in which case the provisions of the GPL or the LGPL are applicable instead
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - of those above. If you wish to allow use of your version of this file only
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - under the terms of either the GPL or the LGPL, and not to allow others to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - use your version of this file under the terms of the MPL, indicate your
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - decision by deleting the provisions above and replace them with the notice
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - and other provisions required by the LGPL or the GPL. If you do not delete
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the provisions above, a recipient may use your version of this file under
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - the terms of any one of the MPL, the GPL or the LGPL.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync - ***** END LICENSE BLOCK ***** -->
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<meta name="ProgId" content="FrontPage.Editor.Document">
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<h1>Building, Configuring and Testing Python XPCOM Package</h1>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>This document attempts to explain how to build, configure and test the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython XPCOM Package. This document assumes you have already successfully
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncMozilla from source and your environment is currently set up for such a build -
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsee the <a href="http://www.mozilla.org/build/">Mozilla build documentation</a>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncfor more information.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>PyXPCOM can be built on Windows using either the <i>nmake makefile.win</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncprocess, or the <i>configure; gmake</i> process used by Linux.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Apply the patch in <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=129216">bugzilla
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync bug 129216</a>. (If this bug is marked as "FIXED", it probably
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync means there is no need to apply the patch and that these docs are out of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>On Linux, you must have Python built for dynamic linking. <a href="http://aspn.activestate.com/ASPN/Python">ActivePython</a>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync 2.1 is one such build.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>On Windows, you must have a Python source tree installed and built.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync Patches gratefully accepted that allow an installed Python to be used (it
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync should not be hard!)</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Ensure the Python interpreter you wish to use is on your path, such that
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync "python" will execute it correctly. The configure process
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync uses this to locate the Python support files.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>From the top-level Mozilla directory, execute <i>/configure
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync --enable-extensions=python/xpcom</i>. As per the Mozilla build
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync instructions, you may add this option to your <i>.mozconfig</i> file.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync If you wish to enable debugging, just enable it as you would normally for
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync Mozilla; PyXPCOM will pick up the same settings.<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync (On Windows you will need to execute <i>sh /configure ...</i> if running
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync from a Command Prompt. See the <a href="http://www.mozilla.org/build/win32.html#ss2.2b">Mozilla
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync win32 specific gmake build instructions</a> for more details.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Build the Mozilla tree as normal; PyXPCOM will automatically be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync built. Alternatively, change to the top-level PyXPCOM directory and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>When you are using PyXPCOM from inside mozilla, no additional configuration
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncoptions should be necessary. However, if you wish to use PyXPCOM from
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncstand-alone Python (ie, so you can write simple Python scripts that can be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncexecuted normally and use XPCOM), then additional environment variables must be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li><a name="PYTHONPATH"><b>PYTHONPATH</b></a> - <tt>PYTHONPATH</tt> needs to
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync be set appropriately. You must manually ensure that the <i>mozilla/dist/bin/python</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync directory (which is where PyXPCOM was installed during the build process) is
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync listed. Note that when PyXPCOM is used from within Mozilla (or any
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync other xpcom process), this path will automatically be added to sys.path.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync It is only when Python directly uses xpcom that this step is necessary.<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync If anything is wrong here you should get a normal <tt>ImportError</tt>.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <p>Note that on Windows, the PYTHONPATH is generally maintained in the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync Registry; however, you can set this variable at a DOS prompt, and it will still be
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncadded to the core PYTHONPATH.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync</blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li><b><a name="PATH">PATH</a>, LD_LIBRARY_PATH, etc</b> - On Windows, you
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync must ensure that the Mozilla bin directory is listed on your PATH, or that
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync you execute your scripts with the Mozilla bin directory as the current
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync directory.<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync On Linux, you must set your PATH and LD_LIBRARY_PATH variables
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync appropriately. However, you may find it simpler and easier to use the <i>run-mozilla.sh</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync script in the Mozilla bin directory. For example, changing to the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync Mozilla bin directory and executing:<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <i>/run-mozilla.sh python ~/src/mozilla/extensions/python/xpcom/test/regrtest.py</i><br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync should setup a correct environment and execute the PyXPCOM test suite.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<h2><a name="RunningTheTests">Testing your Setup</a></h2>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>The Python XPCOM Package has a complete test suite.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>In the rest of this section, we walk through some simpler tests a step at a time,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncto help diagnose any problems.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Note:</b> We recommend you do all your testing outside of <i> mozilla.exe</i>; it is far simpler to test all of
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncthis using the PyXPCOM package stand-alone.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Note:</b> On Windows, if you use a debug build of Mozilla (i.e., in <i>dist\WIN32_D.OBJ\bin)</i>,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync you <b>must</b> use <i>python_d.exe</i>; if you use a release build (i.e., in
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync a <i>dist\WIN32_O.OBJ\bin</i> directory), you must use <i>python.exe</i>.
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<i>makefile.stupid.win</i> handles this automatically.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync works. If not, <a href="#PYTHONPATH">check your PYTHONPATH</a> - the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync main PyXPCOM package can not be located. Also check your <a href="#PATH">PATH</a>,
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync and if you are on Linux, remember that executing /run-mozilla.sh python is
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync the easiest way.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncworks. If not, then most likely your <a href="#PATH">Mozilla
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync directory is not on your path</a>, or something is wrong with <i>_xpcom(_d).pyd/_xpcommodule.so</i>.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Next run a simple test: <i>test/test_misc.py</i>. With a Windows debug build, the command may look like:<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <i>C:\Anywhere> python_d \src\python\xpcom\test\test_misc.py<br>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <i>/home/user/src/mozilla/dist/bin$ python /home/user/src/python/xpcom/test/test_misc.py</i></li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>If you can't get this going, you won't get much further! (You may see a few
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncerrors - that is OK, as long as it appears something worked!). If
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynceverything looks OK, the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncnext step is to register our test component and run our full test suite.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<h2><a name="Registration">Registering the Loader and Test Component</a></h2>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>First register the generic Python loader. For instructions, see the <a href="file:///F:/src/as/Komodo/src/pyxpcom/xpcom/doc/architecture.html">architecture
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncdocument</a>. Do this only once, regardless of how many
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncPython components you have. Then install the test component itself, and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncfinally you can test it!</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<h3>Registering the Python Loader and Component</h3>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Ensure the build process has put <i>pyloader.dll </i>(or <i>modpyloader.so</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync for Unix), and the files <i> py_test_component.py </i> and <i> py_test_component.idl</i> into
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync the Mozilla <i>bin/components</i> directory. If not, copy the files
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync there manually.</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <li>Run <i>regxpcom </i>(or .<i>/run-mozilla.sh /regxpcom</i> if appropriate). <i>regxpcom</i> is a standard Mozilla
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync executable, found in the <i>bin</i> directory, that detects the new DLL and
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync files and registers them accordingly. You should
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync see a few messages that include the following:</li>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync <pre>Registering: PythonComponentLoader
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncRegistered 1 Python components in pyloader.dll
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncnsNativeComponentLoader: autoregistering succeeded
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncAuto-registering all Python components in F:\src\mozilla\dist\WIN32_D.OBJ\bin\components
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncRegistering: PythonTestComponent
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncRegistered 1 Python components in py_test_component.py</pre>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync</blockquote>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>If so (or you see no message at all), you are ready to run the test suite.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p><b>Note</b>: If you execute this same step a second time, you will not
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncsee any of the above mentioned messages. XPCOM knows that nothing has
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncchanged since you last ran <i>regxpcom</i>, so nothing is registered. If
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncyou do not see these messages the first time you run it, there is the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncpossibility that some other process, possibly the build process, has already
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncexecuted this step.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>Before running the test suite, you should change to the <i>mozilla/xpcom/sample</i>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncdirectory and build it. This will build and install a sample component
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncwhich is used by the test suite. If you do not have this component
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncavailable, some of the Python tests will fail.</p>
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsync<p>To run the test suite, run <i>xpcom/test/regrtest.py.</i> This runs the
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsynctests and ensures that the test output is as expected. If all tests
16a8d09569a2ebd598cef72fa605be6fb4563607vboxsyncpass, you have a fully functioning Python XPCOM package. Enjoy!</p>