Setup
=====

Rat-vcpkg_ and vcpkg_ have some prerequisites in order to fully
enable their features.

Install a compilation toolchain
-------------------------------

vcpkg_ requires a **compilation toolchain** to be up and ready to
compile C/C++.

The compilation toolchain consists of a **compiler**, a **linker**
and several other related tools that are needed for the compilation
of C/C++ libraries and programs. This part differs depending on the
targeted platform (e.g. Windows VS the world).

.. table:: Compilation toolchain table
    :width: 70 %
    :widths: auto

    +--------------------+-----------------------------+------------------+
    | Platforms          | Compilers                   | Linkers          |
    +====================+=============================+==================+
    | Windows            | ``cl.exe``                  | ``ld.exe``       |
    +--------------------+-----------------------------+------------------+
    | UNIX (Linux/macOS) | ``gcc``, ``g++``, ``clang`` | ``ldd``, ``lld`` |
    +--------------------+-----------------------------+------------------+

------

A - Windows | `MSVC Build Tools`_
*********************************

Installation come in the form of a classical wizard installer for the
MSVC toolchain.

.. caution::
    The compilation has been tested on **MSVC v2019-2022**.
    The **v2025** is **NOT** compatible with the compilation of
    some packages such as the **SuiteSparse** libraries for the
    time being.

New shells should be available from the **Windows Start Menu** once
the installation is complete. Hit the `⊞ Win` key and look for
something like ``Developer PowerShell for VS 20XX`` (depending on
the version).

This is a PowerShell terminal that starts with a special ``.ps1``
script to update environment variables for the MSVC toolchain to
work properly. **It should be used for the rest of this
documentation** in order to have access to all the MSVC toolchain
needed to compile applications on Windows.

.. note::

    - There exists an equivalent version using ``cmd`` instead of
      PowerShell if preferred. Just make sure to translate commands
      accordingly.
    - For the rest of this documentation, this terminal will be
      refered as the **MSVC shell**.
    - Use the MSVC shell to compile libraries, run programs and use
      vcpkg.
    - If using the **Windows Terminal**, one can add a profile with
      the following start script to have a smooth experience:

    .. code-block:: powershell

        powershell.exe -noexit -command "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1' -arch amd64 -host amd64"

B - UNIX (Linux/macOS) | GNU toolchain
**************************************

The UNIX world being very wide and various some steps might need some
adaptation from the user.

The broad idea is to get items such as a compiler, linker, configure
tools, and some additional headers and libraries if needed depending
on the environment.

Under **WSL2 Ubuntu24** this looks like something like this:

.. code-block:: bash

    # Compiler, linker, configure tools
    sudo apt-get install build-essential

    # OpenGL related items, for WSL
    sudo apt-get install mesa-utils libglu1-mesa-dev freeglut3-dev mesa-common-dev

Do not hesitate to install more things if needed.

------

To complete the toolchain, install the following:

- CMake_ for the build configuration,
- Ninja_ for the build system.

.. note::

    vcpkg_ will install its own CMake_ and Ninja_ since it likes to
    handle its own items, but it might still be interesting to
    install them just in case. We're here to compile some C/C++
    code anyway.

Install Git_
------------

Use the above installer or any package manager.

All the default options should be good to go if you do not know much
about ``git``. Ensure it works properly by opening a new shell and
running ``git --version``.

``git`` will be used for cloning (*downloading*) vcpkg_ and
Project-Rat_ dependencies to compile them locally.

Install vcpkg_
--------------

vcpkg_ is a bit different: it needs to be **cloned**, and then
**bootstrapped** it, which is quite nice.

Clone the vcpkg_ repository in a convenient place for ease of access.

- Open up a shell and navigate to a handy place.

- Clone the vcpkg repository locally:

.. code-block:: powershell

    git clone https://github.com/microsoft/vcpkg.git

- Navigate into it & bootstrap it:

.. code-block:: powershell

    cd vcpkg
    .\bootstrap-vcpkg.bat -disableMetrics

This will generate a ``vcpkg`` executable inside the repository and
can be used by the system and user to install and handle packages.

