Build from source

This guide will teach you how to install Vicinae from source and build an optimized version of the binary.

Why build from source

Vicinae is a decently sized mostly C++ code base. As such, compiling it can be quite resource demanding and time consuming, in particular if you enable specific optimizations such as LTO.

The main reward for compiling it yourself is the ability to compile Vicinae with optimizations that are specific to your CPU model, provided that it's recent enough. And also, it's fun 😏.

If your goal is to get Vicinae up and running on your system as quickly as possible please consider installing from a repository if your distribution is supported or installing from the script if that is not the case.

Build requirements

To build Vicinae, you need a working C++23-capable compiler. We mostly make use of gcc (v15+) but clang should also work and is the supported way to build for macOS.

You will also need a few dependencies, listed below.

If you distribution does not appear in this list, you are on your own to figure out the exact packages to install. If you still manage to build it, don't forget to contribute to this documentation by adding your list here!

pacman -Syu				\
    base-devel			\
    cmake				\
    ninja				\
    nodejs				\
    npm					\
    qt6-base			\
    qt6-svg				\
    qt6-declarative		\
    qt6-shadertools		\
    qt6-tools			\
    cmark-gfm			\
    layer-shell-qt		\
    libqalculate		\
    qtkeychain-qt6		\
    syntax-highlighting	\
    extra-cmake-modules	\
    catch2				\
    wayland-protocols

Recommended build tools

In order to make building and rebuilding Vicinae easier we recommend installing the following:

• Install ccache (or sccache) to automatically cache most compilations and significantly decrease build times. It is detected and used automatically.
• Install the mold linker to link the Vicinae binary significantly faster. It is not picked up automatically: pass -DCMAKE_LINKER_TYPE=MOLD at configure time.

Build Flags

Several build flags are available to tweak what features are built into the final binary. The best way to know about them is to read the beginning of the top level CMakeLists.txt.

Flags are easily identified by the use of the option cmake function:

option(LTO "Enable Link Time Optimization (LTO). This will result in better performance, but greatly increased compile time." OFF)
option(NOSTRIP "Never strip debug symbols from the binary, even in release mode. Note that symbols are never stripped for debug releases." OFF)
option(USE_SYSTEM_CMARK_GFM "Use system cmark-gfm (github's fork of cmark) instead of the vendored copy under vendor/cmark-gfm" ${USE_SYSTEM_DEFAULT})
option(USE_SYSTEM_KF6 "Use system KDE syntax highlighting library for markdown code block highlight support" ${USE_SYSTEM_DEFAULT})
option(USE_SYSTEM_QT_KEYCHAIN "Use system qt-keychain instead of building it from source. Note: still depends on system libsecret." ${USE_SYSTEM_DEFAULT})

You can enable or disable a given option by passing a -D<OPTION>=ON/OFF flag to the cmake program during the configuration step. See the CMake code examples below.

About static linking

Although Vicinae does not support being built in a fully static way, we provide the option to statically link against libraries that bump version often or are generally not easy to install through traditional means.

The main goal of this is to make pre-built binaries more portable across different distributions that ship different versions of the same package.

For reference, this is the CMake configure command we use to build our releases:

cmake -G Ninja .. \
	-DCMAKE_BUILD_TYPE=Release \
	-DCMAKE_POLICY_VERSION_MINIMUM=3.5  \
	-DLTO=ON \
	-DUSE_SYSTEM_CMARK_GFM=OFF

This builds the vendored copy of cmark-gfm alongside the main Vicinae code base and links it statically.

Get the source code

First, clone the repository and go to the source directory:

git clone https://github.com/vicinaehq/vicinae.git && cd vicinae

Release Build

To build a generic release build:

make release

make release enables link-time optimizations, which makes linking a lot slower. Drop -DLTO=ON from the CMake command for a faster build.

Optimized Release Build

If you want to squeeze out the most performance you can out of Vicinae, you can enable a few optimization during configuration:

make host-optimized

• -DLTO=ON will enable link-time optimizations. This can greatly improve performance, but linkage will take a lot more time.
• -march=native compiles with all optimizations supported by the executing CPU. The resulting binary will only be able to be run on systems that support the same CPU flags.

Generally speaking, you will be trading compilation time and portability for more performance.

Debug Build

You want a debug build when you are trying to troubleshoot an issue or generally contribute to Vicinae:

make debug

This will compile with -g3 and QT debug logs. make debug also enables AddressSanitizer (-DENABLE_SANITIZERS=ON).

Install built binaries

Once Vicinae is built, install it to standard system directories:

sudo make install

On Linux, snippet expansion and paste need the input server to have access to input devices. Grant it the required capability (adjust the prefix to your install location):

sudo setcap cap_dac_override=ep /usr/local/libexec/vicinae/vicinae-input-server