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:

  1. Get a project to build

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

  1. 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.

  1. Configure the project

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:

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

  1. Build the project

cmake --build build

  1. Run the project

.\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:

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"
    ]
}
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:

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 Manifest mode.

cd .\examples\manifest-mode

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

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

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:

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:

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 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:

cmake --build build

  • Run the project:

.\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.