Install JCC

Install JCC

Getting JCC's Source Code

JCC's source code is included with PyLucene's. If you've downloadedthe PyLucene source code already, JCC's is to be found inthe jcc subdirectory.

To get the JCC source code only from SVN use:
$ svn cohttp://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc jcc

Building JCC

JCC is a Python extension written in Python and C++. It requires aJava Runtime Environment to operate as it uses Java's reflectionAPIs to do its work. It is built and installedvia distutilsor setuptools.

• Edit setup.py and review that values inthe INCLUDES, CFLAGS,DEBUG_CFLAGS, LFLAGSand JAVAC are correct for your system. These valuesare also going to be compiled into JCC's config.pyfile and are going to be used by JCC wheninvoking distutils or setuptools tocompile extensions it is generating code for.
• At the command line, enter:$ python setup.py build
$ sudo python setup.py install


Requirements

JCC requires a Java Development Kit to be present. It uses the JavaNative Invocation Interface and expects <jni.h>and the Java libraries to be present at build and runtime.

JCC requires a C++ compiler. A recent C++ compiler for yourplatform is expected to work as expected.

Shared Mode: Support for the --shared Flag

JCC includes a small runtime that keeps track of the Java VM and ofJava objects escaping it. Because there can be only one Java VMembedded in a given process at a time, the JCC runtime must becompiled as a shared library when more than one JCC-built Pythonextension is going to be imported into a given Python process.

Shared mode depends on setuptools' capability ofbuilding plain shared libraries (as opposed to shared libraries forPython extensions).

Currently, shared mode is supported with setuptools0.6c7 and above out of the box on Mac OS X and Windows. OnLinux, a patch to setuptools needs to be appliedfirst. This patch is included in the JCC source distribution inthe jcc/patches directory, patch.43. Thispatch was submitted to the setuptools projectvia issue43.

The shared mode disabled error reported during thebuild of JCC's on Linux contains the exact instructions on how topatch the setuptools installationwith patch.43 on your system.

Shared mode is also required when embedding Python in a Java VM asJCC's runtime shared library is used by the JVM to load JCC andbootstrap the Python VM via the JNI.

When shared mode is not enabled, not supportedor distutils is used insteadof setuptools, static mode is used instead. The JCCruntime code is statically linked with each JCC-built Pythonextension and only one such extension can be used in a given Pythonprocess at a time.

As setuptools grows its shared library building capability it isexpected that more operating systems should be supported with sharedmode in the future.

Shared mode can be forced off by building JCC withthe NO_SHARED environment variable set.

There are two defaults to consider here:

• Is JCC built with shared mode support or not ?

  • By default, on Mac OS X and Windows this is the case.

  • By default, on Linux, this is the case. if setuptools is patched.

  • On other operating systems shared mode support is off by default - not supported - because shared mode depends on setuptools's capability of building a regular shared library which is still an experimental feature.

• Is a JCC-built Python extension built with shared mode ?
  By default, no, shared mode is enabled only with the --shared command line argument.

Notes for Mac OS X

On Mac OS X, Java is installed by Apple's setup as a framework. Thevalues in setup.py for INCLUDESand LFLAGS for darwin should be correctand ready to use.

However, if you intend to use the 'system' Python from a Java VM on Mac OS X -- Python embedded in Java -- you will need to add the flags "-framework", "Python" to the LFLAGS value.

Notes for Linux

JCC has been built and tested on a variety of Linux distributions,32- and 64-bit. Getting the java configuration correct is importantand is done differently for every distribution.
For example:

• On Ubuntu, to install Java 5, these commands may be used: $ sudo apt-get install sun-java5-jdk
$ sudo update-java-alternatives -s java-1.5.0-sun
The samples flags for Linux in JCC's setup.py should be close tocorrect.

• On Gentoo, the java-config utility should be used tolocate, and possibly change, the default java installation.The sample flags for Linux in JCC's setup.py shouldbe changed to reflect the root of the Java installation which maybe obtained via: $ java-config -O

See earlier section about Shared Mode forLinux support.

Notes for Solaris 11 with Sun Studio C++ 12

JCC has been built and tested on Solaris 11 with Sun Studio C++ 12, Java 1.6and Python 2.4.

Because JCC is written in C++, Python's distutils mustbe nudged a bit to invoke the correct compiler. Sun Studio's Ccompiler is called cc while its C++ compiler iscalled CC. To build JCC, use the following shellcommand to ensure that the C++ compiler is used:

$ CC=CC python setup.py build

Shared mode is not currently implemented forSolaris, setuptools needs to be taught how to buildplain shared libraries on Solaris first.

Notes for Solaris 11.1 with GCC 4.5

JCC has been built and tested on Solaris 11.1 with gcc 4.5, Java 1.7 andPython 2.6. Make sure, you?ve already installed the following packages:gcc-4.5, jre-1.7, jdk-1.7, python-2.6, ant, gnu-make and subversion.

Missing packages can be installed via pkg install.

• Edit setup.py and do the following changes:
  Inside JDK = { ? } change the entry for sunos5 to:'sunos5': '/usr/jdk/instances/jdk1.7.0',Inside CFLAGS= {?} change the entry for sunos5 to:'sunos5': ['-fno-strict-aliasing', '-Wno-write-strings'],
• python setup.py build
• su python setup.py install

Notes for Windows

At this time, JCC has been built and tested on Win2k and WinXP witha variety of Python and Java versions.

• Adding the Python directory to PATH is recommended.

• Adding the Java directories containing the necessary DLLs and toPATH is a must.

• Adding the directory containing javac.exeto PATH is required for shared mode (enabled bydefault if setuptools >= 0.6c7 is found to beinstalled).

Notes for Python 2.3

To use JCC with Python 2.3, setuptools is required

• download setuptools.

• edit the downloaded setuptools egg file to usepython2.3 instead of python2.4.

• At the command line, run:
  $ sudo sh setuptools-0.6c7-py2.4.egg

The Apache Software Foundation

The Apache Software Foundation provides support for the Apache community of open-source software projects. The Apache projects are defined by collaborative consensus based processes, an open, pragmatic software license and a desire to create high quality software that leads the way in its field. Apache Lucene, Apache Solr, Apache PyLucene, Apache Open Relevance Project and their respective logos are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.