Compile Met.3D from source code: Linux (vcpkg)

This page describes how to setup a development environment to compile Met.3D from its source code using vcpkg under Linux. It will automatically build all third-party dependencies and save them in a dedicated folder. When building Met.3D, these dependencies get copied to the build folder and linked to the executable.

Contrary to conda, this makes debug builds of our dependencies available. The debugger can then step through dependency code. This does however increase first-build time, as all dependencies will be build as-well.

This guide was tested with Ubuntu 26.04. When using another system you might encounter missing system packages or version mismatches.

Important

The installation procedure described here only works for Met.3D v2.0 and higher versions. Older versions do not support vcpkg.

Note

A source build of Met.3D takes roughly 140 GB of space for its dependencies and an additional 4GB of space for each of its build directories. This is necessary for vcpkg to store the build artefacts of all dependencies of Met.3D.

Prerequisites

The following tools are required to build Met.3D on Linux with vcpkg.

  1. CMake >= 3.29

  2. Ninja

  3. vcpkg

  4. git

  5. gcc

Installing build tools

First, we are going to install all required build tools. These are required to build Met.3D:

sudo apt install git build-essential cmake ninja-build

We also recommend installing a debugger:

sudo apt install gdb

Important

Met.3D requires CMake version 3.29 or later. You can check the version with cmake --version.

Bootstrap vcpkg

You will also need a vcpkg installation.

It requires the following dependencies:

sudo apt install curl zip unzip tar

You can then bootstrap vcpkg as follows:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg; ./bootstrap-vcpkg.sh

Note

Compiling dependencies via vcpkg for the first time can take upward of 4 hours, depending on your hardware. In our experience, storage speed is the largest bottleneck, so having your vcpkg directory on an SSD might improve compile times significantly.

Next you have to set the VCPKG_ROOT environment variable to your vcpkg installation. This is required, so that Met.3D can find the vcpkg installation:

export VCPKG_ROOT=/path/to/vcpkg/folder

You might also want to export it to your PATH:

export PATH=$PATH:$VCPKG_ROOT

Note

This only sets these environment variables for the current terminal session. To make them permanent, add them to your .bashrc for bash.

Installing vcpkg system dependencies

Some packages compiled by vcpkg require system dependencies. For example, Qt lists their requirements here: Qt requirements.

To install all required packages on Ubuntu 26.04, run:

sudo apt install libfontconfig1-dev \
libfreetype-dev \
libgtk-3-dev \
libx11-dev \
libx11-xcb-dev \
'^libxcb.*-dev' \
libxext-dev \
libxfixes-dev \
libxi-dev \
libxkbcommon-dev \
libxkbcommon-x11-dev \
libxrender-dev \
libxrandr-dev \
libwayland-dev \
pkg-config \
bison \
flex \
autoconf \
automake \
libtool \
m4 \
autoconf-archive \
python3-jinja2 \
python3-venv \
nasm

Important

Make sure you have a graphics driver installed! AMD graphics card drivers are usually provided by the linux kernel. Nvidia’s graphics card drivers have to be installed manually.

Get the source code

Next you can clone the Met.3D repository to a location of your choosing:

git clone https://gitlab.com/wxmetvis/met.3d.git

Building Met.3D from source in the terminal

Finally, you can build Met.3D from source. Though we recommend an IDE for development, we will first outline how to build it from terminal.

Navigate to the Met.3D repository and execute the following commands:

cmake --preset linux-x64-debug
cmake --preset linux-x64-release

These two commands, will create two build folders, one for a release build and one for a debug build. They will also build all dependencies via vcpkg.

Error

If you get any CMake error during the vcpkg step, read the log. The cause is often a missing dependency or download failures. The log usually contains the error directly or specifies a log file that contains a build error.

Next, you can build Met.3D by navigating into the build folder and running:

cmake --build .

Running Met.3D from terminal

You might notice, that Met.3D will not run directly from its build folder. This is because it searches for Qt plugins when starting, which it cannot find. To fix this, you need to set an environment variable for release builds:

export QT_PLUGIN_PATH=PATH_TO_YOUR_BUILD_FOLDER/vcpkg_installed/x64-linux-dynamic/Qt6/plugins

For debug builds set it to the following:

export QT_PLUGIN_PATH=PATH_TO_YOUR_BUILD_FOLDER/vcpkg_installed/x64-linux-dynamic/debug/Qt6/plugins

You also need to point Fontconfig to the correct Fontconfig file:

export FONTCONFIG_FILE=PATH_TO_YOUR_BUILD_FOLDER/vcpkg_installed/x64-linux-dynamic/etc/fonts/fonts.conf

You can then start Met.3D from this terminal:

./Met3D

Setting up an IDE

Since building directly from command line is a bit cumbersome, we will describe how to setup an IDE for Met.3D on Linux.

CLion

To use CLion with Met.3D, simply open the Met.3D source folder as a project in CLion.

Navigate to Settings → Build, Execution, Deployment. Here we have to setup the CMake profiles. Go to the CMake section.

There will be a default configuration called Debug. Remove it with the - symbol. There should be four grayed-out configurations left. Duplicate the two linux configuration presets and enable the duplicates.

Next, add the VCPKG_ROOT environment variable created earlier to the environment variables of the presets. This only works on the duplicates, as the presets are un-editable.

Apply the changes and close the dialog.

Now you can configure CMake.

Once that completes, you can select your build and run configuration in the menu bar.

Important

You will not be able to start Met.3D just yet with CLion, as it will not find the Qt plugins. For that edit your run configuration, and add a new environment variable, QT_PLUGIN_PATH. Set its value to PATH_TO_BUILD_DEBUG/vcpkg_installed/x64-linux-dynamic/debug/Qt6/plugins;PATH_TO_BUILD_RELEASE/vcpkg_installed/x64-linux-dynamic/Qt6/plugins

Troubleshooting

vcpkg does not compile all dependencies

This can happen for multiple reasons:

  1. You have a missing build dependency. This usually happens during the configure stage of a package and is stated in one of the log files for the package build.

  2. You have an outdated vcpkg repository. Update it with:

1git pull
2./bootstrap-vcpkg.sh

  1. You have a conflicting vcpkg install. Check VCPKG_ROOT environment variable in your development environment.

  2. A package is broken. This can sometimes happen. If you are sure it is not one of the above, check the vcpkg repository and whether the port was updated or already has an issue related to the build failure. You can also create an issue in the Met.3D repository or contact us.