From 2600a1e7fd3e22b536188cc0ec23c8d19400d4ae Mon Sep 17 00:00:00 2001 From: rturrado <68099809+rturrado@users.noreply.github.com> Date: Wed, 27 Sep 2023 18:11:54 +0200 Subject: [PATCH 1/4] Adding conan profiles. --- .github/workflows/test.yml | 7 ++-- README.md | 48 ++++++++++++++++++++++------ conan/profiles/debug | 9 ++++++ conan/profiles/debug-unitary | 9 ++++++ conan/profiles/release | 9 ++++++ conan/profiles/release-unitary | 9 ++++++ conan/profiles/tests-debug | 9 ++++++ conan/profiles/tests-debug-unitary | 9 ++++++ conan/profiles/tests-release | 9 ++++++ conan/profiles/tests-release-unitary | 9 ++++++ 10 files changed, 115 insertions(+), 12 deletions(-) create mode 100644 conan/profiles/debug create mode 100644 conan/profiles/debug-unitary create mode 100644 conan/profiles/release create mode 100644 conan/profiles/release-unitary create mode 100644 conan/profiles/tests-debug create mode 100644 conan/profiles/tests-debug-unitary create mode 100644 conan/profiles/tests-release create mode 100644 conan/profiles/tests-release-unitary 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..57bc3c35d 100644 --- a/README.md +++ b/README.md @@ -59,24 +59,45 @@ So, for the time being, we are installing Flex/Bison and Java manually for this 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=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 @@ -99,7 +120,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 +151,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 From 86466988e0a2e70c68385451b621ab106d506f34 Mon Sep 17 00:00:00 2001 From: rturrado <68099809+rturrado@users.noreply.github.com> Date: Wed, 27 Sep 2023 18:51:08 +0200 Subject: [PATCH 2/4] Updated docs. --- README.md | 52 ++++++++++++++-------------- docs/developer/build.rst | 73 ++++++++++++++++++++++++++++------------ 2 files changed, 79 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 57bc3c35d..5c6ed1556 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,9 +52,9 @@ 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 @@ -106,13 +108,13 @@ The default option is mandatory on Windows. 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++ @@ -154,7 +156,7 @@ 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 +- `Flex` >= 2.6.4 +- `Bison` >= 3.0 +- `Java JRE` >= 11 \ No newline at end of file diff --git a/docs/developer/build.rst b/docs/developer/build.rst index a125696a2..5ba69cf22 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,50 @@ 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=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, From 8bc2dfff4329e86a7eb1d97dbe5293e3c5484e34 Mon Sep 17 00:00:00 2001 From: rturrado <68099809+rturrado@users.noreply.github.com> Date: Thu, 28 Sep 2023 10:59:38 +0200 Subject: [PATCH 3/4] Fixed build.rst after building docs locally and checking the output. --- docs/developer/build.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/developer/build.rst b/docs/developer/build.rst index 5ba69cf22..56d5ab11a 100644 --- a/docs/developer/build.rst +++ b/docs/developer/build.rst @@ -274,7 +274,8 @@ The results end up in a ``test_output`` folder, at the same location from where - 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* +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: @@ -284,13 +285,14 @@ They follow the ``[tests-](debug|release)[-unitary]`` naming convention. For exa All the profiles set the C++ standard to 23. -*Build options* +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 -```` +:: + + 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: From e614267a357dd5395e0a31cd37437aee8bd0979b Mon Sep 17 00:00:00 2001 From: rturrado <68099809+rturrado@users.noreply.github.com> Date: Fri, 29 Sep 2023 02:55:12 +0200 Subject: [PATCH 4/4] Changed '-pr=tests-debug' to '-pr=conan/profiles/tests-debug' in docs. --- README.md | 2 +- docs/developer/build.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5c6ed1556..ea8d9f880 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The installation of `OpenQL` dependencies, as well as the compilation, can be do git clone https://github.com/QuTech-Delft/OpenQL.git cd OpenQL conan profile detect -conan build . -pr=tests-debug -b missing +conan build . -pr=conan/profiles/tests-debug -b missing ``` Notice: diff --git a/docs/developer/build.rst b/docs/developer/build.rst index 56d5ab11a..d100756d4 100644 --- a/docs/developer/build.rst +++ b/docs/developer/build.rst @@ -263,7 +263,7 @@ The results end up in a ``test_output`` folder, at the same location from where git clone https://github.com/QuTech-Delft/OpenQL.git cd OpenQL conan profile detect - conan build . -pr=tests-debug -b missing + conan build . -pr=conan/profiles/tests-debug -b missing cd build/Debug ctest -C Debug --output-on-failure