Skip to content

Installation

Jump to bottom
Alexander Vieth edited this page Oct 23, 2024 · 60 revisions

This pages describes how to build ManiVault from source. If you want to simply download and install the application, you can find an installer here.

You can download ManiVault's source code from the repository on GitHub in any way you like, but the simplest is:

git clone git@github.com:ManiVaultStudio/core.git

Dependencies

ManiVault uses git and CMake for version control and as a meta-build system respectively.

The main build dependency that you need to set up is Qt 6.3.2+ with the additional libraries Qt WebEngine, Qt WebChannel, Qt Positioning and the Qt5 Compatibility Module1. ManiVault plugins might make use of other additional libraries as well, e.g. the image loader plugin uses the Qt Imaging Formats library.

ManiVault is written in C++17 and requires a compatible compiler:

  • For Windows: Visual Studio 2019 or 2022
  • For Mac: Xcode 12.4 with Apple Clang 12 or newer
  • For Linux: gcc 10 or newer

Several build-dependencies are downloaded during the CMake configuration and include: zlib, QuaZip, Qt-Advanced-Docking-System and biovault_bfloat16. These are automatically set up and installed when compiling ManiVault.

Windows-specific

To fully set up Qt:

  • Add a QT_DIR environment variable to your Qt install path (e.g. C:\Qt\6.3.2\msvc2019_64\) so that CMake can link ManiVault to Qt for a successful build.
  • Add the location of the installed Qt libraries (e.g. C:\Qt\6.3.2\msvc2019_64\bin) to the user or system path variable so that the installed .exe might find these runtime libraries when you start it.

Linux-specific

Tried on Ubuntu 23.04 using gcc 12.2.0 and CMake 3.26.4. Install build dependencies (building infrastructure, Qt packages, zlib):

sudo apt install build-essential cmake libgl1-mesa-dev qt6-base-dev qt6-base-private-dev qt6-webengine-dev qt6-5compat-dev qt6-wayland qt6-svg-dev libxkbcommon-dev libtbb-dev fonts-font-awesome libgomp1
Ubuntu 22.04 (not recommended)

On Ubuntu 22.04 you'll additionally need libxkbfile-dev libglew-dev.

sudo apt install build-essential libxkbcommon-dev libxkbfile-dev libtbb-dev libglew-dev fonts-font-awesome libgomp1 libgl1 libegl1 libcups2 libopengl0 libnss3-dev libasound2-dev libxkbcommon-x11-dev

Also, the standard repository does not provide Qt 6.3 or a nice modern cmake version. You can install Qt like this, using aqtinstall:

cd ~
sudo apt install wget
mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init
source ~/.bashrc
conda create -n qt python=3.10 -y
conda activate qt
pip install aqtinstall
aqt list-qt linux desktop --arch 6.3.2
aqt list-qt linux desktop --modules 6.3.2 gcc_64
mkdir -p ~/qt6
aqt install-qt -O ~/qt6 linux desktop 6.3.2 gcc_64 -m all
echo -e '\n# Custom qt\nexport PATH=$HOME/qt6/6.3.2/gcc_64/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

We might as well build cmake from scratch

cd ~
sudo apt purge cmake -y
sudo apt install libssl-dev
mkdir cmake && cd cmake
mkdir cmake_install
git clone https://gitlab.kitware.com/cmake/cmake.git
mv cmake cmake_source
cd cmake_source
git checkout v3.30.5
./bootstrap --prefix=$HOME/cmake/cmake_install
make && make install
echo -e '\n# Custom cmake\nexport PATH=$HOME/cmake/cmake_install/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Project configuration

Install location

Building the plugin system library requires setting an installation path where you would like the executable and library to be installed to. ManiVault uses CMake as it's build system. You'll need to set the variable MV_INSTALL_DIR to your install directory when configurating the CMake project, e.g. D:/Documents/ManiVault/install/ or /home/USERNAME/ManiVault/install/.

CMake GUI

  1. Launch the CMake GUI
  2. In the source code field browse to the local folder to which you cloned the ManiVault core repo, e.g. D:/Documents/ManiVault/core
  3. In the build field copy the source code field but append /Build at the end. This will generate a new folder for all files necessary for building the project.
  4. Set the MV_INSTALL_DIR variable to your install directory, e.g. D:/Documents/ManiVault/install.
  5. Press Configure and select the generator for your IDE of choice with the platform of x64. Press Finish to configure the project.
  6. A lot of red paths should now appear. Check that the ones pointing to Qt directories seem correct and then press Generate to generate the solution for your given IDE.
  7. Press Open Project to launch the IDE and the project.

During step (4) you can define a ZLIB_ROOT variable pointing to a custom Zlib installation

Compilation

This depends on your IDE and compiler of choice. Here we give some exemplary setup instructions.

Windows: Visual Studio

You selected Visual Studio as the generator in the CMake GUI. After opening the project:

  1. At the top of Visual Studio set the build mode (where it says Debug) to Release.
  2. Right click the solution and press Build Solution, if this does not produce errors, continue to the next step.
  3. Right click the project MV_Application in the Solution Explorer and select "Set as Startup Project".
  4. Run the project with Ctrl+F5 to launch ManiVault.

Linux

Tried on Ubuntu 23.04 using gcc 12.2.0 and CMake 3.26.4. In the cloned ManiVault core folder:

mkdir build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DMV_INSTALL_DIR=/home/USERNAME/ManiVault/install -G "Unix Makefiles"
cmake --build build --config Release

Depending on your memory constraints, you can always append -j N with e.g. N=4 as the number of parallel build jobs to the last command or use another generator like e.g. -G "Ninja".

Notes

  • Note: Both code and setup instructions might still reference HDPS, the development name of ManiVault.
  • After first time compiling on macOS it might be necessary to manually moc the MainWindow.ui file:
uic MainWindow.ui -o ui_MainWindow.h
mv ui_MainWindow.h ../Build/
  • ManiVaultStudio might not run properly on integrated/old graphics hardware (in some cases the application crashes). The solution is to run on high-performance (recent) graphics hardware. The link below demontrates how to do this: https://pureinfotech.com/set-gpu-app-windows-10/

1: especially check for Qt5 Compatibility Module to be available, if not, Quazip won't be available to CMake. Qt5 Compatibility Module is apparently not part of every Qt distribution (e.g., it is not available in the binary distribution of Qt 6.5.2 through the Qt installer)

Clone this wiki locally