Build instructions

You need a compiler that supports c++17 to build balder. It is known to compile with gcc 8, clang 9, and msvc++ 14.2. You need the CMake build system generator. The application requires sinspekto and Qt.

The recommended approach to build the application is with the help of conan. conan is a python tool, and once installed, you need to set the following conan remotes.

python -m pip install conan

conan remote add sintef https://artifactory.smd.sintef.no/api/conan/conan-local
conan remote add bincrafters https://api.bintray.com/conan/bincrafters/public-conan
conan config set general.revisions_enabled=1

Building the documentation is optional. It is generated using doxygen, sphinx, emacs, and plantuml. You also need the following python modules (docs/requirements.txt):

breathe
Sphinx >= 4.0.0
doxyqml
exhale
sphinx-rtd-theme
sphinxcontrib-plantuml
sphinxcontrib-svg2pdfconverter
doc2dash

Instructions for each platform is found below.

Configuration options and targets

The table below specifies available options when building the application.

CMake Option	conan option	Default	Comment
See comment	with_fPIC	True	CMAKE_POSITION_INDEPENDENT_CODE=ON
WITH_DOC	with_doc	False	Use cmake --build . --target doc
WITH_INSTALL	with_install	False	Deploy APK to connected device (android)
WITH_CONSOLE	with_console	False	Terminal window side-by-side GUI (windows)

The following build targets are available:

• doc will build documentation html.

• package_it will create .deb (linux), .exe (windows), and .tar.gz (not android)

• appimage (linux) will create an .AppImage executable.

If the executable is built without conan, the Debian packages will contain dependencies to system packages (and sinspekto-runtime, which is non-standard).

• An additional option WITH_API_DOC=OFF disables API documentation, and enables LaTeX and PDF output of the user documentation. This currently requires linux OS, inkscape, latexmk, and a LaTeX distribution to be installed. The output will be available in <build_folder>/docs/sphinx/latex/.

Linux

Prerequisites (debian-based)

These instructions assume a gcc compiler and using conan.

apt-get install -y build-essential cmake pkg-config python3-pip
python -m pip install setuptools wheel conan

Note

There may be other (unknown) packages needed by transitive dependencies, which are not installed by conan. You may either install them manually when build errors occur, or you can set environment variable CONAN SYSREQUIRES MODE=enabled, which lets conan automatically install them for you.

Documentation prerequisites (optional)

apt-get install -y doxygen emacs-nox graphviz plantuml wget
python -m pip install -r docs/requirements.txt --upgrade
emacs -Q --batch -l docs/emacs-install-pkgs.el

If your distribution is a bit old, you may have to update plantuml.

wget https://sourceforge.net/projects/plantuml/files/plantuml.jar
mv plantuml.jar /usr/share/plantuml/

Building and running (debian-based)

To install dependencies and build the application you can run the following commands:

mkdir build && cd build
conan install .. \
  --options balder:with_doc=True \
  --build missing \
  --settings compiler.libcxx=libstdc++11
conan build ..

You need to activate virtual environments to run the built application.

. activate.sh     # Opensplice environment variables
. activate_run.sh # Dynamic libraries added to LD_LIBRARY_PATH
bin/balder

Packaging into artifacts

The project builds into various artifacts on Linux.

• .AppImage executable, build target appimage, only for x86_64/amd64 architecture.

• .deb package, build target package_it.

• .tar.gz archive, build target package_it.

• conan package .. will build all supported targets.

Warning

When building with conan, the .deb package will not be built with system package dependencies. This is because the system packages likely are not the versions as the built executable expects. Also, the package is not bundled with the necessary libraries and resources in order to run.

The AppImage packaging uses linuxdeploy with linuxdeploy-plugin-qt to create an executable AppImage. The deployment tools are downloaded by CMake automatically. The packaging creates an balder-<version>-<arch>.AppImage. ImageMagick is needed and the virtual run environment must be active, since the dynamic libraries must be available on LD_LIBRARY_PATH, and also conan-installed binary qmake when running linuxdeploy.

apt-get install -y imagemagick
cd build
. activate_run.sh
conan package ..

• Instead of conan package .., it is possible to build only a selected target with . activate.sh && cmake --build . --target appimage, or package_it.

• By default, the application loads a bundled config file. It can be overridden by setting the environment variable: export OSPL_URI=file:///path/to/ospl.xml.

• To run an AppImage, fuse may be required, alternatively, run the application with the following flag: ./balder-1.0.0_x86_64.AppImage --appimage-extract-and-run.

• Internally, conan package calls cmake --build . --target appimage and will create the AppImage, which should contain almost all dependencies for running the application. The file can be run as a desktop application or from the command line.

• The contents of AppDir in the build directory is packaged in the AppImage file.

• AppRun is the entry script of the application.

• To “Install” an AppImage, perhaps AppImageLauncher is useful.

• Need to build on “oldest” distro you want to support to ensure standard library compliance.

• The only supported architecture is x86_64/amd64, because the used linuxdeploy appimages are not pre-built for arm-based CPUs.

