Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README mini build & install guide #499

Merged
merged 1 commit into from
Sep 22, 2023
Merged

README mini build & install guide #499

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 114 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,117 @@ can be simulated on the QX simulator.

OpenQL's source code is released under the Apache 2.0 license.

For detailed user and contributor documentation, visit the
[ReadTheDocs](https://openql.readthedocs.io) page!
For detailed user and contributor documentation, please visit the
[ReadTheDocs](https://openql.readthedocs.io) page.

## Dependencies

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

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

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

```
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why does the C++ standard has to be specified in this command?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I approve of the review btw, but it's already merged anyway

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why does the C++ standard has to be specified in this command?

Good question Pablo. I think it is not enough specifying it in the CMake file. I think to remember having some compiling issues for not specifying it. However, I'm not 100% sure so I'm going to double check this, maybe remove it in a future. Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I approve of the review btw, but it's already merged anyway

Yes, sorry about that. I saw that Hans approved the PR this morning, so I quickly merged it, thinking it wasn't dangerous to have it in.

Anyway, I still have to work out with your help:

  1. How can I update the ReadTheDocs? Can I access the server that builds the docs and manually fire a build?
  2. Would it be possible to change the automatic building of the docs to be done after every PR at least, instead of after every release?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why does the C++ standard has to be specified in this command?

Good question Pablo. I think it is not enough specifying it in the CMake file. I think to remember having some compiling issues for not specifying it. However, I'm not 100% sure so I'm going to double check this, maybe remove it in a future. Thanks!

I have just checked. Without specifying the version, Conan tried to use C++11.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm absolutely fine with the merging of this PR :) ! Was just curious

Conan tried to use C++11

Ah, weird, maybe there's a setting in some Conan file that you can use instread of having to specify it on the command line?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think so. Profiles may help here. You should be able to pack all the options together in a profile, let's say x64-linux-debug, and then run it the next way: conan build . -pr x64-linux-debug.

Actually, for what I've just read, you could edit the default profile (the one that is created after doing conan profile detect), to set the compiler (for example). So you would do that once for each of your development machines.

This is one of the things I miss the most from CMake. If you have a look at this project of mine, you will see that I was configuring and building it like this:

C:\projects\the_modern_cpp_challenge> cmake --preset windows-msvc-debug-tests
C:\projects\the_modern_cpp_challenge> cmake --build --preset windows-msvc-debug-tests

Those presets were defined in a CMakePresets.json file. You could define some base presets, then specialize them, defining different options for each one...

Anyway, thanks for the comment because those Conan command lines we have at the moment are very unattractive. I know one can always create bash aliases, e.g. build_openql_debug or whatever, but it would be great to just download something and build it with a shorter command.

Copy link
Contributor Author

@rturrado rturrado Sep 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A little update on this conversation.

I have started using a CLion's Conan plugin, and as a result of the conversation for this issue that I opened, I've found out that:

  1. If you set CMAKE_CXX_STANDARD in your project, you don't need to pass the compiler version as a command line parameter. I've noticed we were not doing that in OpenQL.
  2. There is a way of not working with command line options at all, but defining them in a profile. For example, we could provide a conan/profiles folder together with the code, including a set of predefined profiles, e.g. tests-release, which would look something like:
include(default)

[settings]
openql/*:build_type=Release
[options]
openql/*:asan_enabled=False
openql/*:build_tests=True
openql/*:disable_unitary=True

And then just compile with conan build . -pr=conan/profiles/tests-release.

Or, these profiles may be copied to the ~./conan2/profiles folder, e.g. for this case, with a name such as openql-tests-release, and then build with conan build . -pr=openql-tests-release.

I'll create a separate PR for addressing these two changes. I think the second one can simplify a lot the user experience.

```

You may want to add one or more options to the `conan` command:

- <code><nobr>-o libqasm/*:compat</nobr></code>: enables installation of the headers for the original API, on top of the ones for the new API.
- <code><nobr>-o openql/*:build_type</nobr></code>: defaulted to `Release`, set to `Debug` if you want debug builds.
- <code><nobr>-o openql/*:build_tests</nobr></code>: defaulted to `False`, set to `True` if you want to build tests.
- <code><nobr>-o openql/*:disable_unitary</nobr></code>: defaulted to `False`, set to `True` if you want to disable unitary decomposition.
- <code><nobr>-o openql/*:shared</nobr></code>: 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

### From Python

Install from the project root directory as follows:

```
python3 -m pip install --verbose .
```

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

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 openql as ql`.
The new API doesn't have Python bindings yet.

### From C++

The easiest way to use OpenQL in a CMake project is to fetch the library and then link against it.

```
include(FetchContent)
FetchContent_Declare(OpenQL
GIT_REPOSITORY https://github.com/QuTech-Delft/OpenQL.git
GIT_TAG "<a given cqasm git tag>"
)
FetchContent_MakeAvailable(OpenQL)
target_include_directories(<your target> SYSTEM PRIVATE "${OpenQL_SOURCE_DIR}/include")
target_link_libraries(<your target> PUBLIC ql)
```
60 changes: 42 additions & 18 deletions docs/developer/build.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,37 +12,57 @@ This page documents how OpenQL and its documentation pages can be built and inst
difficulties with these instructions. If you're a new maintainer, update them accordingly via a PR, but
be mindful that something that works on your machine might not work on everyone's machine!


Dependencies
------------

The following packages are required to compile OpenQL from sources:
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 (Linux: gcc, MacOS: LLVM/clang, Windows: Visual Studio 17 2022, MSVC 19.35.32217.1)
- CMake >= 3.12
- conan 2.0
- git
- Python 3.x + pip, with the following packages:
Python builds- 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)
- 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``

.. note::
The connection between Sphinx and SWIG's autodoc functionalities is very iffy,
but aside from tracking everything manually or forking SWIG there is not much that can be done about it.
Because of this, not all Sphinx versions will build correctly,
hence why the Sphinx version is pinned.
Sphinx 4.x for example crashes on getting the function signature of property getters/setters.
Sphinx 4.x for example crashes on getting the function signature of property getters/setters.


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


Windows-specific instructions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -54,8 +74,8 @@ Windows-specific instructions

Dependencies can be installed with:

- `cmake 3.12.0 <https://github.com/Kitware/CMake/releases/download/v3.12.0/cmake-3.12.0-windows-x86_64.msi>`_
- `swigwin 4.0.0 <https://sourceforge.net/projects/swig/files/swigwin/swigwin-4.0.0/swigwin-4.0.0.zip/download>`_
- `CMake 3.12.0 <https://github.com/Kitware/CMake/releases/download/v3.12.0/cmake-3.12.0-windows-x86_64.msi>`_
- `SWIG for Windows 4.0.0 <https://sourceforge.net/projects/swig/files/swigwin/swigwin-4.0.0/swigwin-4.0.0.zip/download>`_

Make sure the above mentioned binaries are added to the system path.

Expand Down Expand Up @@ -115,6 +135,7 @@ for which some modifications (may?) need to be made first.

$env:EnvVariableName = "new-value"


MacOS-specific instructions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand All @@ -132,6 +153,7 @@ All dependencies can be installed using `Homebrew <https://brew.sh>`_ and pip:
Make sure the above mentioned binaries are added to the system path in front of ``/usr/bin``,
otherwise CMake finds the default versions.


Linux-specific instructions
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -199,7 +221,7 @@ You'd have to remember to uninstall if you ever end up moving it.
The ``setup.py`` script (as invoked by pip in the above commands, again, do not invoke it directly!)
listens to a number of environment variables to configure the installation and the compilation process:

- ``OPENQL_BUILD_TYPE``: it can be ``Debug`` or ``Release``.
- ``OPENQL_BUILD_TYPE``: defaulted to ``Release``, set to ``Debug`` if you want debug builds.
- ``OPENQL_BUILD_TESTS``: defaulted to ``OFF``, set to ``ON`` if you want to build tests.
- ``OPENQL_DISABLE_UNITARY``: defaulted to ``OFF``, set to ``ON`` if you want to disable unitary decomposition.
This speeds up compile time if you don't need it.
Expand Down Expand Up @@ -240,6 +262,8 @@ The results end up in a ``test_output`` folder, at the same location from where

::

# This first line only has to be run once, not every time
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
cd build/Debug
ctest -C Debug --output-on-failure
Expand All @@ -261,7 +285,7 @@ Assuming you have installed the required dependencies to do so, the procedure is

::

# first build/install the qutechopenql Python package!
# First build/install the qutechopenql Python package!
cd docs
rm -rf doxygen # optional: ensures all doxygen pages are rebuilt
make clean # optional: ensures all Sphinx pages are rebuilt
Expand Down