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 latest release 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 (v14+) but clang should also work and will be the officially supported way to build for MacOS in the future.

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			\
    protobuf		\
    cmark-gfm		\
    layer-shell-qt 	\
    libqalculate 	\
    minizip			\
    qtkeychain-qt6	\
    rapidfuzz-cpp

Recommended build tools

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

• Install ccache to automatically cache most compilations and significantly decrease build times.
• Install the mold linker to link the Vicinae binary significantly faster.

All you need is to install these tools, the Vicinae build system will take care of the rest for you.

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_PROTOBUF "Use system protobuf instead of building it from source" ON)
option(USE_SYSTEM_ABSEIL "Use system abseil (libabsl) instead of building it from source" ON)
option(USE_SYSTEM_CMARK_GFM "Use system cmark-gfm (github's fork of cmark) instead of building it from source" ON)

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 instance, libprotobuf updates very often and offers no retro-compatbility. This essentially means that the distributed binaries become outdated as soon as the distribution updates its protobuf version. By statically linking against protobuf, we embed a given version of protobuf in the binary, and this specific, local version is the one going to be used for the entire lifetime of the binary.

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

cmake -G Ninja .. \
	-DCMAKE_POLICY_VERSION_MINIMUM=3.5  \
	-DLTO=ON \
	-DUSE_SYSTEM_PROTOBUF=OFF \
	-DUSE_SYSTEM_ABSEIL=OFF \
	-DUSE_SYSTEM_CMARK_GFM=OFF \
	-DUSE_SYSTEM_MINIZIP=OFF

This will:

• instruct cmake to download a copy of a specific version of protobuf, abseil, cmark-gfm and minizip-ng
• build them alongside the main Vicinae code base
• link them all together as a single binary

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 without LTO enabled:

make release

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 also enable QT debug log statements.

Install built binaries

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

sudo make install