Building PyLucene

PyLucene is completely code-generated by JCC whose sources are included with the PyLucene sources.


To build PyLucene a Java Development Kit (JDK) and Ant are required; use of the resulting PyLucene binaries requires only a Java Runtime Environment (JRE).

Attention: Starting with release 6.x, Lucene requires Java 1.8. If you build release 4.8.x, the minimum requirement is Java 1.7.

On macOS, you will need to install Oracle Java 8, and due to a bug in the JDK for macOS, you will also need to install Apple's Java 1.6.

On macOS, once installed, a way to make Java 1.8 the default in your bash shell is:
$ export JAVA_HOME=`/usr/libexec/java_home` Be sure to verify that JAVA_HOME value.

On any system, if you're upgrading your Java installation, please rebuild JCC as well. You must use the same version of Java for both JCC and PyLucene.

The setuptools package is required to build and run PyLucene on Python 2.3.5. With later versions of Python, setuptools is only required for shared mode. See JCC's installation instructions for more information.

For the Impatient Ones

  • pushd jcc
  • <edit to match your environment>
  • python build
  • sudo python install
  • popd
  • <edit Makefile to match your environment>
  • make
  • make test (look for failures)
  • sudo make install

For the Rest of Us

Before building PyLucene, JCC must be built first. See JCC's installation instructions for building and installing it.

Once JCC is built and installed, PyLucene is built via make which invokes JCC. See PyLucene's Makefile for configuration instructions.

There are limits to both how many files can fit on the command line and how large a C++ file the C++ compiler can handle. By default, JCC generates one large C++ file containing the source code for all wrapper classes.

Using the --files command line argument, this behaviour can be tuned to workaround various limits, for example:

  • to break up the large wrapper class file into about 2 files:
    --files 2

  • to break up the large wrapper class file into about 10 files:
    --files 10

  • to generate one C++ file per Java class wrapped:
    --files separate

Notes for Solaris 11 with Sun Studio C++ 12

PyLucene's Makefile is a GNU Makefile. Be sure to use gmake instead of plain make.

Just as when building JCC, 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 PyLucene, use the following shell command to ensure that the C++ compiler is used:
$ CC=CC gmake

Notes for Solaris 11.1 with GCC 4.5

PyLucene's Makefile is a GNU Makefile. Be sure to use gmake instead of plain make.

  • Edit Makefile and do the following changes:
    Insert and enable a Solaris-Section with the following content
    # Solaris   (Solaris 11.1, Python 2.6, 32-bit, Java 1.7)
    JCC=$(PYTHON) -m jcc.__main__ --reserved DEFAULT_TYPE
  • gmake
  • su gmake install

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.