Package: libqasm
libQASM: Library to parse cQASM v1.0 filesFile organizationThe original paper and BNF specification for the cQASM v1.0 are located in thedoc/v10directory.
Please note however that the language has changed to some degree since then,
and theqasm.bnfhas never fully corresponded with the flex/bison grammar.There are currently two C++ API versions contained in this repository:
a new API (v1.2) and the original API (v1.0) maintained for backward compatibility purposes.
The new API lives inv1xdirectories, and the older API inv10directories.src/v1x: sources of the new API, and the grammar files for flex/bison.include/v1x: headers of the new API.include/v10: compatibility layer for the original API, now built on top of the new API instead of the original flex/bison parser.test/v1x: tests for the new API.test/v10: tests for the original API, as well as its Python bindings.The following folders may be generated:build/<build type>: the C++ library output files generated by Conan.pybuild: the Python library output files generated bysetup.py.WIP: cQASM v3.0We have started working on the parsing of cQASM v3.0 files, and that's why you will also see somev3xfolders around.However, the development of the new parser is still in a very early stage so its use through the API is completely unsupported.DependenciesC++ compiler with C++20 support (gcc 11, clang 14, msvc 17)CMake>= 3.12gitPython3.x pluspip, with the following package:conan>= 2.0ARM specific dependenciesWe are having problems when using them4andzulu-opendjkConan packages on an ARMv8 architecture.m4is required by Flex/Bison andzulu-openjdkprovides the Java JRE required by the ANTLR generator.
So, for the time being, we are installing Flex/Bison and Java manually for this platform.Flex>= 2.6.4Bison>= 3.0Java JRE>= 11BuildThis version oflibqasmcan 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=conan/profiles/tests-debug -b missingNotice:theconan profilecommand only has to be run only once, and not before every build.theconan buildcommand is buildinglibqasmin Debug mode with tests using thetests-debugprofile.the-b missingparameter asksconanto build packages from sources
in case it cannot find the binary packages for the current configuration (platform, OS, compiler, build type...).Build profilesA group of predefined profiles is provided under theconan/profilesfolder.
They follow the[tests-](debug|release)[-compat]naming convention. For example:releaseis a Release build without tests and compatibility with the original API.tests-debug-compatis a Debug build with tests and compatibility enabled.All the profiles set the C++ standard to 20. All thetestsprofiles enable Address Sanitizer.Build optionsProfiles are a shorthand for command line options. The command above could be written as well as:conan build . -s:h compiler.cppstd=20 -s:h libqasm/*:build_type=Debug -o libqasm/*:asan_enabled=True -o libqasm/*:build_tests=True -o libqasm/*:compat=False -b missingThese are the list of options that could be specified whether in a profile or in the command line:libqasm/*:build_tests={True,False}: builds tests or not.libqasm/*:build_type={Debug,Release}: builds in debug or release mode.libqasm/*:asan_enabled={True,False}: enables Address Sanitizer.libqasm/*:compat={True,False}: enables installation of the headers for the original API,
on top of the ones for the new API.libqasm/*:shared={True,False}: builds a shared object library instead of a static library, if applicable.InstallFrom PythonInstall from the project root directory as follows:python3 -m pip install --verbose .or if you'd rather use conda:conda build python/conda
conda install libqasm --use-localYou can test if it works by running:python3 -m pytestFrom C++TheCMakeLists.txtfile in the root directory includes install targets:conan create --version 0.4.1 . -pr=tests-debug -b missingYou can test if it works by doing:cd test/Debug
ctest -C Debug --output-on-failureUse from another projectFrom PythonAfter installation, you should be able to use the bindings for the original API by justimport libQasm.
The new API doesn't have Python bindings yet.From C++The easiest way to uselibqasmin a CMake project is to fetch the library and then link against it.include(FetchContent)
FetchContent_Declare(cqasm
    GIT_REPOSITORY https://github.com/QuTech-Delft/libqasm.git
    GIT_TAG "<a given cqasm git tag>"
)
FetchContent_MakeAvailable(cqasm)
target_include_directories(<your target> SYSTEM PRIVATE "${cqasm_SOURCE_DIR}/include")
target_link_libraries(<your target> PUBLIC cqasm)Note that the following dependencies are required forlibqasmto build:Flex>= 2.6.4Bison>= 3.0Java JRE>= 11The original API headers arenotincluded by default.
To enable those, pass-o libqasm/*:compat=Trueas a build option to Conan.DockerThis tests the library in a container with the bare minimum requirements forlibqasm.docker build .Note for Windows users:The above might fail on Windows 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