diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c3c5a8583..980086f56 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -43,7 +43,10 @@ jobs: - name: Configure and build run: | conan profile detect - conan build . -s:h compiler.cppstd=23 -s:h openql/*:build_type=${{ matrix.build_type }} -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing + build_type=${{ matrix.build_type }} + lowercase_build_type=$(echo ${build_type} | tr '[:upper:]' '[:lower:]') + conan build . -pr=conan/profiles/tests-${lowercase_build_type} -b missing + shell: bash - name: Test working-directory: build/${{ matrix.build_type }} run: ctest -C ${{ matrix.build_type }} --output-on-failure @@ -87,7 +90,7 @@ jobs: python3 -m venv venv source venv/bin/activate python3 -m pip install --upgrade pip conan - conan build . -s:h compiler.cppstd=23 -s:h openql/*:build_type=Release -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing + conan build . -pr=conan/profiles/tests-release -b missing - name: Test working-directory: build/Release run: ctest -C Release --output-on-failure diff --git a/README.md b/README.md index 0760a382f..ea8d9f880 100644 --- a/README.md +++ b/README.md @@ -23,26 +23,28 @@ For detailed user and contributor documentation, please visit the The following utilities are required to compile OpenQL from sources: - * C++ compiler with C++23 support (gcc 11, clang 14, msvc 17) - * `CMake` >= 3.12 - * `git` - * `Python` 3.x plus `pip`, with the following package: - * `conan` >= 2.0 +- C++ compiler with C++23 support (gcc 11, clang 14, msvc 17) +- `CMake` >= 3.12 +- `git` +- `Python` 3.x plus `pip`, with the following package: + - `conan` >= 2.0 ### Python build specific dependencies - * `SWIG` (Linux: >= 3.0.12, Windows: >= 4.0.0) - * And the following Python packages. - * `plumbum` - * `qxelarator` - * `setuptools` - * `wheel` - * And, optionally, these: - * Testing: `libqasm`, `make`, `numpy`, and `pytest` - * Documentation generation: `doxygen`, `m2r2`, `sphinx==7.0.0`, and `sphinx-rtd-theme` - * Convert graphs from `dot` to `pdf`, `png`, etc: `Graphviz Dot` utility - * Visualize generated graphs in `dot` format: `XDot` - * Use the visualizer in MacOS: `XQuartz` +- `SWIG` (Linux: >= 3.0.12, Windows: >= 4.0.0) +- Optionally: + - Documentation generation: `doxygen` + - Convert graphs from `dot` to `pdf`, `png`, etc: `Graphviz Dot` utility + - Visualize generated graphs in `dot` format: `XDot` + - Use the visualizer in MacOS: `XQuartz` +- And the following Python packages: + - `plumbum` + - `qxelarator` + - `setuptools` + - `wheel` + - Optionally: + - Testing: `numpy`, and `pytest` + - Documentation generation: `m2r2`, `sphinx==7.0.0`, and `sphinx-rtd-theme` ### ARM specific dependencies @@ -50,33 +52,54 @@ We are having problems when using the `m4` and `zulu-opendjk` Conan packages on `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 +- `Flex` >= 2.6.4 +- `Bison` >= 3.0 +- `Java JRE` >= 11 ## Build This version of OpenQL 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 `OpenQL` dependencies, as well as the compilation, can be done in one go. Notice: -- the `conan profile` command only has to be run once. -- the `conan build` command is building `OpenQL` in Debug mode with tests. +The installation of `OpenQL` dependencies, as well as the compilation, can be done in one go. ``` git clone https://github.com/QuTech-Delft/OpenQL.git cd OpenQL 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 `OpenQL` 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)[-unitary]` naming convention. For example: +- `release` is a Release build without tests and unitary decomposition disabled. +- `tests-debug-unitary` is a Debug build with tests and unitary decomposition enabled. + +All the profiles set the C++ standard to 23. + +### 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=23 -s:h openql/*:build_type=Debug -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing ``` -You may want to add one or more options to the `conan` command: +These are the list of options that could be specified whether in a profile or in the command line: -- -o libqasm/*:compat: enables installation of the headers for the original API, on top of the ones for the new API. -- -o openql/*:build_type: defaulted to `Release`, set to `Debug` if you want debug builds. -- -o openql/*:build_tests: defaulted to `False`, set to `True` if you want to build tests. -- -o openql/*:disable_unitary: defaulted to `False`, set to `True` if you want to disable unitary decomposition. -- -o openql/*:shared: defaulted to `False`, set to `True` if you want OpenQL to be built as a shared library. The default option is mandatory on Windows. +- `openql/*:build_type`: defaulted to `Release`, set to `Debug` if you want Debug builds. +- `openql/*:build_tests`: defaulted to `False`, set to `True` if you want to build tests. +- `openql/*:disable_unitary`: defaulted to `False`, set to `True` if you want to disable unitary decomposition. +- `openql/*:shared`: defaulted to `False`, set to `True` if you want OpenQL to be built as a shared library. +The default option is mandatory on Windows. ## Install @@ -85,13 +108,13 @@ You may want to add one or more options to the `conan` command: Install from the project root directory as follows: ``` -python3 -m pip install --verbose . +python3 -m pip install -v . ``` You can test if it works by running: ``` -python3 -m pytest +python3 -m pytest -v ``` ### From C++ @@ -99,7 +122,7 @@ python3 -m pytest The `CMakeLists.txt` file in the root directory includes install targets: ``` -conan create --version 0.11.2 . -s:h compiler.cppstd=23 -s:h openql/*:build_type=Debug -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing +conan create --version 0.11.2 . tests-debug -b missing ``` You can test if it works by doing: @@ -130,3 +153,10 @@ FetchContent_MakeAvailable(OpenQL) target_include_directories( SYSTEM PRIVATE "${OpenQL_SOURCE_DIR}/include") target_link_libraries( PUBLIC ql) ``` + +Note that the following dependencies are required for `OpenQL` to build: + +- `Flex` >= 2.6.4 +- `Bison` >= 3.0 +- `Java JRE` >= 11 + \ No newline at end of file diff --git a/conan/profiles/debug b/conan/profiles/debug new file mode 100644 index 000000000..be7b87c74 --- /dev/null +++ b/conan/profiles/debug @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Debug + +[options] +openql/*:build_tests=False +openql/*:disable_unitary=True diff --git a/conan/profiles/debug-unitary b/conan/profiles/debug-unitary new file mode 100644 index 000000000..00fe4314a --- /dev/null +++ b/conan/profiles/debug-unitary @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Debug + +[options] +openql/*:build_tests=False +openql/*:disable_unitary=False diff --git a/conan/profiles/release b/conan/profiles/release new file mode 100644 index 000000000..5964efded --- /dev/null +++ b/conan/profiles/release @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Release + +[options] +openql/*:build_tests=False +openql/*:disable_unitary=True diff --git a/conan/profiles/release-unitary b/conan/profiles/release-unitary new file mode 100644 index 000000000..9e1a012fb --- /dev/null +++ b/conan/profiles/release-unitary @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Release + +[options] +openql/*:build_tests=False +openql/*:disable_unitary=False diff --git a/conan/profiles/tests-debug b/conan/profiles/tests-debug new file mode 100644 index 000000000..485fc5d73 --- /dev/null +++ b/conan/profiles/tests-debug @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Debug + +[options] +openql/*:build_tests=True +openql/*:disable_unitary=True diff --git a/conan/profiles/tests-debug-unitary b/conan/profiles/tests-debug-unitary new file mode 100644 index 000000000..daa1a6556 --- /dev/null +++ b/conan/profiles/tests-debug-unitary @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Debug + +[options] +openql/*:build_tests=True +openql/*:disable_unitary=False diff --git a/conan/profiles/tests-release b/conan/profiles/tests-release new file mode 100644 index 000000000..4056b74fd --- /dev/null +++ b/conan/profiles/tests-release @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Release + +[options] +openql/*:build_tests=True +openql/*:disable_unitary=True diff --git a/conan/profiles/tests-release-unitary b/conan/profiles/tests-release-unitary new file mode 100644 index 000000000..6448086e2 --- /dev/null +++ b/conan/profiles/tests-release-unitary @@ -0,0 +1,9 @@ +include(default) + +[settings] +compiler.cppstd=23 +openql/*:build_type=Release + +[options] +openql/*:build_tests=True +openql/*:disable_unitary=False diff --git a/docs/developer/build.rst b/docs/developer/build.rst index a125696a2..d100756d4 100644 --- a/docs/developer/build.rst +++ b/docs/developer/build.rst @@ -30,19 +30,23 @@ Python builds- specific dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``SWIG`` (Linux: >= 3.0.12, Windows: >= 4.0.0) + - Optionally: + + - Documentation generation: ``doxygen`` + - Convert graphs from `dot` to `pdf`, `png`, etc: ``Graphviz Dot`` utility + - Visualize generated graphs in `dot` format: ``XDot`` + - Use the visualizer in MacOS: ``XQuartz`` + - And the following Python packages: - ``plumbum`` - ``qxelarator`` - ``setuptools`` - ``wheel`` - - And, optionally, these: + - Optionally: - - Testing: ``libqasm``, ``make``, ``numpy``, and ``pytest`` - - Documentation generation: ``doxygen``, ``m2r2``, ``sphinx==7.0.0``, and ``sphinx-rtd-theme`` - - Convert graphs from `dot` to `pdf`, `png`, etc: ``Graphviz Dot`` utility - - Visualize generated graphs in `dot` format: ``XDot`` - - Use the visualizer in MacOS: ``XQuartz`` + - Testing: ``numpy`` and ``pytest`` + - Documentation generation: ``m2r2``, ``sphinx==7.0.0``, and ``sphinx-rtd-theme`` .. note:: The connection between Sphinx and SWIG's autodoc functionalities is very iffy, @@ -59,9 +63,9 @@ We are having problems when using the ``m4`` and ``zulu-opendjk`` Conan packages ``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 +- ``Flex`` >= 2.6.4 +- ``Bison`` >= 3.0 +- ``Java JRE`` >= 11 Windows-specific instructions @@ -190,13 +194,13 @@ Running the following command in a terminal/Power Shell from the root of the Ope :: - pip install -v . + python3 -pip install -v . Or in editable mode by the command: :: - pip install -v -e . + python3 -pip install -v -e . Editable mode has the advantage that you'll get incremental compilation if you ever change OpenQL's C++ files, but it's a bit more fragile in that things will break if you move the OpenQL repository around later. @@ -242,12 +246,7 @@ from the root of the OpenQL repository) using :: - pytest -v - -.. note:: - If ``pytest`` is unrecognized, you should be able to use ``python -m pytest`` or ``python3 -m pytest`` instead - (making sure to use the same Python version that the ``pip`` you installed the package with corresponds to). - + python3 -m pytest -v Building the C++ tests and programs ----------------------------------- @@ -259,18 +258,52 @@ The tests are run with the ``build/`` directory as the working direc The results end up in a ``test_output`` folder, at the same location from where the tests are run (``example_output`` if we are running an example instead of a test). - :: - # This first line only has to be run once, not every time + git clone https://github.com/QuTech-Delft/OpenQL.git + cd OpenQL conan profile detect - conan build . -s:h compiler.cppstd=23 -s:h openql/*:build_type=Debug -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing + conan build . -pr=conan/profiles/tests-debug -b missing cd build/Debug ctest -C Debug --output-on-failure .. note:: - The default option ``-o openql/*shared=False`` is mandatory on Windows + - The ``conan profile`` command only has to be run only once, and not before every build. + - The ``conan build`` command is building ``OpenQL`` 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)[-unitary]`` naming convention. For example: + +- ``release`` is a Release build without tests and unitary decomposition disabled. +- ``tests-debug-unitary`` is a Debug build with tests and unitary decomposition enabled. + +All the profiles set the C++ standard to 23. + +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=23 -s:h openql/*:build_type=Debug -o openql/*:build_tests=True -o openql/*:disable_unitary=True -b missing + +These are the list of options that could be specified whether in a profile or in the command line: + +- ``openql/*:build_type``: defaulted to ``Release``, set to ``Debug`` if you want Debug builds. +- ``openql/*:build_tests``: defaulted to ``False``, set to ``True`` if you want to build tests. +- ``openql/*:disable_unitary``: defaulted to ``False``, set to ``True`` if you want to disable unitary decomposition. +- ``openql/*:shared``: defaulted to ``False``, set to ``True`` if you want OpenQL to be built as a shared library. + +.. note:: + + The default option ``openql/*shared=False`` is mandatory on Windows because the executables can't find the OpenQL DLL in the build tree that MSVC generates, and static linking works around that. It works just fine when you manually place the DLL in the same directory as the test executables though,