• When building in a container, set environment variable APPIMAGE_EXTRACT_AND_RUN=1

• It is possible to use --appimage-extract and then create a symlink on PATH to the extracted AppRun.

Windows

Prerequisites

Prerequisites using conan. Most commands expect you to run with elevated privileges. We make use of chocolatey package manager for windows:

powershell -Command Set-ExecutionPolicy Bypass -Scope Process -Force; \
  [System.Net.ServicePointManager]::SecurityProtocol = \
  [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; \
  iex ((New-Object System.Net.WebClient).DownloadString( \
  'https://chocolatey.org/install.ps1'))

choco install -y python3 Wget
choco install -y cmake --installargs '"ADD_CMAKE_TO_PATH=System"'
choco install -y git.install --params "/GitAndUnixToolsOnPath"
python -m pip install setuptools wheel conan win-unicode-console

Microsoft Visual Studio build tools if they are not already installed. These commands must to be run with cmd.exe. Note that the vs_buildtools.exe will run in the background. These steps are not necessary if you have Visual Studio with C++ compilers installed.

mkdir C:\TEMP && cd C:\TEMP
wget https://aka.ms/vs/16/release/vs_buildtools.exe
vs_buildtools.exe --quiet --norestart --wait --nocache \
  --installPath C:\BuildTools \
  --add Microsoft.VisualStudio.Workload.MSBuildTools \
  --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended
setx path "%path%;C:\BuildTools\Common7\Tools"

Tip

You may need to start new command window sessions between commands to load the new PATH variables.

Documentation prerequisites on Windows (optional)

choco install -y doxygen.install emacs plantuml
choco install -y graphviz.portable --force # Maybe optional: 2.44 broken, downgrades to 2.38
python -m pip install -r docs/requirements.txt --upgrade
emacs -Q --batch -l docs/emacs-install-pkgs.el

Building and running

To install dependencies and build the application you can run the following commands:

mkdir build
cd build
conan install .. \
  --options balder:with_doc=True \
  --build missing
conan build ..

You need to use a virtual environment to run the application. activate.bat sets OSPL_URI and OSPL_HOME environment variables.

activate.bat
cd bin
balder.exe

Packaging into installer and archive

The project is set up with packaging into an executable installer (.exe.) and an archive (.tar.gz) using the build target named package_it. The installer is made with NSIS through CPack. NSIS and can be installed with chocolatey:

choco install -y nsis

The packager uses windeployqt.exe, which is bundled with Qt. Create the artifacts with:

cd build
conan package ..
# or
activate_run.bat
cmake --build . --config Release --target package_it

• By default, the application loads a bundled configuration file ospl.xml. It can be overridden by setting the environment variable: set OSPL_URI=file://C:\\path\\to\\ospl.xml.

• There is also a batch script ospl_env.bat, which can be run before the application in the same session on the command line. It sets OSPL_URI and OSPL_HOME.

Tip

If the package is installed with docs, WIN + "Balder Documentation'" should link to the bundled html documentation.

Android

Warning

We offer only highly experimental Android support.

Note

The android compilation is only tested on a Linux platform.

You need to have Android SDK and NDK installed. The recipe itself uses it, but if some dependencies need building, environment variables need to be on path. The following command will help in that regard:

mkdir build_help && cd build_help
conan install "android-cmdline-tools/[>=6858069]@joakimono/testing" \
  --generator virtualenv \
  --profile=../tools/profiles/android_amd64_api29 \
  --build missing
. activate.sh
cd ..

The build process makes use of QtAndroidCMake to create an APK bundle. During the build process, the created .apk can be installed directly to a connected Android device with the conan option with_install=True, (CMake: WITH_INSTALL=ON).

This project are bundled with some pre-made profiles in tools/profiles for common architectures. Below we show how to compile for x86_64 with API level 29 (Android 10):

mkdir build && cd build
conan install .. \
  --profile=../tools/profiles/android_amd64_api29 \
  --build missing
conan build ..

Warning

The packaging uses a self-signed keystore data/balder.keystore for its call to add_qt_android_apk() in CMakeLists.txt. This should be replaced with your own signing keystore and information updated accordingly in CMakeLists.txt. See self signing on how ot create a keystore.

Internally the conan build .. is almost equivalent to the following commands:

source activate.sh
cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE=$CONAN_CMAKE_TOOLCHAIN_FILE \
  -DANDROID_PLATFORM=$ANDROID_PLATFORM \
  -DANDROID_ABI=$ANDROID_ABI \
  -DANDROID_STL=$ANDROID_STL \
  -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \
  ..
cmake --build . --parallel 4

Troubleshooting

• If the AppImage fails with .. symbol lookup error ... version Qt_5_PRIVATE_API, you forgot . activate_run.sh before conan package .., delete the build folder and try again.

• If there is an issue compiling qt, similar to this. Solution was to unset CPATH

• . deactivate.sh does not properly unset OSPL_HOME, which may cause issues, use unset OSPL_HOME