Install JCC

Getting JCC's Source Code

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

To get the JCC source code only from SVN use:

svn co https://svn.apache.org/repos/asf/lucene/pylucene/trunk/jcc jcc

Building JCC

JCC is a Python extension written in Python and C++. It requires a Java Runtime Environment to operate as it uses Java's reflection APIs to do its work. It is built and installed via distutils or setuptools.

  • On MacOS and Windows, setup.py will attempt to find a JDK on your system and report what it found by showing the values for JAVAHOME and JAVAFRAMEWORKS it was able to derive. If the JDK installation that was found is not the one you wish to use or if you are not on MacOS or Windows, you can either edit setup.py and review that the values in the INCLUDES, CFLAGS, DEBUG_CFLAGS, LFLAGS, JAVAC, and JAVADOC dicts are correct for your system or set all of the environment variables JCC_JDK, JCC_INCLUDES, JCC_CFLAGS, JCC_DEBUG_CFLAGS, JCC_LFLAGS, JCC_JAVAC and JCC_JAVADOC, using os.pathsep as value separator to override them. The values hereby configured are going to be compiled into JCC's config.py file and are going to be used by JCC when invoking setuptools to compile the extensions it is used to generate 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 Java Native Invocation (JNI) 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 your platform is recommeded and should work as expected.

Shared Mode: Support for the --shared Flag

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

Shared mode depends on setuptools' capability of building plain shared libraries (as opposed to shared libraries for Python extensions).

Currently, shared mode is supported with setuptools 0.6c7 and above out of the box on MacOS and Windows. On Linux, a patch to setuptools needs to be applied first. This patch is included in the JCC source distribution in the jcc2/patches directory, patch.43. This patch was submitted to the setuptools project years ago via "Issue 43", originally tracked in the long defunct bugs.python.org/setuptools bug tracker. setup.py will attempt to apply the patch for you via monkeypatching.

The shared mode disabled error reported during the build of JCC's on Linux contains the exact instructions on how to patch the setuptools installation with patch.43 on your system.

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

When shared mode is not enabled, not supported or distutils is used instead of setuptools, static mode is used instead. The JCC runtime code is statically linked with each JCC-built Python extension and only one such extension can be used in a given Python process at a time.

As setuptools grows its shared library building capability it is expected that] more operating systems should be supported with shared mode in the future.

Shared mode can be forced off by building JCC with the NO_SHARED environment' variable set.

There are two defaults to consider here:

  • Is JCC built with shared mode support or not ?

    • By default, on MacOS, Linux or Windows, this is the case when using a modern version of setuptools

    • 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 MacOS

On MacOS, Java is installed by Apple's setup as a framework. The values in setup.py for INCLUDES and LFLAGS for darwin should be correct and ready to use when setup.py was able to derive JAVAHOME and JAVAFRAMEWORKS.

However, if you intend to use the 'system' Python from a Java VM on MacOS -- 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 important and is done differently for every distribution.
For example:

  • On Debian 11, the commands below install Temurin Java 17, Python 3.9, gcc, g++ and make

install Temurin Java (Adoptium)

sudo -s
apt install wget apt-transport-https gnupg
wget -O - https://packages.adoptium.net/artifactory/api/gpg/key/public | apt-key add -
echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | tee /etc/apt/sources.list.d/adoptium.list
apt update
apt install temurin-17-jdk

install gcc, g++ and make

sudo apt install gcc-x86-64-linux-gnu g++-x86-64-linux-gnu make

install Python 3.9 with development, virtual environment and setuptools support

sudo apt install python3.9-dev python3-venv python3-setuptools

The samples flags for Linux in JCC's setup.py should be close to correct. See earlier section about Shared Mode for Linux 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.6 and Python 2.4.

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

$ CC=CC python setup.py build

Shared mode is not currently implemented for Solaris, setuptools needs to be taught how to build plain 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 and Python 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 with a variety of Python and Java versions.

  • Adding the Python directory to PATH is recommended.
  • Adding the Java directories containing the necessary DLLs and to PATH is a must.
  • Adding the directory containing javac.exe to PATH is required for shared mode (enabled by default if setuptools >= 0.6c7 is found to be installed).

Notes for Python 2.3

To use JCC with Python 2.3, setuptools is required

  • download setuptools.
  • edit the downloaded setuptools egg file to use python2.3 instead of python2.4.
  • At the command line, run:
    $ sudo sh setuptools-0.6c7-py2.4.egg