Using SMS++ with vcpkg

If you want to consume SMS++ as a dependency in another project, the easiest way is through the SMS++ vcpkg registry. It packages SMS++ (and its otherwise-unavailable dependency StOpt) as vcpkg ports, so any project can pull smspp like any other library, with vcpkg taking care of building it and all of its transitive dependencies.

This guide explains how to set up a project that depends on SMS++ via the registry. If you instead want to build and install SMS++ itself from source, see the Installation guide; for a first program against an already-installed SMS++, see Getting started.

Note: Conan is no longer supported. The vcpkg registry described here is now the recommended way to consume SMS++ as a dependency.

[[TOC]]

What the registry provides

The registry lives at https://gitlab.com/smspp/vcpkg-registry.git. It is a vcpkg git registry that exposes two ports:

Port	Version	Upstream
smspp	0.5.1	https://gitlab.com/smspp/smspp-project
stopt	6.3	https://gitlab.com/stochastic-control/StOpt

stopt (StOpt) is a dependency of smspp that is not available in the default vcpkg registry, so it is hosted here too. This means a project depending on smspp routes both packages to this single registry and needs no other custom registry for SMS++.

The registry has the standard vcpkg layout:

ports/
  smspp/
    portfile.cmake      # clones smspp-project 0.5.1 (with submodules) and builds it
    vcpkg.json          # port manifest + dependencies
  stopt/
    portfile.cmake      # fetches StOpt v6.3 and builds it
    vcpkg.json          # port manifest + dependencies
versions/
  baseline.json         # default versions served by the registry
  s-/
    smspp.json          # version -> git-tree map
    stopt.json          # version -> git-tree map

The complete dependency set that vcpkg pulls in for smspp is declared in ports/smspp/vcpkg.json: Boost (including boost-mpi), bzip2, the COIN-OR libraries (coin-or-clp, coin-or-osi, coinutils), eigen3, getopt, highs, liblemon, msmpi (on Windows), netcdf-cxx4, pthreads, stopt and zlib. You do not need to list any of these yourself.

Note: smspp-project is an umbrella of git submodules. The release source archive does not include submodule contents, so the smspp port clones the repository recursively at the pinned release tag instead of using a plain source archive (see the comment in ports/smspp/portfile.cmake).

Prerequisites

1. A vcpkg checkout. Clone vcpkg and bootstrap it:

   git clone https://github.com/microsoft/vcpkg.git
   ./vcpkg/bootstrap-vcpkg.sh        # Linux/macOS
   # .\vcpkg\bootstrap-vcpkg.bat     # Windows

   Note the path to your vcpkg checkout; you will pass its toolchain file to CMake. (On Windows, the SMS++ install scripts use C:\vcpkg.)

2. Manifest mode. This guide uses vcpkg's manifest mode, in which your project ships a vcpkg.json and vcpkg installs the listed dependencies automatically at CMake configure time. You do not run vcpkg install smspp by hand; the dependencies are resolved from the manifest.

3. A C++ toolchain and CMake (CMake >= 3.21, the minimum required by the SMS++ core). SMS++ is a C++17 framework, so a reasonably recent compiler is needed.

Step 1 — Create the project vcpkg.json

In the root of your project, create a vcpkg.json that:

• lists smspp in dependencies, and
• routes both smspp and stopt to the SMS++ registry under configuration.registries.

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": [
    "smspp"
  ],
  "builtin-baseline": "f8be6942c0c5abd48bb325726d57af9ac39e251d",
  "configuration": {
    "registries": [
      {
        "kind": "git",
        "repository": "https://gitlab.com/smspp/vcpkg-registry.git",
        "baseline": "<commit-SHA-of-the-registry>",
        "packages": [
          "smspp",
          "stopt"
        ]
      }
    ]
  }
}

Key points:

• dependencies — you only need to list smspp. Its transitive dependencies (including stopt) are declared by the port itself.
• configuration.registries — the git registry entry tells vcpkg that the named packages must be resolved from the SMS++ registry instead of the default vcpkg registry. stopt must appear in this packages list alongside smspp, because it is not in the default registry; if you omit it, vcpkg will fail to find stopt when resolving smspp's dependencies.
• baseline (inside the registry entry) — the full commit SHA of the SMS++ registry repository to pin to (see Step 2).
• builtin-baseline — the commit SHA of your vcpkg checkout used to pin all packages that come from the default vcpkg registry (Boost, Eigen, etc.). See Updating baselines.

