libQASM: Library to parse cQASM v3.0 files

File organization

For development, see:

• include: 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

ARM specific dependencies

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

• Java JRE >= 11

Build

This version of libqasm can only be compiled via the Conan package manager. You'll 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

Notice:

• the conan profile command only 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...).

Build 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.

Build 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/*:build_tests=True -o libqasm/*:asan_enabled=True -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 enabled by default. To disable them, use -c tools.build:skip_test=True.

Install

From Python

Install from the project root directory as follows:

python3 -m pip install --verbose .

You can test if it works by running:

python3 -m pytest

From C++

The CMakeLists.txt file in the root directory includes install targets:

conan create --version 0.6.6 . -pr:a=tests-debug -b missing

You can test if it works by doing:

cd test/Debug
ctest -C Debug --output-on-failure

Use from another project

From Python

The libqasm module should provide access to the V3xAnalyzer API:

• parse_file,
• parse_string,
• analyze_file, and
• analyzer_string.

The cqasm.v3x module is also available for a more fine-grained use of the library.

import cqasm.v3x.ast
import cqasm.v3x.instruction
import cqasm.v3x.primitives
import cqasm.v3x.semantic
import cqasm.v3x.types
import cqasm.v3x.values

From C++

libqasm can be requested as a Conan package from a conanfile.py.

def build_requirements(self):
    self.tool_requires("libqasm/0.6.5")
def requirements(self):
    self.requires("libqasm/0.6.5")

And then linked against from a CMakeLists.txt:

target_link_libraries(<your target> PUBLIC libqasm::libqasm)

Note that the following dependency is required for libqasm to build:

• Java JRE >= 11

The header file cqasm.hpp should provide access to the following API:

• cqasm::v3x::analyze_file, and
• cqasm::v3x::analyze_string.

Again, other header files are available for a more fine-grained use of the library.

Docker

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

docker build .

Note for Windows users: The above might fail on Windows due to the autocrlf transformation that git does. If you are having trouble with this just create new clone of this repository using:

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

Emscripten

The generation of emscripten binaries has been tested as a cross-compilation from an ubuntu/x64 platform.

conan build . -pr=conan/profiles/release-clang-emscripten-wasm -pr:b=conan/profiles/release -b missing

The output of this build lives in build/Release/emscripten:

• cqasm_emscripten.js.
• cqasm_emscripten.wasm.

Note that cqasm_emscripten.js is an ES6 module. An example of how to use it would be:

cd build/Release/emscripten
mv cqasm_emscripten.js cqasm_emscripten.mjs
cd ../../../emscripten
deno run -A test_libqasm.ts