Skip to content
This repository has been archived by the owner on Aug 19, 2023. It is now read-only.

Update building from source instructions #1439

Merged
merged 9 commits into from
Mar 23, 2022
Merged

Update building from source instructions #1439

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
be2cfec
Update building from source instructions
mtreinish Mar 1, 2022
b745e58
Merge branch 'master' into update-install-docs-terra
mtreinish Mar 1, 2022
a991fdf
Apply suggestions from code review
mtreinish Mar 1, 2022
1c2ab2c
Merge branch 'master' into update-install-docs-terra
mtreinish Mar 11, 2022
98df40f
Consistently capitalise "Rust"
jakelishman Mar 22, 2022
2420e7b
Add section on modifying rust extension
mtreinish Mar 23, 2022
f5df9d6
Merge branch 'master' into update-install-docs-terra
mtreinish Mar 23, 2022
d4487d7
Fix typos
jakelishman Mar 23, 2022
1c48345
Empty-Commit to retrigger ci after outage
mtreinish Mar 23, 2022
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
87 changes: 21 additions & 66 deletions docs/contributing_to_qiskit.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -700,12 +700,6 @@ from system-wide packages. This way, we avoid inadvertently becoming dependent o
particular system configuration. For developers, this also makes it easy to maintain multiple
environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).

.. note::

**M1 Mac users:** Some Qiskit dependencies may not yet be available in PyPI. Until they are,
Conda is recommended.


.. tabbed:: Python venv

All Python versions supported by Qiskit include built-in virtual environment module
Expand Down Expand Up @@ -750,39 +744,17 @@ environments (e.g. one per supported Python version, for older versions of Qiski
Installing Terra from Source
============================

Installing from source requires that you have a C++ compiler on your system that supports
C++11.


.. tabbed:: Compiler for Linux

On most Linux platforms, the necessary GCC compiler is already installed.

.. tabbed:: Compiler for macOS

If you use macOS, you can install the Clang compiler by installing XCode.
Check if you have XCode and Clang installed by opening a terminal window and entering the
following.

.. code:: sh

clang --version

Install XCode and Clang by using the following command.

.. code:: sh

xcode-select --install
Installing from source requires that you have the Rust compiler on your system.
To install the Rust compiler the recommended path is to use rustup, which is
a cross-platform rust installer. To use rustup you can go to:
jakelishman marked this conversation as resolved.
Show resolved Hide resolved

.. tabbed:: Compiler for Windows
https://rustup.rs/
Copy link
Member

Choose a reason for hiding this comment

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

This URL just ends up kind of awkwardly in its own paragraph - perhaps it'd be better to hyperlink the words "rustup, which is a cross-platform Rust installer"?

Copy link
Member Author

Choose a reason for hiding this comment

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

I was trying to make the link pretty prominent instead of hidden behind a hyperlink since I expect most people reading this section will want to click it. I was worried a hyperlink wouldn't be super clear.

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, that's fair.


On Windows, it is easiest to install the Visual C++ compiler from the
`Build Tools for Visual Studio 2017 <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017>`__.
You can instead install Visual Studio version 2015 or 2017, making sure to select the
options for installing the C++ compiler.
which will provide instructions for how to install rust on your platform.
Besides rustup there are
`other installation <https://forge.rust-lang.org/infra/other-installation-methods.html>`__ available too.
mtreinish marked this conversation as resolved.
Show resolved Hide resolved


Once the compilers are installed, you are ready to install Qiskit Terra.
Once the Rust compiler is installed, you are ready to install Qiskit Terra.

1. Clone the Terra repository.

Expand All @@ -796,19 +768,13 @@ Once the compilers are installed, you are ready to install Qiskit Terra.

cd qiskit-terra

3. Install the Python requirements libraries from your ``qiskit-terra`` directory.

.. code:: sh

pip install cython

4. If you want to run tests or linting checks, install the developer requirements.
3. If you want to run tests or linting checks, install the developer requirements.

.. code:: sh

pip install -r requirements-dev.txt

5. Install ``qiskit-terra``.
4. Install ``qiskit-terra``.

.. code:: sh

Expand All @@ -821,31 +787,24 @@ project don't require a reinstall to be applied, you can do this with:

pip install -e .

You can then run the code examples after installing Terra. You can
run the example with the following command.
Installing in editable mode will build the compiled extensions in debug mode
mtreinish marked this conversation as resolved.
Show resolved Hide resolved
without optimizations. This will effect the runtime performance of the compiled
mtreinish marked this conversation as resolved.
Show resolved Hide resolved
code. If you'd like to use editable mode and build the compiled code in release
with optimizations enabled you can run:

.. code:: sh

python examples/python/using_qiskit_terra_level_0.py
python setup.py build_rust --release --inplace

after your run pip and that will rebuild the binary in release mode.
mtreinish marked this conversation as resolved.
Show resolved Hide resolved

.. note::
You can then run the code examples after installing Terra. You can
run the example with the following command.
mtreinish marked this conversation as resolved.
Show resolved Hide resolved

If you do not intend to install any other components, qiskit-terra will
emit a ``RuntimeWarning`` warning that both qiskit-aer and
qiskit-ibmq-provider are not installed. This is done because
users commonly intend to use the additional elements,
but do not realize they are not installed, or that the installation
of either Aer or the IBM Quantum Provider failed for some reason. If you wish
to suppress these warnings, add::
.. code:: sh

import warnings
warnings.filterwarnings('ignore', category=RuntimeWarning,
module='qiskit')
python examples/python/using_qiskit_terra_level_0.py

before any ``qiskit`` imports in your code. This will suppress the
warning about the missing qiskit-aer and qiskit-ibmq-provider, but
will continue to display any other warnings from qiskit or other packages.

.. _install-qiskit-aer:

Expand All @@ -862,7 +821,7 @@ Installing Aer from Source

.. code:: sh

pip install cmake scikit-build cython
pip install cmake scikit-build

After this, the steps to install Aer depend on which operating system you are
using. Since Aer is a compiled C++ program with a Python interface, there are
Expand Down Expand Up @@ -906,10 +865,6 @@ universally depending on operating system.

.. tabbed:: macOS

.. note::
**Mac M1 Users:** There are ongoing issues with building Aer for AArch64 macOS.
See `#1286 <https://github.com/Qiskit/qiskit-aer/issues/1286>`__ for discussion and
workarounds before continuing.

3. Install dependencies.

Expand Down