Note: The two baseline fields are different things. The baseline inside the configuration.registries entry pins the SMS++ registry repository; the top-level builtin-baseline pins the default vcpkg registry (your local vcpkg checkout).

Step 2 — Pick the registry baseline

vcpkg requires a baseline for a git registry: it must be the full commit SHA of the SMS++ registry repository (normally the latest commit on its default branch). Get it with:

git ls-remote https://gitlab.com/smspp/vcpkg-registry.git HEAD

Copy the SHA into the baseline field of the registry entry. vcpkg then resolves the requested versions through the registry's versions/baseline.json and versions/s-/*.json maps and builds each port from ports/<port>/.

Note: A short SHA or a branch name is not accepted by vcpkg for a git registry baseline — use the full 40-character commit SHA.

Step 3 — Write a minimal CMakeLists.txt

SMS++ exports its core library as the imported target SMS++::SMSpp, found via find_package(SMSpp). Link against it exactly as you would for a system-installed SMS++:

cmake_minimum_required(VERSION 3.21)
project(my-project CXX)

# Provided by the smspp vcpkg port
find_package(SMSpp CONFIG REQUIRED)

add_executable(my-app main.cpp)
target_link_libraries(my-app PRIVATE SMS++::SMSpp)

A minimal main.cpp to verify the link works:

#include <iostream>

#include <SMS++/AbstractBlock.h>

using namespace SMSpp_di_unipi_it;

int main()
{
 AbstractBlock b;
 std::cout << b;
 return 0;
}

Note: The exported target name SMS++::SMSpp and the find_package(SMSpp) call are the same ones used in Getting started; nothing about how you reference SMS++ in CMake changes when it comes from vcpkg. Other SMS++ modules (Blocks/Solvers) are exported under the same SMS++:: namespace by their respective CMake configs.

Step 4 — Configure with the vcpkg toolchain

Point CMake at vcpkg's toolchain file. With it on the command line and a vcpkg.json present, vcpkg builds and installs the dependencies (the first configure builds SMS++ and all of its dependencies, which can take a while) before configuring your project:

cmake -S . -B build \
      -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake \
      -DCMAKE_BUILD_TYPE=Release

cmake --build build

On Windows the toolchain path is typically C:/vcpkg/scripts/buildsystems/vcpkg.cmake.

Note: The first configure compiles SMS++ and its full dependency tree from source; this can take a long time and a fair amount of disk space. Subsequent configures reuse the vcpkg binary cache.

Updating baselines

There are two independent baselines to keep current:

• The SMS++ registry baseline (the baseline inside the configuration.registries entry). Re-run the git ls-remote from Step 2 and update the SHA whenever you want to pick up a new SMS++/StOpt port version published by the registry.

• The vcpkg builtin baseline (builtin-baseline). This pins the versions of the packages that come from the default vcpkg registry. After a git pull in your vcpkg checkout, set it to the new revision so your manifest resolves against the updated package versions:

  git -C /path/to/vcpkg rev-parse HEAD

  On Windows, the SMS++ install script INSTALL.ps1 provides an -updatevcpkg flag that rewrites the "builtin-baseline" field in the umbrella's own vcpkg.json to the current git rev-parse HEAD of C:\vcpkg. That flag operates on the SMS++ umbrella's manifest, not on your consumer project; for your own project, update builtin-baseline by hand as shown above. See the Installation guide for details on -updatevcpkg.

Reference: the umbrella's own manifest

For comparison, the SMS++ umbrella consumes its own dependencies through vcpkg with the manifest at the repository root (vcpkg.json). Note that the umbrella's manifest lists every dependency explicitly (Boost, COIN-OR, HiGHS, LEMON, netCDF, stopt, …) because it builds SMS++ rather than consuming the smspp port; when you consume the smspp port instead, listing smspp alone is enough. The umbrella routes only stopt to a registry (a StOpt-specific one), whereas a consumer of the smspp port routes both smspp and stopt to the SMS++ registry described above.

See also

• Installation guide — building and installing SMS++ from source.
• Getting started — your first program with SMS++.
• SMS++ vcpkg registry — the registry repository and its README.