About `vcpkg registries`_
=========================

`vcpkg registries`_ are collections of `vcpkg ports`_ usually
gathered into Git repositories in order to extend the base
vcpkg_ registry with custom ports for new packages and libraries.

This structure allows Rat-vcpkg_ to be used in `vcpkg
manifest mode`_ with fine-grain versioning if needed.

.. seealso::

    :doc:`about_vcpkg_ports`

.. code-block:: text

    myregistry/                 ← Registry repository (e.g Rat-vcpkg)
    ├── ports/                  ← Ports directory
    │   ├── port-1/             ← A port
    │   │   ├──portfile.cmake   ← Portfile
    │   │   ├──vcpkg.json       ← Port metadata
    │   │   ├──...              ← Other files for port
    │   ├── ...                 ← Other ports
    ├── versions/               ← Port versions directory
    │   ├── p-/                 ← Prefix
    │   │   ├──port-1.json      ← Port version file
    │   ├── baseline.json       ← Baseline versions file
    ├── ...

Maintain
--------

Registries can require meticulous versioning and maintainement
when it comes to updating ports or baselines (and this Rat-vcpkg_
is not perfect in that sense).

However some people are quite good at this, namely `luncliff's
vcpkg-registry repository`_. Following these guidelines to update
ports enables cleaner workflows.

Here are some useful guides:

- `create port`_
- `update port`_
- `update version baseline`_

It is recommended to have a look at their work.

.. Links
.. _CMake: https://cmake.org
.. _create port: https://luncliff.github.io/vcpkg-registry/guide-create-port
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _luncliff's vcpkg-registry repository: https://luncliff.github.io/vcpkg-registry/
.. _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
.. _update port: https://luncliff.github.io/vcpkg-registry/guide-update-port
.. _update version baseline: https://luncliff.github.io/vcpkg-registry/guide-update-version-baseline
.. _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 registries: https://learn.microsoft.com/en-us/vcpkg/concepts/registries
.. _vcpkg registry: https://learn.microsoft.com/en-us/vcpkg/concepts/registries