Metadata-Version: 2.1
Name: libqasm
Version: 0.5.1
Summary: libQasm Python Package
Home-page: https://github.com/QuTech-Delft/libqasm
Author: QuTech, TU Delft
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: msvc-runtime ; platform_system == "Windows"

# libQASM: Library to parse cQASM v1.0 files

[![CI](https://github.com/QuTech-Delft/libqasm/workflows/Test/badge.svg)](https://github.com/qutech-delft/libqasm/actions)
[![PyPI](https://badgen.net/pypi/v/libqasm)](https://pypi.org/project/libqasm/)
[![Anaconda](https://anaconda.org/qutech/libqasm/badges/version.svg)](https://anaconda.org/qutech/libqasm/)
[![API docs](https://readthedocs.org/projects/libqasm/badge/?version=latest)](https://libqasm.readthedocs.io/en/latest/)

## File organization

The original paper and BNF specification for the cQASM v1.0 are located in the `doc/v10` directory.
Please note however that the language has changed to some degree since then,
and the `qasm.bnf` has 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 in `v1x` directories, and the older API in `v10` directories.

- `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.<br/>
- `pybuild`: the Python library output files generated by `setup.py`.

### WIP: cQASM v3.0

We have started working on the parsing of cQASM v3.0 files, and that's why you will also see some `v3x` folders around.

However, the development of the new parser is still in a very early stage so its use through the API is completely unsupported.

## 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 `m4` and `zulu-opendjk` Conan packages on an ARMv8 architecture.
`m4` is required by Flex/Bison and `zulu-openjdk` provides 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.4
* `Bison` >= 3.0
* `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=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-](debug|release)[-compat]` naming convention. For example:
  - `release` is a Release build without tests and compatibility with the original API.
  - `tests-debug-compat` is a Debug build with tests and compatibility enabled.

All the profiles set the C++ standard to 20. All the `tests` profiles enable Address Sanitizer.

### Build options

Profiles 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 missing
```

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

## Install

### From Python

Install 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-local
```

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.4.1 . -pr=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

After installation, you should be able to use the bindings for the original API by just `import libQasm`.
The new API doesn't have Python bindings yet.

### From C++

The easiest way to use `libqasm` in 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 for `libqasm` to build:

* `Flex` >= 2.6.4
* `Bison` >= 3.0
* `Java JRE` >= 11

The original API headers are *not* included by default.
To enable those, pass <code><nobr>-o libqasm/*:compat=True</nobr></code> as a build option to Conan.

## 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 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
```
