MLIR Passes v1.0
Loading...
Searching...
No Matches
Development Guide

Ready to contribute to the Collection of MLIR Passes of the MQSS? This guide will help you get started.

Installing LLVM/MLIR

Since the MQSS compiler is based on LLVM/MLIR infrastructure and CudaQ compiler, your system must contain an installation of the LLVM project as a main prerequisite.

We recommend using the scripts given by CudaQ (see https://github.com/NVIDIA/cuda-quantum/tree/main/scripts) . Those scripts help install LLVM/MLIR.

We recommend clang16 as toolchain for the compilation of the LLVM project. Use the script install_toolchain.sh as follows:

bash scripts/install_toolchain.sh -t clang16

Then, you can install LLVM/MLIR and the prerequisites required by CudaQ by running:

LLVM_PROJECTS="clang;lld;mlir;python-bindings;compiler-rt" bash scripts/install_prerequisites.sh
Note
Do not forget to include compiler-rt in the LLVM_PROJECTS. This is required by some of the MQSS MLIR passes. If you do not include it, the project will not compile.

Initial Setup

  1. Fork the Passes repository on GitHub (see https://github.com/Munich-Quantum-Software-Stack/passes).

  2. Clone your fork locally

    git clone https://forked-url/passes

  3. Change into the project directory

    cd passes

  4. Create a branch for local development

    git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

Alternative: Visual Studio Code DevContainer (Strongly recommended)

Dev Containers (short for Development Containers) are an environment configuration that allows developers to create a consistent, isolated environment for development, testing, and deployment. They are typically used in conjunction with Visual Studio Code (VS Code) and Docker to ensure that the development environment is the same across all team members, regardless of their host machine or operating system.

  • Open the repository in VS-code
  • Use the Dev Container plugin to Open Folder in Container. This should pull and install LLVM/MLIR and the required dependencies.

The previous steps creates an isolated environment where you can tests this project. The project is located:

cd /workspaces/passes

Working on Source Code

Building the project requires a C++ compiler supporting C11 and a minimum CMake version of 3.19. The example devices and the tests require a C++ compiler supporting C++17 and C++20 dialects.

Configure and Build

This collection of MLIR passes uses CMake as its build system. However, we provide an script build.sh that first builds CudaQ library cudaq-mlir-runtime. Then, the script builds the MQSS passes project. You can configure and build the project as follows:

bash build.sh --jobs 5 --debug --mlir-dir "dir-to-mlir" --clang-dir "dir-to-clang"
--llvm-dir "dir-to-llvm" --build-tests --build-docs --build-tools

In the following, we describe each of the arguments accepted by build.sh.

  • --jobs (optional) The number of jobs utilized to configure and compile the project. If not specified, a single job is used to compile the project.
  • --debug (optional) Used to show debug information. If you want to build the project without debug information, do not include it.
  • --mlir-dir Path of your MLIR installation. E.g., /opt/llvm/lib/cmake/mlir/
  • --clang-dir Path of your Clang installation.
  • --llvm-dir Path of your LLVM installation.
  • --build-tests (optional) Include it if you want to build the tests of this project.
  • --build-docs (optional) Include it if you want to build this documentation.
  • --build-tools (optional) Include it if you want to build additional tools.

Running Tests

We use the GoogleTest framework for unit testing each MLIR pass in this collection. All tests are contained in the test directory. You can configure and build the project using CMake as follows:

bash build.sh --build-tests

The executables used to run the tests can be found at build/tests/. To verify all the available tests, run:

ctest --test-dir build --output-on-failure

Format for Comments

For the information to be displayed correctly in the documentation, it is essential that the comments follow the format required by Doxygen. Below you find some tags, that are commonly used within the documentation of a function:

  • @brief For a brief, one-line description of the function. Should always be provided.
  • @details For a longer, detailed description of the function.
  • @param To explain the usage of a parameter. Should be provided for each parameter.
  • @return To explain the return value. Should be provided if the function returns a value.
Note
In the current setting, the long description is always prepended with the brief description. So there is no need to repeat the brief description in the details.

Working on the Documentation

The documentation is generated using Doxygen, which is seamlessly integrated into the CMake build system.

Building the Documentation

The documentation can be built configuring the CMake as follows:

bash build.sh --build-docs

The generated webpage can be inspected by opening the file in docs/html/index.html in the CMake build directory.

Static Content

The generated webpage also contains four static sites, namely the main page, the support page, the FAQ page, and this development guide. The respective markdown files that serve as the source for those sites are contained in docs/ where index.md contains the content of the main page.

Dynamic Content

In order to include source files to be listed among the menu item API Reference/Files, these files must be marked as documented. This is accomplished by adding a comment like the following to the top of the file. Right now, this is done for all files in the include directory.

Further Links