| 1 | <html>
|
|---|
| 2 | <!-- ***** BEGIN LICENSE BLOCK *****
|
|---|
| 3 | - Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|---|
| 4 | -
|
|---|
| 5 | - The contents of this file are subject to the Mozilla Public License Version
|
|---|
| 6 | - 1.1 (the "License"); you may not use this file except in compliance with
|
|---|
| 7 | - the License. You may obtain a copy of the License at
|
|---|
| 8 | - http://www.mozilla.org/MPL/
|
|---|
| 9 | -
|
|---|
| 10 | - Software distributed under the License is distributed on an "AS IS" basis,
|
|---|
| 11 | - WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|---|
| 12 | - for the specific language governing rights and limitations under the
|
|---|
| 13 | - License.
|
|---|
| 14 | -
|
|---|
| 15 | - The Original Code is PyXPCOM.
|
|---|
| 16 | -
|
|---|
| 17 | - The Initial Developer of the Original Code is
|
|---|
| 18 | - ActiveState Tool Corporation.
|
|---|
| 19 | - Portions created by the Initial Developer are Copyright (C) 2000-2001
|
|---|
| 20 | - the Initial Developer. All Rights Reserved.
|
|---|
| 21 | -
|
|---|
| 22 | - Contributor(s):
|
|---|
| 23 | -
|
|---|
| 24 | - Alternatively, the contents of this file may be used under the terms of
|
|---|
| 25 | - either the GNU General Public License Version 2 or later (the "GPL"), or
|
|---|
| 26 | - the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|---|
| 27 | - in which case the provisions of the GPL or the LGPL are applicable instead
|
|---|
| 28 | - of those above. If you wish to allow use of your version of this file only
|
|---|
| 29 | - under the terms of either the GPL or the LGPL, and not to allow others to
|
|---|
| 30 | - use your version of this file under the terms of the MPL, indicate your
|
|---|
| 31 | - decision by deleting the provisions above and replace them with the notice
|
|---|
| 32 | - and other provisions required by the LGPL or the GPL. If you do not delete
|
|---|
| 33 | - the provisions above, a recipient may use your version of this file under
|
|---|
| 34 | - the terms of any one of the MPL, the GPL or the LGPL.
|
|---|
| 35 | -
|
|---|
| 36 | - ***** END LICENSE BLOCK ***** -->
|
|---|
| 37 |
|
|---|
| 38 | <head>
|
|---|
| 39 | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|---|
| 40 | <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
|---|
| 41 | <meta name="ProgId" content="FrontPage.Editor.Document">
|
|---|
| 42 | <title>Configuring your Environment</title>
|
|---|
| 43 | </head>
|
|---|
| 44 |
|
|---|
| 45 | <body>
|
|---|
| 46 |
|
|---|
| 47 | <h1>Building, Configuring and Testing Python XPCOM Package</h1>
|
|---|
| 48 | <p>This document attempts to explain how to build, configure and test the
|
|---|
| 49 | Python XPCOM Package. This document assumes you have already successfully
|
|---|
| 50 | built
|
|---|
| 51 | Mozilla from source and your environment is currently set up for such a build -
|
|---|
| 52 | see the <a href="http://www.mozilla.org/build/">Mozilla build documentation</a>
|
|---|
| 53 | for more information.</p>
|
|---|
| 54 | <p>PyXPCOM can be built on Windows using either the <i>nmake makefile.win</i>
|
|---|
| 55 | process, or the <i>configure; gmake</i> process used by Linux.</p>
|
|---|
| 56 | <h2>configure; gmake Instructions</h2>
|
|---|
| 57 | <h3>Preparing for the build</h3>
|
|---|
| 58 | <ul>
|
|---|
| 59 | <li>Apply the patch in <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=129216">bugzilla
|
|---|
| 60 | bug 129216</a>. (If this bug is marked as "FIXED", it probably
|
|---|
| 61 | means there is no need to apply the patch and that these docs are out of
|
|---|
| 62 | date)</li>
|
|---|
| 63 | <li>On Linux, you must have Python built for dynamic linking. <a href="http://aspn.activestate.com/ASPN/Python">ActivePython</a>
|
|---|
| 64 | 2.1 is one such build.</li>
|
|---|
| 65 | <li>On Windows, you must have a Python source tree installed and built.
|
|---|
| 66 | Patches gratefully accepted that allow an installed Python to be used (it
|
|---|
| 67 | should not be hard!)</li>
|
|---|
| 68 | <li>Ensure the Python interpreter you wish to use is on your path, such that
|
|---|
| 69 | "python" will execute it correctly. The configure process
|
|---|
| 70 | uses this to locate the Python support files.</li>
|
|---|
| 71 | </ul>
|
|---|
| 72 | <h3>Building</h3>
|
|---|
| 73 | <ul>
|
|---|
| 74 | <li>From the top-level Mozilla directory, execute <i>./configure
|
|---|
| 75 | --enable-extensions=python/xpcom</i>. As per the Mozilla build
|
|---|
| 76 | instructions, you may add this option to your <i>.mozconfig</i> file.
|
|---|
| 77 | If you wish to enable debugging, just enable it as you would normally for
|
|---|
| 78 | Mozilla; PyXPCOM will pick up the same settings.<br>
|
|---|
| 79 | (On Windows you will need to execute <i>sh ./configure ...</i> if running
|
|---|
| 80 | from a Command Prompt. See the <a href="http://www.mozilla.org/build/win32.html#ss2.2b">Mozilla
|
|---|
| 81 | win32 specific gmake build instructions</a> for more details.</li>
|
|---|
| 82 | <li>Build the Mozilla tree as normal; PyXPCOM will automatically be
|
|---|
| 83 | built. Alternatively, change to the top-level PyXPCOM directory and
|
|---|
| 84 | execute <i>gmake</i> in that directory.</li>
|
|---|
| 85 | </ul>
|
|---|
| 86 | <h2>PyXPCOM outside Mozilla</h2>
|
|---|
| 87 | <p>When you are using PyXPCOM from inside mozilla, no additional configuration
|
|---|
| 88 | options should be necessary. However, if you wish to use PyXPCOM from
|
|---|
| 89 | stand-alone Python (ie, so you can write simple Python scripts that can be
|
|---|
| 90 | executed normally and use XPCOM), then additional environment variables must be
|
|---|
| 91 | setup.</p>
|
|---|
| 92 | <ul>
|
|---|
| 93 | <li><a name="PYTHONPATH"><b>PYTHONPATH</b></a> - <tt>PYTHONPATH</tt> needs to
|
|---|
| 94 | be set appropriately. You must manually ensure that the <i>mozilla/dist/bin/python</i>
|
|---|
| 95 | directory (which is where PyXPCOM was installed during the build process) is
|
|---|
| 96 | listed. Note that when PyXPCOM is used from within Mozilla (or any
|
|---|
| 97 | other xpcom process), this path will automatically be added to sys.path.
|
|---|
| 98 | It is only when Python directly uses xpcom that this step is necessary.<br>
|
|---|
| 99 | If anything is wrong here you should get a normal <tt>ImportError</tt>.</li>
|
|---|
| 100 | </ul>
|
|---|
| 101 | <blockquote>
|
|---|
| 102 | <p>Note that on Windows, the PYTHONPATH is generally maintained in the
|
|---|
| 103 | Registry; however, you can set this variable at a DOS prompt, and it will still be
|
|---|
| 104 | added to the core PYTHONPATH.
|
|---|
| 105 | </blockquote>
|
|---|
| 106 | <ul>
|
|---|
| 107 | <li><b><a name="PATH">PATH</a>, LD_LIBRARY_PATH, etc</b> - On Windows, you
|
|---|
| 108 | must ensure that the Mozilla bin directory is listed on your PATH, or that
|
|---|
| 109 | you execute your scripts with the Mozilla bin directory as the current
|
|---|
| 110 | directory.<br>
|
|---|
| 111 | On Linux, you must set your PATH and LD_LIBRARY_PATH variables
|
|---|
| 112 | appropriately. However, you may find it simpler and easier to use the <i>run-mozilla.sh</i>
|
|---|
| 113 | script in the Mozilla bin directory. For example, changing to the
|
|---|
| 114 | Mozilla bin directory and executing:<br>
|
|---|
| 115 | <i>./run-mozilla.sh python ~/src/mozilla/extensions/python/xpcom/test/regrtest.py</i><br>
|
|---|
| 116 | should setup a correct environment and execute the PyXPCOM test suite.</li>
|
|---|
| 117 | </ul>
|
|---|
| 118 | <h2><a name="RunningTheTests">Testing your Setup</a></h2>
|
|---|
| 119 | <p>The Python XPCOM Package has a complete test suite.</p>
|
|---|
| 120 | <p>In the rest of this section, we walk through some simpler tests a step at a time,
|
|---|
| 121 | to help diagnose any problems.</p>
|
|---|
| 122 | <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
|
|---|
| 123 | this using the PyXPCOM package stand-alone.</p>
|
|---|
| 124 | <p><b>Note:</b> On Windows, if you use a debug build of Mozilla (i.e., in <i>dist\WIN32_D.OBJ\bin)</i>,
|
|---|
| 125 | you <b>must</b> use <i>python_d.exe</i>; if you use a release build (i.e., in
|
|---|
| 126 | a <i>dist\WIN32_O.OBJ\bin</i> directory), you must use <i>python.exe</i>.
|
|---|
| 127 | <i>makefile.stupid.win</i> handles this automatically.</p>
|
|---|
| 128 | <p>To test your setup:</p>
|
|---|
| 129 | <ol>
|
|---|
| 130 | <li>Start Python, and check<br>
|
|---|
| 131 | >>> <i>import xpcom</i><br>
|
|---|
| 132 | works. If not, <a href="#PYTHONPATH">check your PYTHONPATH</a> - the
|
|---|
| 133 | main PyXPCOM package can not be located. Also check your <a href="#PATH">PATH</a>,
|
|---|
| 134 | and if you are on Linux, remember that executing ./run-mozilla.sh python is
|
|---|
| 135 | the easiest way.</li>
|
|---|
| 136 | <li>Check<i><br>
|
|---|
| 137 | >>> import xpcom._xpcom</i><br>
|
|---|
| 138 |
|
|---|
| 139 | works. If not, then most likely your <a href="#PATH">Mozilla
|
|---|
| 140 | directory is not on your path</a>, or something is wrong with <i>_xpcom(_d).pyd/_xpcommodule.so</i>.</li>
|
|---|
| 141 |
|
|---|
| 142 | <li>Next run a simple test: <i>test/test_misc.py</i>. With a Windows debug build, the command may look like:<br>
|
|---|
| 143 | <i>C:\Anywhere> python_d \src\python\xpcom\test\test_misc.py<br>
|
|---|
| 144 | </i>or on Linux<br>
|
|---|
| 145 | <i>/home/user/src/mozilla/dist/bin$ python /home/user/src/python/xpcom/test/test_misc.py</i></li>
|
|---|
| 146 | </ol>
|
|---|
| 147 | <p>If you can't get this going, you won't get much further! (You may see a few
|
|---|
| 148 | errors - that is OK, as long as it appears something worked!). If
|
|---|
| 149 | everything looks OK, the
|
|---|
| 150 | next step is to register our test component and run our full test suite.</p>
|
|---|
| 151 | <h2><a name="Registration">Registering the Loader and Test Component</a></h2>
|
|---|
| 152 | <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
|
|---|
| 153 | document</a>. Do this only once, regardless of how many
|
|---|
| 154 | Python components you have. Then install the test component itself, and
|
|---|
| 155 | finally you can test it!</p>
|
|---|
| 156 | <h3>Registering the Python Loader and Component</h3>
|
|---|
| 157 | <p>To register the Python Loader and Component:</p>
|
|---|
| 158 | <ol>
|
|---|
| 159 | <li>Ensure the build process has put <i>pyloader.dll </i>(or <i>modpyloader.so</i>
|
|---|
| 160 | for Unix), and the files <i> py_test_component.py </i> and <i> py_test_component.idl</i> into
|
|---|
| 161 | the Mozilla <i>bin/components</i> directory. If not, copy the files
|
|---|
| 162 | there manually.</li>
|
|---|
| 163 | <li>Run <i>regxpcom </i>(or .<i>/run-mozilla.sh ./regxpcom</i> if appropriate). <i>regxpcom</i> is a standard Mozilla
|
|---|
| 164 | executable, found in the <i>bin</i> directory, that detects the new DLL and
|
|---|
| 165 | .py
|
|---|
| 166 | files and registers them accordingly. You should
|
|---|
| 167 | see a few messages that include the following:</li>
|
|---|
| 168 | </ol>
|
|---|
| 169 | <blockquote>
|
|---|
| 170 | <pre>Registering: PythonComponentLoader
|
|---|
| 171 | Registered 1 Python components in pyloader.dll
|
|---|
| 172 | nsNativeComponentLoader: autoregistering succeeded
|
|---|
| 173 | Auto-registering all Python components in F:\src\mozilla\dist\WIN32_D.OBJ\bin\components
|
|---|
| 174 | Registering: PythonTestComponent
|
|---|
| 175 | Registered 1 Python components in py_test_component.py</pre>
|
|---|
| 176 | </blockquote>
|
|---|
| 177 | <p>If so (or you see no message at all), you are ready to run the test suite.</p>
|
|---|
| 178 | <p><b>Note</b>: If you execute this same step a second time, you will not
|
|---|
| 179 | see any of the above mentioned messages. XPCOM knows that nothing has
|
|---|
| 180 | changed since you last ran <i>regxpcom</i>, so nothing is registered. If
|
|---|
| 181 | you do not see these messages the first time you run it, there is the
|
|---|
| 182 | possibility that some other process, possibly the build process, has already
|
|---|
| 183 | executed this step.</p>
|
|---|
| 184 | <h2><b>Running the Test Suite</b></h2>
|
|---|
| 185 | <p>Before running the test suite, you should change to the <i>mozilla/xpcom/sample</i>
|
|---|
| 186 | directory and build it. This will build and install a sample component
|
|---|
| 187 | which is used by the test suite. If you do not have this component
|
|---|
| 188 | available, some of the Python tests will fail.</p>
|
|---|
| 189 |
|
|---|
| 190 | <p>To run the test suite, run <i>xpcom/test/regrtest.py.</i> This runs the
|
|---|
| 191 | tests and ensures that the test output is as expected. If all tests
|
|---|
| 192 | pass, you have a fully functioning Python XPCOM package. Enjoy!</p>
|
|---|
| 193 |
|
|---|
| 194 | </body>
|
|---|
| 195 |
|
|---|
| 196 | </html>
|
|---|
