add --shared
[pylucene.git] / doc / jcc / documentation / install.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <head>
4 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <meta content="Apache Forrest" name="Generator">
6 <meta name="Forrest-version" content="0.8">
7 <meta name="Forrest-skin-name" content="pelt">
8 <title>JCC Installation Instructions</title>
9 <link type="text/css" href="../../skin/basic.css" rel="stylesheet">
10 <link media="screen" type="text/css" href="../../skin/screen.css" rel="stylesheet">
11 <link media="print" type="text/css" href="../../skin/print.css" rel="stylesheet">
12 <link type="text/css" href="../../skin/profile.css" rel="stylesheet">
13 <script src="../../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../../skin/fontsize.js" language="javascript" type="text/javascript"></script>
14 <link rel="shortcut icon" href="../../">
15 </head>
16 <body onload="init()">
17 <script type="text/javascript">ndeSetTextSize();</script>
18 <div id="top">
19 <!--+
20     |breadtrail
21     +-->
22 <div class="breadtrail">
23 <a href="http://www.apache.org/">apache</a> &gt; <a href="http://lucene.apache.org/">lucene</a><script src="../../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
24 </div>
25 <!--+
26     |header
27     +-->
28 <div class="header">
29 <!--+
30     |start group logo
31     +-->
32 <div class="grouplogo">
33 <a href="http://lucene.apache.org/"><img class="logoImage" alt="Lucene" src="../../images/lucene_green_150.gif" title="Lucene Description"></a>
34 </div>
35 <!--+
36     |end group logo
37     +-->
38 <!--+
39     |start Project Logo
40     +-->
41 <div class="projectlogoA1">
42 <a href="http://lucene.apache.org/pylucene/"><img class="logoImage" alt="PyLucene" src="../../images/project.png" title="PyLucene Description"></a>
43 </div>
44 <!--+
45     |end Project Logo
46     +-->
47 <!--+
48     |start Tabs
49     +-->
50 <ul id="tabs">
51 <li>
52 <a class="unselected" href="../../index.html">PyLucene</a>
53 </li>
54 <li class="current">
55 <a class="selected" href="../../jcc/index.html">JCC</a>
56 </li>
57 </ul>
58 <!--+
59     |end Tabs
60     +-->
61 </div>
62 </div>
63 <div id="main">
64 <div id="publishedStrip">
65 <!--+
66     |start Subtabs
67     +-->
68 <div id="level2tabs"></div>
69 <!--+
70     |end Endtabs
71     +-->
72 <script type="text/javascript"><!--
73 document.write("Last Published: " + document.lastModified);
74 //  --></script>
75 </div>
76 <!--+
77     |breadtrail
78     +-->
79 <div class="breadtrail">
80
81              &nbsp;
82            </div>
83 <!--+
84     |start Menu, mainarea
85     +-->
86 <!--+
87     |start Menu
88     +-->
89 <div id="menu">
90 <div onclick="SwitchMenu('menu_selected_1.1', '../../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">JCC</div>
91 <div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
92 <div onclick="SwitchMenu('menu_1.1.1', '../../skin/')" id="menu_1.1.1Title" class="menutitle">About</div>
93 <div id="menu_1.1.1" class="menuitemgroup">
94 <div class="menuitem">
95 <a href="../../jcc/index.html" title="Welcome to JCC">Index</a>
96 </div>
97 </div>
98 <div onclick="SwitchMenu('menu_selected_1.1.2', '../../skin/')" id="menu_selected_1.1.2Title" class="menutitle" style="background-image: url('../../skin/images/chapter_open.gif');">Documentation</div>
99 <div id="menu_selected_1.1.2" class="selectedmenuitemgroup" style="display: block;">
100 <div class="menupage">
101 <div class="menupagetitle">Installation</div>
102 </div>
103 <div class="menuitem">
104 <a href="../../jcc/documentation/readme.html">Features</a>
105 </div>
106 <div class="menuitem">
107 <a href="../../jcc/documentation/javadoc/index.html">Javadoc</a>
108 </div>
109 </div>
110 </div>
111 <div id="credit"></div>
112 <div id="roundbottom">
113 <img style="display: none" class="corner" height="15" width="15" alt="" src="../../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
114 <!--+
115   |alternative credits
116   +-->
117 <div id="credit2"></div>
118 </div>
119 <!--+
120     |end Menu
121     +-->
122 <!--+
123     |start content
124     +-->
125 <div id="content">
126 <div title="Portable Document Format" class="pdflink">
127 <a class="dida" href="install.pdf"><img alt="PDF -icon" src="../../skin/images/pdfdoc.gif" class="skin"><br>
128         PDF</a>
129 </div>
130 <h1>JCC Installation Instructions</h1>
131 <div id="minitoc-area">
132 <ul class="minitoc">
133 <li>
134 <a href="#sources">Getting JCC's Source Code</a>
135 </li>
136 <li>
137 <a href="#build">Building JCC</a>
138 </li>
139 <li>
140 <a href="#requirements">Requirements</a>
141 </li>
142 <li>
143 <a href="#shared">Shared Mode: Support for the --shared Flag</a>
144 </li>
145 <li>
146 <a href="#mac">Notes for Mac OS X</a>
147 </li>
148 <li>
149 <a href="#linux">Notes for Linux</a>
150 </li>
151 <li>
152 <a href="#solaris">Notes for Solaris</a>
153 </li>
154 <li>
155 <a href="#windows">Notes for Windows</a>
156 </li>
157 <li>
158 <a href="#python">Notes for Python 2.3</a>
159 </li>
160 </ul>
161 </div>
162     
163 <a name="N1000D"></a><a name="sources"></a>
164 <h2 class="boxed">Getting JCC's Source Code</h2>
165 <div class="section">
166 <p>
167         JCC's source code is included with PyLucene's. If you've downloaded
168         the PyLucene source code already, JCC's is to be found in
169         the <span class="codefrag">jcc</span> subdirectory.
170       </p>
171 <p>
172         To get the JCC source code only from SVN use:<br>
173         
174 <span class="codefrag">$ svn co
175         http://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc jcc</span>
176       
177 </p>
178 </div>
179     
180 <a name="N10022"></a><a name="build"></a>
181 <h2 class="boxed">Building JCC</h2>
182 <div class="section">
183 <p>
184         JCC is a Python extension written in Python and C++. It requires a
185         Java Runtime Environment to operate as it uses Java's reflection
186         APIs to do its work. It is built and installed
187         via <span class="codefrag">distutils</span>
188         or <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>.
189       </p>
190 <ol>
191         
192 <li>
193           Edit <span class="codefrag">setup.py</span> and review that values in
194           the <span class="codefrag">INCLUDES</span>, <span class="codefrag">CFLAGS</span>,
195           <span class="codefrag">DEBUG_CFLAGS</span>, <span class="codefrag">LFLAGS</span>
196           and <span class="codefrag">JAVAC</span> are correct for your system. These values
197           are also going to be compiled into JCC's <span class="codefrag">config.py</span>
198           file and are going to be used by JCC when
199           invoking <span class="codefrag">distutils</span> or <span class="codefrag">setuptools</span> to
200           compile extensions it is generating code for.
201         </li>
202         
203 <li>
204           At the command line, enter:
205           <pre class="code">
206             $ python setup.py build
207             $ sudo python setup.py install
208           </pre>
209         
210 </li>
211       
212 </ol>
213 </div>
214     
215 <a name="N1005B"></a><a name="requirements"></a>
216 <h2 class="boxed">Requirements</h2>
217 <div class="section">
218 <p>
219         JCC requires a Java Development Kit to be present. It uses the Java
220         Native Invocation Interface and expects <span class="codefrag">&lt;jni.h&gt;</span>
221         and the Java libraries to be present at build and runtime.
222       </p>
223 <p>
224         JCC requires a C++ compiler. A recent C++ compiler for your
225         platform is expected to work as expected.
226       </p>
227 </div>
228     
229 <a name="N1006B"></a><a name="shared"></a>
230 <h2 class="boxed">Shared Mode: Support for the --shared Flag</h2>
231 <div class="section">
232 <p>
233         JCC includes a small runtime that keeps track of the Java VM and of
234         Java objects escaping it. Because there can be only one Java VM
235         embedded in a given process at a time, the JCC runtime must be
236         compiled as a shared library when more than one JCC-built Python
237         extension is going to be imported into a given Python process.
238       </p>
239 <p>
240         Shared mode depends on <span class="codefrag">setuptools</span>' capability of
241         building plain shared libraries (as opposed to shared libraries for
242         Python extensions).
243       </p>
244 <p>
245         Currently, shared mode is supported with <span class="codefrag">setuptools
246         0.6c7</span> and above out of the box on Mac OS X and Windows. On
247         Linux, a patch to <span class="codefrag">setuptools</span> needs to be applied
248         first. This patch is included in the JCC source distribution in
249         the <span class="codefrag">jcc/patches</span> directory, <span class="codefrag">patch.43</span>. This
250         patch was submitted to the <span class="codefrag">setuptools</span> project
251         via <a href="http://bugs.python.org/setuptools/issue43">issue
252         43</a>.
253       </p>
254 <p>
255         The <span class="codefrag">shared mode disabled</span> error reported during the
256         build of JCC's on Linux contains the exact instructions on how to
257         patch the <span class="codefrag">setuptools</span> installation
258         with <span class="codefrag">patch.43</span> on your system.
259       </p>
260 <p>
261         Shared mode is also required when embedding Python in a Java VM as
262         JCC's runtime shared library is used by the JVM to load JCC and
263         bootstrap the Python VM via the JNI.
264       </p>
265 <p>
266         When shared mode is not enabled, not supported
267         or <span class="codefrag">distutils</span> is used instead
268         of <span class="codefrag">setuptools</span>, static mode is used instead. The JCC
269         runtime code is statically linked with each JCC-built Python
270         extension and only one such extension can be used in a given Python
271         process at a time.
272       </p>
273 <p>
274         As setuptools grows its shared library building capability it is
275         expected that more operating systems should be supported with shared
276         mode in the future.
277       </p>
278 <p>
279         Shared mode can be forced off by building JCC with
280         the <span class="codefrag">NO_SHARED</span> environment variable set.
281       </p>
282 <p>
283         There are two defaults to consider here:
284       </p>
285 <ul>
286         
287 <li>
288           Is JCC built with shared mode support or not ?
289           <ul>
290             
291 <li>
292               By default, on Mac OS X and Windows this is the case.
293             </li>
294             
295 <li>
296               By default, on Linux, this is the case.
297               if <span class="codefrag">setuptools</span> is patched.
298             </li>
299             
300 <li>
301               On other operating systems shared mode support is off by
302               default - not supported - because shared mode depends on
303               <span class="codefrag">setuptools</span>'s capability of building a regular
304               shared library which is still an experimental feature.
305             </li>
306           
307 </ul>
308         
309 </li>
310         
311 <li>
312           Is a JCC-built Python extension built with shared mode ?<br>
313           By default, no, shared mode is enabled only with
314           the <span class="codefrag">--shared</span> command line argument.
315         </li>
316       
317 </ul>
318 </div>
319     
320 <a name="N100D8"></a><a name="mac"></a>
321 <h2 class="boxed">Notes for Mac OS X</h2>
322 <div class="section">
323 <p>
324         On Mac OS X, Java is installed by Apple's setup as a framework. The
325         values in <span class="codefrag">setup.py</span> for <span class="codefrag">INCLUDES</span>
326         and <span class="codefrag">LFLAGS</span> for <span class="codefrag">darwin</span> should be correct
327         and ready to use.
328       </p>
329 <p>
330         However, if you intend to use the 'system' Python from a Java VM
331         on Mac OS X -- Python embedded in Java --
332         you will need to add the flags <span class="codefrag">"-framework", "Python"</span>
333         to the <span class="codefrag">LFLAGS</span> value.
334       </p>
335 </div>
336     
337 <a name="N100F7"></a><a name="linux"></a>
338 <h2 class="boxed">Notes for Linux</h2>
339 <div class="section">
340 <p>
341         JCC has been built and tested on a variety of Linux distributions,
342         32- and 64-bit. Getting the java configuration correct is important
343         and is done differently for every distribution.<br>
344         For example:
345       </p>
346 <ul>
347         
348 <li>
349           on Ubuntu, to install Java 5, these commands may be used:
350           <pre class="code">
351             $ sudo apt-get install sun-java5-jdk
352             $ sudo update-java-alternatives -s java-1.5.0-sun
353           </pre>
354           The samples flags for Linux in JCC's setup.py should be close to
355           correct.
356         </li>
357         
358 <li>
359           on Gentoo, the <span class="codefrag">java-config</span> utility should be used to
360           locate, and possibly change, the default java installation.
361           The sample flags for Linux in JCC's <span class="codefrag">setup.py</span> should
362           be changed to reflect the root of the Java installation which may
363           be obtained via:
364           <pre class="code">
365             $ java-config -O
366           </pre>
367         
368 </li>
369         
370 </ul>
371 <p>
372         See earlier section about <a href="#shared">Shared Mode</a> for
373         Linux support.
374       </p>
375 </div>
376     
377 <a name="N10121"></a><a name="solaris"></a>
378 <h2 class="boxed">Notes for Solaris</h2>
379 <div class="section">
380 <p>
381         At this time, JCC has been built and tested only on Solaris 11 with Sun
382         Studio C++ 12, Java 1.6 and Python 2.4.
383       </p>
384 <p>
385         Because JCC is written in C++, Python's <span class="codefrag">distutils</span> must
386         be nudged a bit to invoke the correct compiler. Sun Studio's C
387         compiler is called <span class="codefrag">cc</span> while its C++ compiler is
388         called <span class="codefrag">CC</span>. To build JCC, use the following shell
389         command to ensure that the C++ compiler is used:
390       </p>
391 <pre class="code">
392         $ CC=CC python setup.py build
393       </pre>
394 <p>
395         Shared mode is not currently implemented for
396         Solaris, <span class="codefrag">setuptools</span> needs to be taught how to build
397         plain shared libraries on Solaris first. 
398       </p>
399 </div>
400     
401 <a name="N10141"></a><a name="windows"></a>
402 <h2 class="boxed">Notes for Windows</h2>
403 <div class="section">
404 <p>
405         At this time, JCC has been built and tested on Win2k and WinXP with
406         a variety of Python and Java versions.
407       </p>
408 <ul>
409         
410 <li>
411           Adding the Python directory to <span class="codefrag">PATH</span> is recommended.
412         </li>
413         
414 <li>
415           Adding the Java directories containing the necessary DLLs and to
416           <span class="codefrag">PATH</span> is a must.
417         </li>
418         
419 <li>
420           Adding the directory containing <span class="codefrag">javac.exe</span>
421           to <span class="codefrag">PATH</span> is required for shared mode (enabled by
422           default if <span class="codefrag">setuptools &gt;= 0.6c7</span> is found to be
423           installed).
424         </li>
425       
426 </ul>
427 </div>
428     
429 <a name="N10166"></a><a name="python"></a>
430 <h2 class="boxed">Notes for Python 2.3</h2>
431 <div class="section">
432 <p>
433         To use JCC with Python 2.3, setuptools is required
434       </p>
435 <ol>
436         
437 <li>
438           download <a href="http://pypi.python.org/pypi/setuptools">setuptools</a>.
439         </li>
440         
441 <li>
442           edit the downloaded <span class="codefrag">setuptools</span> egg file to use
443           python2.3 instead of python2.4.
444         </li>
445         
446 <li>
447           At the command line, run:<br>
448           
449 <span class="codefrag">$ sudo sh setuptools-0.6c7-py2.4.egg</span>
450         
451 </li>
452       
453 </ol>
454 </div>
455   
456 </div>
457 <!--+
458     |end content
459     +-->
460 <div class="clearboth">&nbsp;</div>
461 </div>
462 <div id="footer">
463 <!--+
464     |start bottomstrip
465     +-->
466 <div class="lastmodified">
467 <script type="text/javascript"><!--
468 document.write("Last Published: " + document.lastModified);
469 //  --></script>
470 </div>
471 <div class="copyright">
472         Copyright &copy;
473          2009-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
474 </div>
475 <!--+
476     |end bottomstrip
477     +-->
478 </div>
479 </body>
480 </html>