Examples
========

Some examples are available at `rat-vcpkg/examples`_.

These are just copied from the base
Project-Rat_ repositories with some tweaks:

- Fixed include statements to use global
  header paths rather than local.

- Added simple corresponding ``CMakeLists.txt``
  to easily configure and build example.

These examples are intended to be used as bases
to get familiar with vcpkg_ and CMake_.

Workflow
--------

Building projects utlizing Rat C++ libraries built
with Rat-vcpkg_ should follow this general workflow:

1. **Install Rat C++ libraries**

Follow the previous sections to install
Rat C++ libraries using either modes:

- :doc:`manifest_mode`
- :doc:`classic_mode`

2. **Get a project to build**

It can be either a simple single source files like Project-Rat_
repositories examples or more complex C++ projects.

3. **Get a configure script**
   (and manifest files if using manifest mode)

Rat is mostly intended to use CMake_ as its configuration tool.
The corresponding configuration script is a ``CMakeLists.txt`` file
just like in the examples directory.

If using `vcpkg manifest mode`_ ensure both ``vcpkg.json`` and
``vcpkg-configuration.json`` files sit a the root of the project,
with an optional ``CMakePresets.json`` file for CMake_.

4. **Configure the project**

.. code-block:: powershell

    cmake -B build -S . -G "Ninja" `
        -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
        -DCMAKE_BUILD_TYPE=Release `
        -DVCPKG_TARGET_TRIPLET=x64-windows-release `
        -DVCPKG_HOST_TRIPLET=x64-windows-release

or using a ``CMakePresets.json`` file:

.. code-block:: powershell

    cmake -B build -S . -G "Ninja" --preset main

5. **Build the project**

.. code-block:: powershell

    cmake --build build

6. **Run the project**

.. code-block:: powershell

    .\build\Release\bin\<name>.exe

Paths and names may differ depending on the project.

Manifest mode example
---------------------

`rat-vcpkg/examples/manifest-mode`_ defines manifest and
configuration files examples to build projects using
`vcpkg manifest mode`_. Its most simple form is as such:

.. code-block:: json
    :caption: ``vcpkg.json`` file using overlay

    {
        "name": "manifest-mode",
        "version": "0.2.1",
        "dependencies": [
            "armadillo",
            "distmesh-cpp",
            "materials-cpp",
            "openblas",
            "rat-common",
            "rat-math",
            "rat-mlfmm",
            "rat-models",
            "rat-nl"
        ]
    }

.. code-block:: json
    :caption: ``vcpkg-configuration.json`` file using overlay

    {
        "overlay-ports": [
            "../../ports"
        ]
    }

This requires to have the `rat-vcpkg`_ repository
cloned locally on the system in order to access it.
This file can however be changed following previous sections:

.. code-block:: json
    :caption: ``vcpkg-configuration.json`` file using commit SHAs

    {
        "default-registry": {
            "kind": "git",
            "baseline": "e5a4f54c0d562059e9ccc6f7e7150667da58fe41",
            "repository": "https://github.com/microsoft/vcpkg"
        },
        "registries": [
            {
                "kind": "git",
                "repository": "https://gitlab.com/project-rat-extras/rat-vcpkg",
                "baseline": "4c91781307fbf741dbae8ad4d4ce2fc405b7949d",
                "packages": [
                    "armadillo",
                    "distmesh-cpp",
                    "materials-cpp",
                    "openblas",
                    "rat-common",
                    "rat-math",
                    "rat-mlfmm",
                    "rat-models",
                    "rat-nl"
                ]
            }
        ]
    }

in order to pull in arbitrary commit SHAs from remote repositories.

One can copy ``vcpkg.json`` and ``vcpkg-configuration.json`` files
next to their ``CMakeLists.txt`` file to use build their
project using `vcpkg manifest mode`_.

Update the baseline
*******************

`vcpkg manifest mode`_ requires a precise ``"baseline"`` value in
order to pinpoint the version of the Rat-vcpkg_ registry to use.

One can either:

- Run the CMake_ configuration with an empty string as value.
  vcpkg will error out and print the most recent baseline value
  of the target registry. Simply copy and paste it into the
  ``vcpkg-configuration.json`` file for the Rat-vcpkg_ registry
  baseline.

- Pick a specific Git commit hash of the Rat-vcpkg_ repository.

If desired one can also update the
baseline for the vcpkg default registry.

The project can then be configure and built like described above.

Rat-Template
------------

A good exercise is to compile the Rat-Template_ repository from
Project-Rat_ group. It defines a simple program to simulate a
solenoid and calculate field values over its mesh.

This can be done using :doc:`manifest_mode`.

- From the root of the repository, navigate to the
  `rat-vcpkg/examples/manifest-mode`_ subdirectory:

.. code-block:: powershell

    cd .\examples\manifest-mode

- Clone the Rat-Template_ repository and navigate into it:

.. code-block:: powershell

    git clone https://gitlab.com/project-rat/rat-template.git
    cd rat-template

- Copy the manifest and configuration
  files into the project directory:

.. code-block:: powershell

    cp ..\vcpkg.json .
    cp ..\vcpkg-configuration.json .
    cp ..\CMakePresets.json . #optional

- Update the baselines to valid commit SHAs of Rat-vcpkg_ and vcpkg_
  in ``vcpkg-configuration.json`` file following error message.
  This can be done by running the ``git rev-parse HEAD`` command
  from within each repository of interest or by searching online.

  .. note::

    If using overlay ports, ensure to update the path to the ``ports``
    directory (e.g. add another ``../`` since we went down a directory):
    ``"../../../ports"``

- Configure the CMake_ project using the vcpkg toolchain file:

.. code-block:: powershell

    cmake -B build -S . -G "Ninja" `
        -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
        -DCMAKE_BUILD_TYPE=Release `
        -DVCPKG_TARGET_TRIPLET=x64-windows-release `
        -DVCPKG_HOST_TRIPLET=x64-windows-release

or using a ``CMakePresets.json`` file:

.. code-block:: powershell

    cmake -B build -S . -G "Ninja" --preset main

If running vcpkg_ installation for the first time this will trigger
to build all required libraries and will thus take some time. If
libaries have already been built by vcpkg_ caching will kick in and
reuse these libraries. See :doc:`caching` for more information.

.. note::

    One might need to modify the ``CMakeLists.txt`` configuration
    file in order to match the versions of the Rat libraries
    installed by vcpkg ports (e.g. ``v2.021.1``).

- Build the project:

.. code-block:: powershell

    cmake --build build

- Run the project:

.. code-block:: powershell

    .\build\bin\solenoid.exe --od .\mydata

pyRat_
------

pyRat_ offers Python bindings for Rat C++ libraries. It can be built
using ports from Rat-vcpkg_ in both modes to expose Rat classes and
methods to Python users via a ``pyrat`` module.

.. Links
.. _CMake: https://cmake.org
.. _Project-Rat: https://gitlab.com/project-rat
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-Template: https://gitlab.com/project-rat/rat-template
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _rat-vcpkg/examples: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/examples?ref_type=heads
.. _rat-vcpkg/examples/manifest-mode: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/examples/manifest-mode?ref_type=heads
.. _rat-vcpkg/examples/rat: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/examples/rat?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
.. _vcpkg triplets: https://learn.microsoft.com/en-gb/vcpkg/concepts/triplets