Add documentation on installing aer from source (Qiskit/qiskit-metapa…

…ckage#317)

* Add documentation on installing aer from source

Instead of just linking to Aer's contributing guide as was done
previously. This commit adds documention on how to build in install
Aer. The build system for Aer is much more complicated than any of the
other components, with a lot of specifics for different environments.
This intends to cover the widest base and link to where you can more
information (which is not the Aer repo) if you need to figure out
specific options for building Aer.

* Fix lint

* Cleanup some wording and formatting

* minor edits

Mac OSX -> macOS

"We" tense to "you" tense.

docs/contributing_to_qiskit.rst

@@ -152,7 +152,7 @@ Installing from source requires that you have a c++ compiler on your system that
 c++-11.  On most Linux platforms, the necessary GCC compiler is already installed.
 
 Install a compiler for MacOS
-""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you use Apple OSX, 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
@@ -169,7 +169,7 @@ Install XCode and clang by using the following command.
     xcode-select --install
 
 Install a compiler for Windows
-""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 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
@@ -226,7 +226,286 @@ Install Qiskit Terra
 
 After you've installed Terra, you can install Aer as an add-on to run additional simulators.
 
-* `Qiskit Aer <https://github.com/Qiskit/qiskit-aer/blob/master/CONTRIBUTING.md>`__
+Install Aer from Source
+-----------------------
+
+1. Clone the Aer repository.
+
+.. code:: sh
+
+    git clone https://github.com/Qiskit/qiskit-aer
+
+2. Install build requirements.
+
+.. code:: sh
+
+    pip install cmake scikit-build cython
+
+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
+non-python dependencies for building the Aer binary which can't be installed
+universally depending on operating system.
+
+Linux
+^^^^^
+
+3. Install compiler requirements.
+
+   Building Aer requires a C++ compiler and development headers
+
+   If you're using Ubuntu>=16.04 or an equivalent Debian Linux distribution
+   you can install this with:
+
+.. code:: sh
+
+    sudo apt install build-essential
+
+4. Install OpenBLAS development headers.
+
+If you're using Ubuntu>=16.04 or an equivalent Debian Linux distribution,
+you can install this with:
+
+.. code:: sh
+
+    sudo apt install libopenblas-dev
+
+
+5. Build and install qiskit-aer directly
+
+If you have pip <19.0.0 installed and your environment doesn't require a
+custom build options you can just run:
+
+.. code:: sh
+
+    cd qiskit-aer
+    pip install .
+
+This will both build the binaries and install Aer.
+
+Alternatively if you have a newer pip installed, or have some custom requirement
+you can build a python wheel manually.
+
+.. code:: sh
+
+    cd qiskit-aer
+    python ./setup.py bdist_wheel
+
+If you need to set a custom option during the wheel build you can refer to
+:ref:`aer_wheel_build_options`.
+
+After you build the python wheel it will be stored in the ``dist/`` dir in the
+Aer repository. The exact version will depend
+
+.. code:: sh
+
+    cd dist
+    pip install qiskit_aer-*.whl
+
+The exact filename of the output wheel file depends on the current version of
+Aer under development.
+
+macOS
+^^^^^
+
+3. Install dependencies.
+
+To use the `Clang`_ compiler on macOS, you need to install an extra library for
+supporting `OpenMP`_.  You can use `brew`_ to install this and other
+dependencies.
+
+.. _brew: https://brew.sh/
+.. _Clang: https://clang.llvm.org/
+.. _OpenMP: https://www.openmp.org/
+
+.. code:: sh
+
+    brew install libomp
+
+You then also have to install a BLAS implementation, `OpenBLAS`_ is the
+default choice.
+
+.. code:: sh
+
+    brew install openblas
+
+.. _OpenBlas: https://www.openblas.net/
+
+You also need to have ``Xcode Command Line Tools`` installed.
+
+.. code:: sh
+
+    xcode-select --install
+
+4. Build and install qiskit
+
+If you have pip <19.0.0 installed and your environment doesn't require a
+custom build options you can just run:
+
+.. code:: sh
+
+    cd qiskit-aer
+    pip install .
+
+This will both build the binaries and install aer.
+
+Alternatively if you have a newer pip installed, or need to set custom options
+for your environment you can build a python wheel manually.
+
+.. code:: sh
+
+    cd qiskit-aer
+    python ./setup.py bdist_wheel
+
+If you need to set a custom option during the wheel build you can refer to
+:ref:`aer_wheel_build_options`.
+
+After you build the python wheel it will be stored in the ``dist/`` dir in the
+Aer repository. The exact version will depend
+
+.. code:: sh
+
+    cd dist
+    pip install qiskit_aer-*.whl
+
+The exact filename of the output wheel file depends on the current version of
+Aer under development.
+
+Windows
+^^^^^^^
+
+On Windows you need to use `Anaconda3`_ or `Miniconda3`_ to install all the
+dependencies.
+
+.. _Anaconda3: https://www.anaconda.com/distribution/#windows
+.. _Miniconda3: https://docs.conda.io/en/latest/miniconda.html
+
+3. Install compiler requirements
+
+.. code:: sh
+
+    conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime
+
+4. Install binary and build dependencies
+
+.. code:: sh
+
+    conda install --update-deps -c conda-forge -y openblas cmake
+
+5. Install the package
+
+If you have pip <19.0.0 installed you can just run
+
+.. code:: sh
+
+    cd qiskit-aer
+    pip install .
+
+if you're using pip >=19.0.0 then you can manually build a wheel file and install
+that instead.
+
+.. code:: sh
+
+    cd qiskit-aer
+    python setup.py bdist_wheel
+
+If you need to set a custom option during the wheel build you can refer to
+:ref:`aer_wheel_build_options`.
+
+After you build the python wheel it will be stored in the ``dist/`` dir in the
+Aer repository. The exact version will depend
+
+.. code:: sh
+
+    cd dist
+    pip install qiskit_aer-*.whl
+
+The exact filename of the output wheel file depends on the current version of
+Aer under development.
+
+.. _aer_wheel_build_options:
+
+Custom options during wheel builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Aer build system uses `scikit-build`_ to run the compilation when building
+it with the python interface. It acts as an interface for `setuptools`_ to
+call `CMake`_ and compile the binaries for your local system.
+
+.. _scikit-build: https://scikit-build.readthedocs.io/en/latest/index.html
+.. _setuptools: https://setuptools.readthedocs.io/en/latest/
+.. _CMake: https://cmake.org/
+
+Due to the complexity of compiling the binaries you may need to pass options
+to a certain part of the build process. The way to pass variables is:
+
+.. code:: sh
+
+    python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]]
+
+where the elements within square brackets `[]` are optional, and
+``skbuild_opts``, ``cmake_opts``, ``build_tool_opts`` are to be replaced by
+flags of your choice. A list of *CMake* options is available here:
+https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options . For
+example, you could run something like:
+
+.. code:: sh
+
+    python setup.py bdist_wheel -- -- -j8
+
+This is passing the flag `-j8` to the underlying build system (which in this
+case is `Automake`_) telling it that we want to build in parallel using 8
+processes.
+
+.. _Automake: https://www.gnu.org/software/automake/
+
+For example, a common use case for these flags on linux is to specify a
+specific version of the C++ compiler to use (normally if the default is too
+old).
+
+.. code:: sh
+
+    python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7
+
+which will tell CMake to use the g++-7 command instead of the default g++ when
+compiling Aer
+
+Another common use case for this, depending on your environment, is that you may
+need to specify your platform name and turn off static linking.
+
+.. code:: sh
+
+    python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \
+    -- -DSTATIC_LINKING=False -- -j8
+
+Here ``--plat-name`` is a flag to setuptools, to specify the platform name to
+use in the package metadata, ``-DSTATIC_LINKING`` is a flag to CMake being used
+to disable static linking, and ``-j8`` is a flag to Automake being used to use
+8 processes for compilation.
+
+A list of common options depending on platform are:
+
++--------+------------+----------------------+---------------------------------------------+
+|Platform| Tool       | Option               | Use Case                                    |
++========+============+======================+=============================================+
+| All    | Automake   | -j                   | Followed by a number this set the number of |
+|        |            |                      | process to use for compilation              |
++--------+------------+----------------------+---------------------------------------------+
+| Linux  | CMake      | -DCMAKE_CXX_COMPILER | Used to specify a specific C++ compiler,    |
+|        |            |                      | this is often needed if you default g++ is  |
+|        |            |                      | too.                                        |
++--------+------------+----------------------+---------------------------------------------+
+| OSX    | setuptools | --plat-name          | Used to specify the platform name in the    |
+|        |            |                      | output Python package.                      |
++--------+------------+----------------------+---------------------------------------------+
+| OSX    | CMake      | -DSTATIC_LINKING     | Used to specify whether static linking      |
+|        |            |                      | should be used or not                       |
++--------+------------+----------------------+---------------------------------------------+
+
+.. note::
+    Some of these options are not platform specific, if a platform is listed
+    this is just outlining it's commonly used in that environment. Refer to the
+    tool documentation for more information.
+
 * `Qiskit Ignis <https://github.com/Qiskit/qiskit-ignis/blob/master/CONTRIBUTING.md>`_
 * `Qiskit Aqua <https://github.com/Qiskit/qiskit-aqua/blob/master/CONTRIBUTING.md>`__
 * `Qiskit Chemistry <https://github.com/Qiskit/qiskit-chemistry/blob/master/CONTRIBUTING.md>`__