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>