2.8. Others: Build with CMake#

This document describes how to build Groonga from source with CMake.

2.8.1. Install depended software#

Here is depended software for GNU/Linux, UNIX and Windows.

2.8.1.1. GNU/Linux or UNIX#

Execute setup.sh included in the source code.

If groonga-14.1.0.tar.gz is expanded, it is groonga-14.1.0/setup.sh.

Example of command execution.

$ groonga-14.1.0/setup.sh

setup.sh supports Debian GNU/Linux, Ubuntu, AlmaLinux, and Amazon Linux 2023.

2.8.1.1.1. macOS#

Install Xcode.

Execute setup.sh included in the source code.

If groonga-14.1.0.tar.gz is expanded, it is groonga-14.1.0/setup.sh.

Example of command execution.

$ groonga-14.1.0/setup.sh

2.8.1.2. Windows#

2.8.2. Download source#

You can get the latest source from packages.groonga.org.

2.8.2.1. GNU/Linux or UNIX#

$ wget https://packages.groonga.org/source/groonga/groonga-14.1.0.tar.gz
$ tar xvzf groonga-14.1.0.tar.gz

2.8.2.2. Windows#

Download the latest zipped source from packages.groonga.org.

Then extract it.

2.8.3. Run cmake#

You need to generate build files such as Makefile for your environment.

You can custom your build configuration by passing options to cmake.

Command example for GNU/Linux or UNIX.

$ cmake -S <Groonga source code directory path> -B <Build directory path> --preset=release-maximum

  • -S option

    • Specify the path of the Groonga source code directory

    • Specify the directory from which you downloaded and extracted the files

  • -B option

    • Specify the directory to be used for build

    • Specify a build-only directory outside of Groonga’s source code directory

2.8.3.1. CMake presets#

Using CMake version 3.21.0 or higher, some presets for various build configurations are provided. We have provided a combination of frequently used CMake options, so you can basically use this presets. Use CMake options only if you want to make custom settings. You can get a list of the available presets using cmake --list-presets .

$ cmake --list-presets
Available configure presets:

  "debug-default"                   - Optional features may not be enabled (debug build)
  "release-default"                 - Optional features may not be enabled (release build)
  "release-with-debug-info-default" - Optional features may not be enabled (release build with debug info)
  "debug-maximum"                   - Enable all features (debug build)
  "release-maximum"                 - Enable all features (release build)
  "release-with-debug-info-maximum" - Enable all features (release build with debug info)
  "doc"                             - For documentation
  "memory-debug"                    - For memory debug
  "benchmark"                       - For benchmark

2.8.3.2. CMake options#

This section describes important options of CMake.

2.8.3.2.1. -G GENERATOR#

Specify a generator.

The default is depending on the system.

You can check the default generator and available generators by cmake --help.

$ cmake --help
...
The following generators are available on this platform (* marks default):
  Green Hills MULTI            = Generates Green Hills MULTI files
                                (experimental, work-in-progress).
* Unix Makefiles               = Generates standard UNIX makefiles.
  Ninja                        = Generates build.ninja files.
  Ninja Multi-Config           = Generates build-<Config>.ninja files.
  Watcom WMake                 = Generates Watcom WMake makefiles.
  CodeBlocks - Ninja           = Generates CodeBlocks project files.
  CodeBlocks - Unix Makefiles  = Generates CodeBlocks project files.
  CodeLite - Ninja             = Generates CodeLite project files.
  CodeLite - Unix Makefiles    = Generates CodeLite project files.
  Eclipse CDT4 - Ninja         = Generates Eclipse CDT 4.0 project files.
  Eclipse CDT4 - Unix Makefiles= Generates Eclipse CDT 4.0 project files.
  Kate - Ninja                 = Generates Kate project files.
  Kate - Unix Makefiles        = Generates Kate project files.
  Sublime Text 2 - Ninja       = Generates Sublime Text 2 project files.
  Sublime Text 2 - Unix Makefiles

Here is an example how to specify Unix Makefiles on GNU/Linux or UNIX.

$ cmake . -G "Unix Makefiles"

Here is an example how to specify Visual Studio 17 2022 x64 as a generator on Windows. You can specify a target platform name (architecture) with the -A option.

> cmake . -G "Visual Studio 17 2022" -A x64

2.8.3.2.2. -DCMAKE_INSTALL_PREFIX#

Specify a directory to install Groonga.

The default is depending on the system, e.g. /usr/local or C:/Program Files/groonga.

Here is an example how to specify /tmp/local/ as an install directory on GNU/Linux or UNIX.

$ cmake . -DCMAKE_INSTALL_PREFIX="/tmp/local/"

Here is an example how to specify C:\Groonga as an install directory on Windows.

> cmake . -DCMAKE_INSTALL_PREFIX="C:\Groonga"

2.8.3.2.3. -DGRN_WITH_MRUBY#

Enables mruby support.

You can use the Sharding plugin and ruby_eval with the mruby support.

The default is OFF.

Groonga builds bundled mruby if the mruby support is enabled. In order to build mruby, you must install some required libraries. See the mruby compile guide for more details.

Here is an example how to enable the mruby support.

$ cmake . -DGRN_WITH_MRUBY=ON

2.8.3.2.4. -DGRN_WITH_DEBUG#

Enables debug options for C/C++ compiler. It’s useful for debugging on debugger such as GDB and LLDB.

The default is OFF.

Here is an example how to enable debug options.

$ cmake . -DGRN_WITH_DEBUG=ON

2.8.3.2.5. -DGRN_WITH_APACHE_ARROW#

Enables Apache Arrow support.

In addition to using Apache Arrow IPC streaming format output, you can also use multithreading processing that is used in n_workers and query_parallel_or with the Apache Arrow support.

The default is OFF.

You can install Apache Arrow following to the official installation procedure.

Here is an example how to enable the Apache Arrow support.

$ cmake . -DGRN_WITH_APACHE_ARROW=ON

Note

If you install Apache Arrow manually, you need to use the -DCMAKE_PREFIX_PATH=PATHS option.

2.8.3.2.6. -DCMAKE_PREFIX_PATH=PATHS#

Adds search paths for .cmake files.

You can specify multiple path separating them with : on GNU/Linux or UNIX, ; on Windows.

In case of using libraries installed via a package manager, you do not need to specify this parameter. It is because .cmake files for those libraries are in the default search paths of CMake.

In case of using libraries installed in non-system directories such as /usr, you need to specify .cmake file paths of those libraries by this parameter.

Here is an example how to specify a .cmake file path for /tmp/local/lib/cmake/Arrow/ArrowConfig.cmake on GNU/Linux or UNIX.

$ cmake . -DCMAKE_PREFIX_PATH="/tmp/local"

Here is an example how to specify a .cmake file path for C:\arrow\lib\cmake\Arrow\ArrowConfig.cmake on Windows.

> cmake . -DCMAKE_PREFIX_PATH="C:\arrow"

2.8.4. Build and install Groonga#

Now, you can build Groonga.

2.8.4.1. GNU/Linux or UNIX#

Here is a command line to build and install Groonga.

$ cmake --build -B <Build directory path>
$ sudo cmake --install -B <Build directory path>

2.8.4.2. Windows#

Here is how it is to do it when Visual Studio is specified as the generator, like -G "Visual Studio 17 2022" .

You can use Visual Studio or cmake --build.

Here is a command line to build and install Groonga by cmake --build.

> cmake --build . --config Release
> cmake --build . --config Release --target Install

You should specify --config Debug instead of --config Release when debugging.