Skip to content

Dev Guide

File organization

For development, see:

  • include/libqasm: public headers.
  • src: source files.
  • test: test files.
  • python: SWIG interface.
  • res: resource files, for testing.

For build process, continuous integration, and documentation:

  • conan: Conan profiles.
  • emscripten: bindings and test for the Emscripten binaries.
  • scripts: helper scripts used during the build process.
  • .github: GitHub Actions configuration files.
  • doc: documentation.

Build outputs may go into:

  • build/<build type>: the C++ library output files generated by Conan.
  • pybuild: the Python library output files generated by setup.py.

Dependencies

  • C++ compiler with C++20 support (gcc 11, clang 14, msvc 17)
  • CMake >= 3.12
  • git
  • Python 3.x plus pip, with the following package:
    • conan >= 2.0
  • SWIG

ARM builds

We are having problems when using the zulu-openjdk Conan package on an ARMv8 architecture. zulu-openjdk provides the Java JRE required by the ANTLR generator. For the time being, we install Java manually for this platform.

  • Java JRE >= 11

Documentation

  • doxygen
  • mkdocs with the following packages:
    • mike
    • mkdocs-material
    • mkdocstrings
    • pymdown-extensions

Linters

  • clang-format-18
  • clang-tidy-18

On a Linux machine, these linters can be installed with the following commands:

wget https://apt.llvm.org/llvm.sh -O llvm_install.sh
chmod +x llvm_install.sh
./llvm_install.sh
apt-get install -y clang-format-18 clang-tidy-18

Build

This version of libQASM can only be compiled via the Conan package manager. You will need to create a default profile before using it for the first time.

The installation of dependencies, as well as the compilation, can be done in one go.

git clone https://github.com/QuTech-Delft/libqasm.git
cd libqasm
conan profile detect
conan build . -pr:a=conan/profiles/tests-debug -b missing

Note

  • the conan profile command has to be run only once, and not before every build.
  • the conan build command is building libQASM in Debug mode with tests using the tests-debug profile.
  • the -b missing parameter asks conan to build packages from sources in case it cannot find the binary packages for the current configuration (platform, OS, compiler, build type...).

Profiles

A group of predefined profiles is provided under the conan/profiles folder.
They follow the [tests-](build_type)(-compiler)(-os)(-arch)[-shared] naming convention:

  • tests: if tests are being built.
  • build_type: can be debug or release.
  • compiler: apple-clang, clang, gcc, msvc.
  • os: emscripten, linux, macos, windows.
  • arch: arm64, wasm, x64.
  • shared: if the library is being built in shared mode.

All the profiles set the C++ standard to 20.
All the tests, except for linux-x64 profiles, enable Address Sanitizer.

Options

Profiles are a shorthand for command line options. The command above could be written, similarly, as:

conan build . -s:a compiler.cppstd=20 -s:a libqasm/*:build_type=Debug -o libqasm/*:asan_enabled=True -c tools.build:skip_test=False -b missing

This is the list of options that could be specified either in a profile or in the command line:

  • libqasm/*:asan_enabled={True,False}: enables Address Sanitizer.
  • libqasm/*:build_type={Debug,Release}: builds in Debug or Release mode.
  • libqasm/*:shared={True,False}: builds a shared object library instead of a static library, if applicable.

Tests are disabled by default. To enable them, use -c tools.build:skip_test=False.

Documentation

Build and serve on http://127.0.0.1:8000/.

export PYTHONPATH=./scripts/python
mkdocs serve

Note

The export is needed to point mkdocs to the custom handlers used for the C++, emscripten, and Python APIs.

Linters

Continuous Integration will fail if the files do not adhere to a series of formatting and code style guidelines:

  • Formatting checks are defined in .clang-format.
  • Code style checks are defined in .clang-tidy.

It is recommended to run these linters before pushing any changes:

conan build . -pr:a=conan/profiles/tests-release-gcc-linux-x64 -b missing
python3 ./scripts/run_cpp_linters.py .

Note

  • The linters require clang-format-18 and clang-tidy-18.
  • It is mandatory to have a build before running the linters.
    • clang-tidy expects to find a compile_commands.json in a build folder.
  • It is recommended to build with gcc in Release mode.
    • We have observed clang-tidy fails to find some standard headers when compiling with clang.
    • run_cpp_linters.py can receive a build folder as second argument, but defaults to build/Release.

Docker

This tests the library in a container with the bare minimum requirements for libQASM.

docker build .

Note

The above might fail on Windows due to the autocrlf transformation that git does. If you run into this issue, then create new clone of this repository:

git clone --config core.autocrlf=input git@github.com:QuTech-Delft/libqasm.git