Lucene++: a C++ port of Java Lucene, version 3.0.9

A port, not a wrapper, and it corresponds to Lucene 3

Lucene++ is described as an up to date C++ port of the popular Java Lucene library, a high-performance, full-featured text search engine. The wording matters in two ways.

First, it is a port rather than a binding. There is no JVM and no JNI bridge in the architecture. The Java analysis chain, the index format, the query parser and the scoring machinery are reimplemented in C++, which means the library links into a native binary with no runtime dependency on a virtual machine.

Second, the version. The project says it welcomes you to Lucene++ version 3.0.9. That number corresponds to the Lucene 3 generation rather than to any current Lucene release, and it tells you what to expect from the feature set: the classic index format, the classic analyzers, and the classic query syntax. Modern Lucene work, including the more recent spatial, vector and highlighting features, is not what this codebase contains.

The primary language is C++, and the build is CMake based, with `CMakeLists.txt` at the root, a `cmake/` directory, an `options.cmake` file and an `include/` directory for public headers alongside `src/` for the implementation.

The audience is a C++ developer who wants Lucene's behaviour without leaving the language. That is a real constituency: desktop applications, embedded search, and systems where a JVM is unacceptable, whether for footprint reasons or for reasons of process model.

Two libraries, a tester and three demos

The component list in the documentation is short and tells you what actually ships.

There is `liblucene++`, the main library, and `liblucene++-contrib`, the contributed extensions. Then `lucene++-tester`, the unit tester. Then three programs that are explicitly labelled demos: `deletefiles`, `indexfiles` and `searchfiles`.

That is a small surface area for a search engine library, and it tells you the split of responsibility. The core library holds the index handling, the analysis chain and the query execution, and the contrib library holds the pieces that are useful but not part of the core contract. The demos are not a CLI product, they exist so you can see the library work end to end.

The tester deserves a note because it tells you about the engineering process. It is built using the Google Testing Framework, so it is the same gtest style of unit testing that the original Java project's ported test suite would map onto, and the documentation gives the exact invocation from the repository root:

    $ build/src/test/lucene++-tester

Command options can be discovered by supplying `--help`. On NT systems the same command works, but the required DLL files must be copied manually into the test binary path first, otherwise you get errors saying that required libraries cannot be found. That is a Windows specific wrinkle worth knowing before you file it as a bug.

For building the suite itself, the documentation points to `doc/BUILDING.md` rather than repeating the steps, which is the right call for a CMake project of this size.

Indexing and searching with the demo programs

The demos give you a working end to end path through the library, and the sequence is short.

Start by indexing a directory of files, giving the indexer the directory to read and the directory to store the index in:

    ./indexfiles <directory to index> <directory to store index>

Once the indexer has finished, query it with `searchfiles`:

    ./searchfiles -index <directory you stored the index in>

That second program gives you an interactive command. You type a query to search the index, press enter, and you see the results.

This is the fastest way to understand what you have built, and it is worth doing before touching the library API. If `indexfiles` and `searchfiles` behave as expected against your own documents, the analysis chain and the query parser are doing what you assumed. If they do not, the problem is in your data or in your expectations about the analyzer, not in your own code.

The third demo, `deletefiles`, exists for the operation that index-only search engines often get wrong, which is deleting documents from an index. Having it as a separate program rather than an option on the indexer is a reminder that deletion in Lucene is a distinct code path with its own semantics.

Note the naming. `searchfiles` takes a `-index` flag with the index directory, whereas `indexfiles` takes two positional arguments. The demos are simple enough to run and simple enough to read as example code.

The licence directory holds three licence texts

The licence story here needs care, because the repository listing shows more than one licence file.

At the top level there is `COPYING`, and alongside it `APACHE.license`, `GPL.license` and `LGPL.license`. The licence field carries a value GitHub cannot categorise, which is a signal that this is a composite rather than a single standard grant.