.. seealso::
    
    More information about vcpkg_ can be found here:
    https://learn.microsoft.com/fr-fr/vcpkg/get_started/get-started?pivots=shell-cmd

- Add the local vcpkg repository to the ``PATH`` environment variable.

.. code-block:: powershell

    $env:Path="C:\path\to\vcpkg;$env:Path"

Verify the ``vcpkg`` command is available from the shell:

.. code-block:: powershell

    vcpkg --version

This should print the version as a Git commit hash.

Install `CUDA Toolkit`_ & `NVIDIA drivers`_
-------------------------------------------

.. note::

    This part is optional and should be done to enable
    NVIDIA CUDA GPU acceleration for Rat calculations.

    Computers without graphics cards will not be able to benefit
    from this acceleration.

- Install the `CUDA Toolkit`_.
  Setups should be similar to these for most users:

.. table:: NVIDIA CUDA Toolkit table
    :width: 70 %
    :widths: auto

    +-------------+-----------------------------+
    | Plaforms    | Installers                  |
    +=============+=============================+
    | Windows     | `CUDA Toolkit Windows`_     |
    +-------------+-----------------------------+
    | WSL2 Ubuntu | `CUDA Toolkit WSL2 Ubuntu`_ |
    +-------------+-----------------------------+

- Install the latest `NVIDIA drivers`_. This will depend on the
  graphics card at hand.

.. danger::

    **If using WSL**, do **NOT** install NVIDIA drivers in the Linux
    distribution. **Install them on Windows only**.

Find your graphics card model via the **NVIDIA Control Panel** in the
Start Menu, e.g. **NVIDIA RTX 1000 Ada Generation**, and search for
it in the search bar of the above web page. Download and install the
corresponding driver.

- Update ``PATH`` environment variable to reflect CUDA installation
  (change the `13.0` to the version on the system if needed).

.. code-block:: powershell

    $env:Path="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin;$env:Path"      # binaries
    $env:Path="C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin\x64;$env:Path"  # libraries

.. important::

    Paths to CUDA installation must remain visible
    when compiling anything requiring the CUDA Toolkit.

    For a more long lasting setup consider adding these paths
    to the ``PATH`` environment variable either via a PowerShell
    profile or via Windows environment variables menu.

Install an IDE
--------------

Any IDE (Integrated Development Environment) should do the trick.
Here are some *random* propositions:

- `VS Code`_ / VSCodium_
- `Notepad++`_
- Neovim_
- Emacs_

One might want to write some code using Rat C++ libraries after all.

.. Links
.. _CMake: https://cmake.org
.. _CUDA Toolkit: https://developer.nvidia.com/cuda-downloads
.. _CUDA Toolkit Windows: https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64&target_version=10&target_type=exe_local
.. _CUDA Toolkit WSL2 Ubuntu: https://developer.nvidia.com/cuda-downloads?target_os=Linux&target_arch=x86_64&Distribution=WSL-Ubuntu&target_version=2.0&target_type=deb_network
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _Emacs: https://www.gnu.org/software/emacs/
.. _Git: https://git-scm.com/
.. _MSVC Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
.. _Neovim: https://neovim.io/
.. _Ninja: https://ninja-build.org/
.. _Notepad++: https://notepad-plus-plus.org/
.. _NVIDIA drivers: https://www.nvidia.com/en-us/drivers/
.. _Project-Rat: https://gitlab.com/project-rat
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _rat-vcpkg/ports: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/ports?ref_type=heads
.. _vcpkg: https://vcpkg.io/en/
.. _vcpkg classic mode: https://learn.microsoft.com/en-us/vcpkg/concepts/ports
.. _vcpkg manifest mode: https://learn.microsoft.com/en-us/vcpkg/consume/manifest-mode?tabs=msbuild%2Cbuild-MSBuild
.. _vcpkg ports: https://learn.microsoft.com/en-us/vcpkg/concepts/ports
.. _vcpkg registry: https://learn.microsoft.com/en-us/vcpkg/concepts/registries
.. _VS Code: https://code.visualstudio.com/
.. _VSCodium: https://vscodium.com/