Warning

Building with GNU Autotools is deprecated, you should build with CMake: Others: Build with CMake

Others#

This section describes how to install Groonga from source on UNIX like environment.

To get more detail about installing Groonga from source on the specific environment, find the document for the specific environment from Install.

Dependencies#

Groonga doesn’t require any special libraries but requires some tools for build.

Tools#

Here are required tools:

  • wget, curl or Web browser for downloading source archive

  • tar and gzip for extracting source archive

  • shell (many shells such as dash, bash and zsh will work)

  • C compiler and C++ compiler (gcc and g++ are supported but other compilers may work)

  • make (GNU make is supported but other make like BSD make will work)

You must get them ready.

You can use CMake instead of shell but this document doesn’t describe about building with CMake.

Here are optional tools:

  • pkg-config for detecting libraries

  • sudo for installing built Groonga

You must get them ready if you want to use optional libraries.

Libraries#

All libraries are optional. Here are optional libraries:

If you want to use those all or some libraries, you need to install them before installing Groonga.

Build from source#

Groonga uses GNU build system. So the following is the simplest build steps:

% wget https://packages.groonga.org/source/groonga/groonga-latest.tar.gz
% tar xvf groonga-latest.tar.gz
% cd groonga-*
% ./configure
% make
% sudo make install

After the above steps, groonga executable file is found in /usr/local/bin/groonga.

The default build will work well but you can customize Groonga at configure step.

The following describes details about each step.

configure#

First, you need to run configure. Here are important configure options:

--prefix=PATH#

Specifies the install base directory. Groonga related files are installed under ${PATH}/ directory.

The default is /usr/local. In this case, groonga executable file is installed into /usr/local/bin/groonga.

Here is an example that installs Groonga into ~/local for an user use instead of system wide use:

% ./configure --prefix=$HOME/local

--localstatedir=PATH#

Specifies the base directory to place modifiable file such as log file, PID file and database files. For example, log file is placed at ${PATH}/log/groonga.log.

The default is /usr/local/var.

Here is an example that system wide /var is used for modifiable files:

% ./configure --localstatedir=/var

--with-log-path=PATH#

Specifies the default log file path. You can override the default log path is groonga executable file command’s --log-path command line option. So this option is not critical build option. It’s just for convenient.

The default is /usr/local/var/log/groonga.log. The /usr/local/var part is changed by --localstatedir option.

Here is an example that log file is placed into shared NFS directory /nfs/log/groonga.log:

% ./configure --with-log-path=/nfs/log/groonga.log

--with-default-encoding=ENCODING#

Specifies the default encoding. Available encodings are euc_jp, sjis, utf8, latin1, koi8r and none.

The default is utf8.

Here is an example that Shift_JIS is used as the default encoding:

% ./configure --with-default-encoding=sjis

--with-match-escalation-threshold=NUMBER#

Specifies the default match escalation threshold. See match_escalation_threshold about match escalation threshold. -1 means that match operation never escalate.

The default is 0.

Here is an example that match escalation isn’t used by default:

% ./configure --with-match-escalation-threshold=-1

--with-zlib#

Enables column value compression by zlib.

The default is disabled.

Here is an example that enables column value compression by zlib:

% ./configure --with-zlib

--with-lz4#

Enables column value compression by LZ4.

The default is disabled.

Here is an example that enables column value compression by LZ4:

% ./configure --with-lz4

--with-message-pack=MESSAGE_PACK_INSTALL_PREFIX#

Specifies where MessagePack is installed. If MessagePack isn’t installed with --prefix=/usr, you need to specify this option with path that you use for building MessagePack.

If you installed MessagePack with --prefix=$HOME/local option, you should specify --with-message-pack=$HOME/local to Groonga’s configure.

The default is /usr.

Here is an example that uses MessagePack built with --prefix=$HOME/local option:

% ./configure --with-message-pack=$HOME/local

--with-munin-plugins#

Installs Munin plugins for Groonga. They are installed into ${PREFIX}/share/groonga/munin/plugins/.

Those plugins are not installed by default.

Here is an example that installs Munin plugins for Groonga:

% ./configure --with-munin-plugins

--with-package-platform=PLATFORM#

Installs platform specific system management files such as init script. Only Red Hat and Red Hat clone distributions such as AlmaLinux are supported.

Those system management files are not installed by default.

Here is an example that installs Red Hat or Red Hat clone distributions specific system management files:

% ./configure --with-package-platform=rhel

--help#

Shows all configure options.

--enable-apache-arrow and --disable-apache-arrow#

Enables or disables 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.

In case of not specifing --enable-apache-arrow nor --disable-apache-arrow, the Apache Arrow support is enabled if Apache Arrow is installed on the system, otherwise disabled. This default behaviour is same as to specify --enable-apache-arrow=auto.

When you specify --enable-apache-arrow explicitly, you must install Apache Arrow on the system beforehand.

You can install Apache Arrow following to the official installation procedure. Groonga requires libarrow-dev on a Debian based system or arrow-devel on a Red Hat Enterprise Linux based system.

When you specify --disable-apache-arrow explicitly, Groonga disables the Apache Arrow support even if Apache Arrow is installed on the system.

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

% ./configure --enable-apache-arrow

Note

If you install Apache Arrow into a non-standard directory, you need to specify the PKG_CONFIG_PATH=PATHS option.

PKG_CONFIG_PATH=PATHS#

Adds search paths of .pc files for pkg-config.

You can specify multiple paths using : to separating.

Groonga uses pkg-config to find external libraries.

pkg-config is a tool that collects flags and paths required for using external libraries from .pc files.

When using libraries installed via a package manager, you do not need to specify this parameter because .pc files for the libraries are in the default search paths of pkg-config.

When using manual built libraries, you need to specify .pc file paths of those libraries by this parameter.

You can use PKG_CONFIG_PATH as an environment variable, but we recommend to use it as a configure parameter because of the following reason.

configure is generated from configure.ac by GNU Autotools. And when make detects that configure.ac has changed, GNU Autotools automatically regenerates configure and re-executes it. If you specify PKG_CONFIG_PATH as a configure parameter, PKG_CONFIG_PATH is specified automatically when configure is re-executed. On the other hand, if you specify PKG_CONFIG_PATH as an environment variable, PKG_CONFIG_PATH is not specified automatically.

Here is an example how to specify a .pc file path for /tmp/local/lib/pkgconfig/arrow.pc.

% ./configure PKG_CONFIG_PATH=/tmp/local/lib/pkgconfig/

make#

configure is succeeded, you can build Groonga by make:

% make

If you have multi cores CPU, you can make faster by using -j option. If you have 4 cores CPU, it’s good for using -j4 option:

% make -j4

If you get some errors by make, please report them to us: How to report a bug

make install#

Now, you can install built Groonga!:

% sudo make install

If you have write permission for ${PREFIX}, you don’t need to use sudo. e.g. --prefix=$HOME/local case. In this case, use make install:

% make install