Skip to main content

Development Installation Guide (Unstable)

This guide is for contributors or anyone who wants the latest changes before a stable release. The unstable branch may break at any time and can include incomplete features.

Tip: If you only need a stable build, use the Installation Guide and download the latest release ZIP.

Prerequisites​

Use the same prerequisites as the standard Installation Guide, including build tools and optional OpenSSL.

Build from the Unstable Branch​

Step 1: Clone the Repository (Unstable)​

git clone --branch unstable git@github.com:hlquery/hlquery.git
cd hlquery/

Step 2: Configure​

./configure

During this step, hlquery generates core/config.h, including the CoreExport macro used on public core classes and globals such as hlquery, TimerManager, LogManager, and Instance.

CoreExport maps to the compiler's symbol-visibility attribute on GCC/Clang builds and expands to an empty macro on toolchains that do not need it. We use it to keep the core symbols that must be visible across object-file and shared library boundaries exported explicitly instead of relying on default visibility. That matters for downstream linking, plugin-style boundaries, and builds that enable hidden visibility by default.

You can override defaults with the following parameters:

  • --prefix=PATH Base directory for installation.
  • --layout=NAME Install layout preset: dev, system, debian, rpm, auto.
  • --debian-layout Alias for --layout=debian.
  • --rpm-layout Alias for --layout=rpm.
  • --confdir=PATH Directory for configuration files.
  • --logdir=PATH Directory for log files.
  • --datadir=PATH Directory for data files.
  • --rundir=PATH Directory for PID files.
  • --bindir=PATH Directory for executables.
  • --skip-tests Skip library testing and compilation steps.
  • --disable-lsm Disable LSM storage engine (enabled by default).
  • --enable-extras=LIST Enable optional modules from src/modules/extra using a comma-separated list or all.
  • --max-threads=N Set the maximum thread count.
  • --engine=ENGINE Force a specific I/O engine (epoll, kqueue, or poll).
  • --help Show all options.

In this build system, "extras" means optional modules that live under src/modules/extra. They are excluded unless explicitly enabled during ./configure. The configure step discovers the available extras, updates the generated Makefile, and arranges for the selected modules to be built as shared libraries in run/modules/.

How discovery and enabling work:

  • src/modules/extra/m_name.cpp is treated as a single-file extra named m_name.
  • src/modules/extra/m_name/ is treated as a multi-file extra named m_name when the directory contains .cpp files.
  • --enable-extras=name_a,name_b enables only the listed extras.
  • --enable-extras=all enables every extra discovered in src/modules/extra at configure time.
  • Unknown names are rejected immediately so ./configure does not continue with a misspelled extra.
  • Enabled extras are linked into run/modules/*.so.
  • Configure also creates symlinks under src/modules/ that point back to src/modules/extra, because the runtime/module loader expects enabled modules to appear there.

If src/modules/extra is empty, --enable-extras=all has no effect beyond generating a normal build.

Examples:

./configure --engine=epoll --max-threads=16
./configure --layout=debian
./configure --enable-extras=all
./configure --enable-extras=m_example,m_other

Use --layout=debian or --layout=rpm when preparing binaries intended to run with distro-standard paths (for example /etc/hlquery, /var/log/hlquery, /var/lib/hlquery).

./configure --prefix=/usr --confdir=/etc/hlquery --logdir=/var/log/hlquery \
  --datadir=/var/lib/hlquery --rundir=/run/hlquery --bindir=/usr/bin

Step 3: Build and Install​

make -j4
make install

If you change the extras list, re-run ./configure before make so the generated Makefile and generated module symlinks are refreshed with the correct module targets.

To remove build output, including extra-module .so files and generated module symlinks, run:

make clean

Because make clean also removes the generated Makefile, a clean rebuild with extras usually starts with ./configure --enable-extras=... followed by make.

Packaging-Friendly Layouts​

If you are validating binaries for Debian/Ubuntu or RPM-family deployment, prefer layout presets:

./configure --layout=debian
# or
./configure --layout=rpm

These presets target distro-standard directories so the same runtime paths are used when packages are later installed system-wide.

Staying Updated​

Pull the newest commits when you want to sync with upstream:

git pull

If build errors appear after an update, re-run ./configure and rebuild.

Running in Development​

Start hlquery in the foreground for easier debugging:

./run/hlquery start --nofork

Notes​

  • The unstable branch can change APIs or configuration defaults without notice.
  • For bug reports, include the output of ./run/hlquery --version and the current commit hash.