Three texts together usually means the code is a mix. The most likely arrangement, given a Lucene port, is that the parts derived from the original Apache-licensed Lucene remain under the Apache License 2.0, while some components carry the GPL or LGPL terms. The `REQUESTS` file at the root is a standard mechanism for recording licence requests from downstream users, which suggests the project has historically been willing to grant exceptions, but nothing in the visible documentation says what the current arrangement is.

So the practical instruction is narrow and firm: read `COPYING` and the three licence files before you link this into a product. Do not assume the Apache grant covers the whole library, and do not assume the GPL or LGPL applies to everything. The presence of `APACHE.license` in the tree tells you the Apache text is included, not that it is the only applicable one.

This is a description of the files, not legal advice. If the licence terms matter to your organisation, ask whoever owns your compliance review to read the actual text rather than a summary of it.

Lineage, acknowledgements and what the credit implies

The acknowledgements section is short and tells you about the ancestry of the code, which is the kind of detail that matters when you are deciding how much to trust a port.

The project credits Ben van Klinken and the contributors to the CLucene project for inspiring it. CLucene was an earlier C++ port of Lucene, so Lucene++ is a port of a port in the sense of lineage even if the implementation was written from the Java sources.

Then there is the md5 copyright, held by Aladdin Enterprises with dates in 1999, 2000 and 2002, and the Unicode character properties, guniprop, credited to Tom Tromey for 1999 and Red Hat for 2000. Both of those are the sort of attribution that a faithful port accumulates: you cannot rewrite a hash function to avoid carrying its licence, and the Unicode property tables come from a specific source.

Finally there is Cotire, the compile time reducer, credited to Sascha Kratky. Cotire was a CMake add-on that precompiled translation units to shorten build times, and it was deprecated upstream in CMake, so its presence in the acknowledgements dates the build tooling to a particular era.

Taken together, the acknowledgements describe a codebase with deep roots in older C++ porting work and a build setup that predates current CMake practice. That is context for how you should approach the code: it is a mature port with a real pedigree, but its dependencies and build conventions are of their time.

Where Lucene++ is the wrong choice

Three boundaries are real.

The first is the version gap. Lucene++ 3.0.9 tracks the Lucene 3 generation. If your requirement mentions newer Lucene capabilities, or you need to interoperate with a Java Lucene index written by a current version, the index formats and analysis behaviours will not line up. Lucene changed considerably after version 3, and the analysis chain in particular changed behaviour in ways that affect tokenisation and therefore search results.

The second is that this is a library, not a service. There is no HTTP API, no query endpoint, no index management layer. You are embedding it in your own application, which means you own the index lifecycle, the concurrent access story and the on-disk format. The demos give you a starting point, and the `doc/` directory plus `include/` headers are the real documentation surface.

The third is the ecosystem question, and it is the one that decides most evaluations. There is a much larger body of knowledge, tooling and community around the Java original, and the Java version is where new features land first. If your organisation already runs Java services, embedding Lucene there is often less work than maintaining a C++ port, and the operational cost of two stacks matters.

The alternative to name is the Java Lucene library itself, or a search engine built on it. The difference in approach is that those give you a running service with its own index management, query APIs and operational tooling, while Lucene++ gives you the same analysis and ranking behaviour compiled into your own binary with no service to run. For a desktop application, an embedded tool, or an environment where a JVM is not an option, that difference is decisive.

Editorial conclusion

Adopt Lucene++ if you are building a C++ application that needs full text indexing and query and you would rather ship Lucene's proven analysis and ranking behaviour than write it. Do not adopt it if you need recent Lucene features, since version 3.0.9 corresponds to the Lucene 3 generation, and check the licence file yourself before shipping, because the repository carries the Apache, GPL and LGPL texts together. Verify first that your compiler and standard library satisfy the requirements in doc/BUILDING.md, and that the APIs you need exist in the version you are pinning.

Frequently asked questions

Official sources

1. Issues
2. luceneplusplus/LucenePlusPlus on GitHub
3. README