About `vcpkg ports`_
====================

`vcpkg ports`_ define packages/libraries that can be used with
vcpkg_.

They serve both vcpkg_ modes:

- `vcpkg manifest mode`_: this repository can then be used as a
  *(Git)* `vcpkg registry`_. This is the recommended way of consuming
  custom ports from external registries. See the in-depth guide
  available at TODO.

- `vcpkg classic mode`_: via the ``--overlay-ports=./ports`` flag
  from the command-line. See the guide available at TODO.

vcpkg_ utilizes CMake_ to configure, build and link C++ code
in either a local isolated project-specific environment or in a
more global way across the whole system.

vcpkg_ downloads source code (or binaries if available) in order
to compile on the host platform using the available compilation
toolchain to produce libraries that can later be consumed by users.
This ensures reproducible builds across multiple platforms and
allows for controlled per-project development environments.


Project-Rat_ C++ libraries depends on multiple libraries listed
in Rat-Docs_. Most of these dependencies are provided in the
default vcpkg_ registry as ports, such as:

- Boost
- SuiteSparse
- SUNDIALS
- JsonCpp
- TCLAP

but some might require some tweaking in order to work properly.
This can be related to specific compilation (e.g. OpenBLAS and
single threading) or the lack of recent versions in the vcpkg_
default registry (e.g. Armadillo version ``15.2.x``).

.. note::

    The base installation sequence for compiling Rat on Windows in
    Rat-Docs_ seems to use the vcpkg_ default OpenBLAS port, but I
    did not have such success when trying it on my part, so
    Rat-vcpkg_ ships its own port.

Rat-vcpkg_ solves this by providing its own overrides for such
ports, as well as Rat-specific ports to compile Rat C++ libraries
using all previously mentionned ports.

Ports definitions can be found under the `rat-vcpkg/ports`_,
directory, each following the structure of typical `vcpkg ports`_.

Rat-vcpkg_ ports
----------------

When building Rat-vcpkg_ ports in either modes vcpkg_ solves the
dependencies listed in the ports definitions and start compiling
these first. This is why installing ``rat-models`` starts the whole
dependency chain and installs everything needed.

It might however be easiest to install each library step
by step for debugging purposes following the order below:

1. ``openblas`` - *modified base OpenBLAS for single-threading*
2. ``armadillo``
3. ``rat-common``
4. ``distmesh-cpp``
5. ``materials-cpp``
6. ``rat-math``
7. ``rat-mlfmm``
8. ``rat-nl`` - *optional*
9. ``rat-models`` - *longest to build*

.. note::

    ``rat-nl`` is only required for the non-linear solver used in
    ``rat-models`` thus it is defined as a feature. It is enabled by
    default.

    If not required: ``rat-models[-nl]:x64-windows-release``.

.. Links
.. _CMake: https://cmake.org
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _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