← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/extensions/python/xpcom/doc/configure.html

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

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