Manifest mode
=============

`vcpkg manifest mode`_ is the recommended
way of consuming packages with vcpkg_.

It allows reproducible per-project build
environments using JSON files.

`vcpkg manifest mode`_ also enables the use of `vcpkg registries`_,
which are groups of custom `vcpkg ports`_ with finer versioning.

Project structure
-----------------

.. code-block:: text

    myproject/
    ├── include/                    ← Example header files
    ├── src/                        ← Example source files
    ├── ...
    ├── CMakeLists.txt              ← Example CMakeLists
    ├── CMakePresets.json           ← Example CMake presets file
    ├── README.md                   ← Example README
    ├── vcpkg-configuration.json    ← vcpkg registry configuration
    ├── vcpkg.json                  ← vcpkg manifest configuration

The above structure presents an example of a project using `vcpkg
manifest mode`_. At the root are the two following JSON files.

- ``vcpkg-configuration.json``: describing the base curated registry
  to use, as well as custom registries, such as the Rat-vcpkg_
  repository.

- ``vcpkg.json``: describing the project at hand and the packages
  to use.

- ``CMakePresets.json``: optional file describing the arguments to
  pass to CMake_ configuration for lighter terminal commands.

An example of the files can be found under the
`rat-vcpkg/examples/manifest-mode`_ subdirectory
within the Rat-vcpkg_ repository on GitLab.

Manifest file
-------------

``vcpkg.json`` simply defines project metadata and following this
structure:

.. code-block:: json
    :caption: vcpkg manifest file

    {
        "name": "project-name",
        "version": "1.0.0",
        "dependencies": [
            "my-dependency-1",
            "my-dependency-2"
        ]
    }

Configuration file
------------------

``vcpkg-configuration.json`` defines registries to use along with
their baselines defined as Git commit hashes and the ports to use:

.. code-block:: json
    :caption: vcpkg configuration file

    {
        "default-registry": {
            "kind": "git",
            "baseline": "<commit hash of vcpkg to use>",
            "repository": "https://github.com/microsoft/vcpkg"
        },
        "registries": [
            {
                "kind": "git",
                "repository": "https://path/to/git/registry",
                "baseline": "<commit hash of registry to use>",
                "packages": [
                    "my-registry-dependency-1",
                    "my-registry-dependency-2"
                ]
            }
        ]
    }

This configuration defines a version for the vcpkg_ default registry
to use as well as an additional Git registry entry to access more
dependencies for the project.

The configuration file can also be used to point to local registry
to override specific ports like in `rat-vcpkg/examples/manifest-mode`_:

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

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

This is usefull for quick iterations and testing.

.. note::

    - To obtain a correct ``"baseline"`` value to use, one can leave a
      blank string. vcpkg_ will print out and error containing the
      most recent commit hash. Just copy it as the value for the
      registry baseline. Alternatively one can paste the output of
      the ``git rev-parse HEAD`` command in the repository of interest.
      Baselines should point to valid commit hash.

    - The path to the external registry can also be a file path to a
      local git repository:

    .. code-block:: json

        {
            "kind": "git",
            "repository": "file:///C:/path/to/project-rat-extras/rat-vcpkg",
        }

.. warning::

    vcpkg_ seems pretty dumb when it comes to commit SHA
    (which is funny considering it is the base of registries...)
    and will not really use the provided commit SHA completely.

    For instance, commits to a ``dev`` branch would be recognize,
    but versions and baseline will still be resolved using the
    ``main`` branch... One might need to have a more *impactful*
    commit such as a tag or push a new branch in order to have vcpkg
    property recognize the given commit SHA.

.. seealso::

    For more information about registries: `vcpkg registries`_.

    For an example of manifest and configuration files using
    Rat-vcpkg_: :doc:`examples`

CMake_ presets file
-------------------

``CMakePresets.json`` defines CMake_ presets to use during project
configuration, allowing for leaner and more concise terminal command

.. code-block:: json
    :caption: CMake_ preset file

    {
      "version": 3,
      "configurePresets": [
        {
          "name": "main",
          "cacheVariables": {
            "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
            "CMAKE_BUILD_TYPE": "Release",
            "VCPKG_TARGET_TRIPLET": "x64-windows-release",
            "VCPKG_HOST_TRIPLET": "x64-windows-release"
          }
        }
      ]
    }

Providing the ``VCPKG_ROOT`` environment variable, this
allow to configure project with the simple following command:

.. code-block:: powershell

    cmake -B build -S . --preset main

Consume packages
----------------

vcpkg_ will recognize the two JSON files described above whenever
running an install, configure or build command, either directly via
vcpkg_, or via CMake_.

vcpkg_ first needs to build and install the project dependencies
defined in the manifest and configuration files and will do so under
a ``vcpkg_installed`` directory, either next to the JSON files or
under a build directory if invoked via CMake_.

.. note::

    Depencies might take some time to build depending on the
    hardware.

    The heaviest one for Rat seems to be VTK, which is even
    longer to build in ``Debug``.

Local manifest installation
***************************

- Run the following command to first build and install vcpkg_
  dependencies for the local project following the manifest:

.. code-block:: powershell

    vcpkg install --triplet x64-windows-release --host-triplet x64-windows-release

It will trigger vcpkg_ to build dependencies inside a
``vcpkg_installed`` directory using the ``x64-windows-release``
triplet for faster and leaner builds. See `vcpkg triplets`_.

This will serve as the dependency installation directory for the
project and vcpkg will know to use it when instructed to configure
projects with CMake_ pointing to its toolchain.

CMake_ configuration installation
*********************************

- Ensure the ``VCPKG_ROOT`` environment variable is defined and
  points to the local vcpkg repository installation.

- 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 the ``CMakePresets.json`` file above:

.. code-block:: powershell

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

This will first trigger vcpkg_ to build dependencies just like the
above local manifest installation before running the CMake_
configuration for the project.

- Build the project:

.. code-block:: powershell

    cmake --build build

.. warning::

    VTK ports recently changed to introduce a ``vtk-compile-tools``
    port which is host specific and might break CMake_ configuration.

    To fix this, ensure the ``vtk-compile-tools`` package is
    installed in **global vcpkg using classic mode** by running the
    following command from outside the current manifest project:

    ``vcpkg install vtk-compile-tools``

.. Links
.. _CMake: https://cmake.org
.. _rat-vcpkg/examples/manifest-mode: https://gitlab.com/project-rat-extras/rat-vcpkg/-/tree/main/examples/manifest-mode?ref_type=heads
.. _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
.. _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 registries: https://learn.microsoft.com/en-us/vcpkg/concepts/registries
.. _vcpkg triplets: https://learn.microsoft.com/en-gb/vcpkg/concepts/triplets