{"id":20779748,"url":"https://github.com/openqasm/qe-qasm","last_synced_at":"2026-03-27T02:16:05.211Z","repository":{"id":215116427,"uuid":"557996466","full_name":"openqasm/qe-qasm","owner":"openqasm","description":"A LALR(1) OpenQASM Parser and AST Generator.","archived":false,"fork":false,"pushed_at":"2024-07-29T12:05:54.000Z","size":2015,"stargazers_count":13,"open_issues_count":12,"forks_count":5,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-12-26T18:48:06.616Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"OpenQASM","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openqasm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-26T17:43:20.000Z","updated_at":"2025-08-25T17:08:48.000Z","dependencies_parsed_at":"2024-06-12T20:29:29.158Z","dependency_job_id":"092f78b4-eb26-41c4-b319-282db1dfddb6","html_url":"https://github.com/openqasm/qe-qasm","commit_stats":null,"previous_names":["openqasm/qe-qasm"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/openqasm/qe-qasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openqasm%2Fqe-qasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openqasm%2Fqe-qasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openqasm%2Fqe-qasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openqasm%2Fqe-qasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openqasm","download_url":"https://codeload.github.com/openqasm/qe-qasm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openqasm%2Fqe-qasm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31009857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T01:56:05.093Z","status":"online","status_checked_at":"2026-03-27T02:00:08.055Z","response_time":164,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T13:29:28.903Z","updated_at":"2026-03-27T02:16:04.453Z","avatar_url":"https://github.com/openqasm.png","language":"OpenQASM","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qe-qasm\nThe Quantum Engine's implementation of an OpenQASM v3.0 lexer and parser written in C++. The Quantum Engine is a system comprised of low-level software components enabling the execution of quantum programs in quantum hardware.\nThe parser is based on [Flex](https://github.com/westes/flex) and [Bison](https://www.gnu.org/software/bison/),\nand therefore it is a [LALR parser](https://en.wikipedia.org/wiki/LALR_parser).\n\nThis is a CMake Project. It builds four libraries:\n- libqasmParser.{so|a}\n- libqasmAST.{so|a}\n- libqasmFrontend.{so|a}\n- libqasmDIAG.{so|a}\n\nand a simple CLI tool [QasmParser](./examples/QasmParser/) for demonstrations and testing.\n\nThese libraries can be used to work on further development of a\nfully functional OpenQASM 3 compiler. In particular, the library is used by the [qe-compiler](https://github.com/openqasm/qe-compiler) to\nparse OpenQASM 3 source files to MLIR.\n\n## Contents\n- [qe-qasm](#qe-qasm)\n  - [Contents](#contents)\n  - [Building from source](#building-from-source)\n    - [Conan](#conan)\n      - [Building for development and debugging](#building-for-development-and-debugging)\n    - [Make](#make)\n      - [Running Tests](#running-tests)\n  - [Static Code Checks](#static-code-checks)\n  - [CI and Release Cycle](#ci-and-release-cycle)\n    - [CI](#ci)\n    - [Branches](#branches)\n    - [Tags](#tags)\n    - [Release cycle](#release-cycle)\n    - [Example release cycle](#example-release-cycle)\n\n\n## Building from source\n\nThe parser's build system is driven by [Cmake](https://cmake.org/).\nFor simplicity of building, packaging and distribution we provide a [conan](https://conan.io/)\npackager and recommend this for development/integration.\n\nCurrently the supported platforms are Linux and OSX. It is possible to build on Windows using\n[WSL](https://learn.microsoft.com/en-us/windows/wsl/install).\n\n### Conan\n- Clone this repo: `git clone git@github.com:openqasm/qe-qasm.git`\n- Install build dependencies: `pip install -r requirements-dev.txt`\n  - It is recommended to use a Python virtual environment for this\n- The package may be built and installed to conan with: `conan create . --build=outdated -pr:h default -pr:b default`\n   - This will build the conan package and install it locally. The version will be detected automatically from the repo tag.\n   - If you wish to override the package name, version or remote do so by calling conan with `conan create . \u003cpackage\u003e/\u003cversion\u003e@remote -pr:h default -pr:b default`\n\n#### Building for development and debugging\n- Create a build directory: `mkdir build \u0026\u0026 cd build/`\n- Install package with: `conan install .. --build=outdated -pr:h default -pr:b default` which will install and build all missing dependencies\n- Build the package with: `conan build ..`\n- The package tests may be run with: `conan build .. --test`\n\n\n### Make\n\n- Clone this repo: `git clone git@github.com:openqasm/qe-qasm.git`\n- Install build dependencies: `pip install -r requirements-dev.txt`\n   - It is recommended to use a Python virtual environment for this\n- Install a recent GCC or LLVM/clang compiler that supports C++17,\n   GNU MP, GNU MPFR, GNU MPC, GNU Flex and GNU Bison installed on your system.\n   Please make sure you install the `devel` packages for GNU MP, GNU MPFR\n   and GNU MPC.\n\n   Recommended versions are:\n   - GCC: \u003e= 9.2\n   - LLVM: \u003e= 10.0\n- Install the package dependencies:\n  - Versions:\n   - Bison: \u003e= 3.6.2\n   - Flex: \u003e= 2.6.1\n   - GNU MP: \u003e= 5.0.0\n   - GNU MPFR: \u003e= 4.0.0\n   - GNU MPC \u003e= 1.0.0\n   - CMake: \u003e= 3.17.0\n  - Platforms:\n    - Linux: Recent versions of Fedora (32 or 33) or Ubuntu (20.X.X) should\n   satisfy these version requirements.\n     - On Fedora (RedHat), the names of the packages are:\n      - gmp(gmp-devel)\n      - mpfr(mpfr-devel)\n      - libmpc(libmpc-devel)\n\n     - Apple Darwin (MacOS):\n      - GCC is a symlink to clang. Building with GCC on MacOS is not supported.\n      - You need XCode \u003e= 14.2. Lower versions do not handle static initializations\n        correctly on MacOS M1 (AArch64).\n      - Most of the Toolchain utilities provided by Darwin by default in /usr/bin\n        are much too old to be able to build qe-qasm correctly. Recent equivalents\n        of these tools must be downloaded from Homebrew [ https://brew.sh/ ].\n      - List of dependencies that must be installed from Homebrew:\n        - flex\n        - bison\n        - gmake\n        - cmake\n        - gmp\n        - mpfr\n        - libmpc\n        - m4\n      - Please consult the Homebrew documentation on how to use Homebrew.\n      - If you want to use the Homebrew LLVM:\n        The LLVM lld linker [lld] needs a symlink created to itself in order to\n        work correctly. To do so:\n        - cd to the Homebrew LLVM installation directory:\n          - /opt/homebrew/opt/llvm/bin on MacOS M1\n          - /usr/local/opt/llvm/bin on MacOS x86_64\n        - ln -sf lld ld64.lld\n- Prepare the build directory:  `mkdir build \u0026\u0026 cd build`\n- Configure: `cmake -G \"Unix Makefiles\" ..`\n  - If dependencies are not installed or properly setup errors may be raised\n- Build with: `make`\n  - This will build both static and shared libraries\n-  Running: `make DESTDIR=/path/to/DESTDIR/` in the build directory will install the\n    required libraries and header files to `/path/to/DESTDIR/`.\n\n#### Running Tests\n\n- There are a number of OpenQASM 2.0 and OpenQASM 3.0 tests in the\n    directory `./tests``.\n- You can run any of these tests manually as: `./QasmParser -I../../qasm/tests/include ../../qasm/tests/src/\u003ctest-name\u003e.qasm` from the 'build/bin' directory.\n- You can also run the ``./short-run-tests.sh`` shell script found in the tests\n   directory. It runs all the tests in the ``../../tests/src`` directory. This script\n   is intended to be run from the `build/bin`` directory.\n   Alternatively, you can run the 'make test' target from the toplevel `build``\n   directory. This will run all the tests using the CMake CTest utility.\n- QasmParser will tell you if it could parse and generate the AST for the\n    OpenQASM program correctly, or if it encountered an errror.\n- A pseudo-XML output of the AST being built by the parser will be printed\n    either to stdout, or to the file used to capture QasmParser's output.\n\n\n## Static Code Checks\nThe easiest, fastest, and most automated way to integrate the formatting into your workflow\nis via [pre-commit](https://pre-commit.com). Note that this tool requires an internet connection\nto initially setup because the formatting tools needs to be downloaded.\n\n**In environments without an internet connection, please see one of the other solutions documented\nbelow.**\n\nThese should be installed and setup prior to any development work so that they are not forgotten\nabout. The setup is straight forward:\n\n```bash\npip install pre-commit\npre-commit install\n```\n\nThe first time `pre-commit install` is run, it will take a minute to setup the environment.\n\nAfter installation, the hooks will be run prior to every commit, and will be run against all staged\nchanges. Optionally, you can trigger this run via `pre-commit run`.\n\nIf you wish to run the hooks against the entire repository, run:\n\n```bash\npre-commit run --all-files\n```\n\nThe other checks that are performed can be seen in\n[`.pre-commit-config.yaml`](.pre-commit-config.yaml). At the time of writing, these are:\n\n- No direct committing to `main`, or `release/*`\n- Check json for validity\n- Ensure newline character at the end of files\n- Trim end of line whitespace characters\n- Check for no merge conflict lines accidentally being staged\n- Clang format\n- Python block (line length 100)\n\n\n## CI and Release Cycle\nPlease keep the following points in mind when developing:\n\n### CI\nCI is currently run on every pull request against the `main` branch.\nAll CI processes are based on the [conan package](#conan) build.\n\n### Branches\n\n* `main`:\nThe main branch is used for the development of the next release.\nIt is updated frequently and should *not* be considered stable. On the development\nbranch, breaking changes can and will be introduced.\nAll efforts should be made to ensure that the development branch is maintained in\na self-consistent state that is passing continuous integration (CI).\nChanges should not be merged unless they are verified by CI.\n* `release/\u003cmajor.minor\u003e` branches:\nBranches under `release/\u003cmajor.minor\u003e` are used to maintain released versions of the qe-qasm parser.\nThey contain the version of the parser corresponding to the\nrelease as identified by its [semantic version](https://semver.org/). For example,\n`release/1.5` would be the compiler version for major version 1 and minor version 5.\nOn these branches, the parser\nis considered stable. The only changes that may be merged to a release branch are\npatches/bugfixes. When a patch is required when possible the fix should\nfirst be made to the development branch through a pull request.\nThe fix should then be backported from the development branch to the\ntarget release branch (of name `release/\u003cmajor.minor\u003e`) by creating a pull request on\nGithub into the target release branch with the relevant cherry-picked commits.\nThe new release branch `HEAD` should be tagged (see [Tags](#tags)) with a new\n`\u003cmajor.minor.patch\u003e` version and pushed to Github.\n\n### Tags\nGit tags are used to tag the specific commit associated with a versioned release.\nTags must take the form of `v\u003cmajor\u003e.\u003cminor\u003e.\u003cpatch\u003e-\u003clabels\u003e`. For example the semver\n`v1.5.1` would point to the parser release with major version 1,\nminor version 5, and, patch version 1. The current development version would therefore be MINOR+1\n`v1.6.0`. All official releases when tagged must always point to the current HEAD\nof a release branch.\n\n### Release cycle\nTo release a version a new version:\n\n- (Option A) If releasing a major/minor version create a new release branch for the version (See [Branches](#branches)).\n   This should be cut from the latest development branch.\n   ```bash\n   git checkout -b release/\u003cversion\u003e \u003cbase\u003e\n   git push -u origin release/\u003cversion\u003e\n   ```\n- (Option B) If releasing a patch version:\n  -  checkout the existing release branch for your target major/minor version to apply the patch\n   ```bash\n   git checkout -b \u003cbackport\u003e-\u003cdesc\u003e-release/\u003cversion\u003e release/\u003cversion\u003e\n   ```\n  - Apply your changes (or cherry-pick existing commits) to your new branch and then push your branch to Github\n   ```bash\n   git push -u origin \u003cyour-branch\u003e\n   ```\n  - Make a PR from your new branch into the target `release/\u003cversion\u003e` branch with the form `[Backport] \u003cTitle\u003e` and merge the PR\n- Create a new tag with the required semantic version number (see [Tags](#tags)), tagging the `HEAD` of the target `release/\u003cversion\u003e` branch.\n  Push the tag to Github which will trigger CI.\n    ```bash\n    git tag -a v\u003cversion\u003e -m \"\u003cdescription\u003e e.g. release v\u003cx\u003e.\u003cy\u003e.\u003cz\u003e\" # \u003c- where version is the version number of the tag.\n    git push -u origin v\u003cversion\u003e\n    ```\n\n### Example release cycle\n\nFor this example assume the current release of the parser is version `0.5.1`. This will correspond to a commit\non `release/0.5`. The project's development branch reflects the development state of the next release - `0.6.0`\nand is referred to by version as `0.6.0-dev`.\n\nTo trigger a bugfix release - `0.5.2`:\n1. Create a PR into `release/0.5` with all required changes. The PR ideally should begin with title of the form `[Backport] \u003cTitle\u003e`.\n   These may be backported commits from `main`.\n2. Upon merger of the PR tag the HEAD of `release/0.5` with `v0.5.2` and push to Github.\n\nTo trigger a minor release - `0.6.0`:\n1. Create a new release branch `release/0.6` using the current development branch (`main`) as the base branch, eg., `git checkout -b release/0.6 main`.\n   - *Note*: Branch protection rules are in place for release branches and these steps may only be completed by project\nadministrators.\n2. Push this branch to Github.\n3. Tag the branch with `v0.6.0` and push to Github.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenqasm%2Fqe-qasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenqasm%2Fqe-qasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenqasm%2Fqe-qasm/lists"}