Skip to content

Installing SMS++

Jump to bottom
Donato Meoli edited this page Mar 7, 2025 · 119 revisions

If you are new to SMS++ and you are looking for a zero-waste way to install all dependencies in the default locations, we suggest using the ad-hoc INSTALL files.

If you have not yet cloned the SMS++ repository, you can launch the script directly:

# Windows (from a PowerShell as administrator)
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& ([scriptblock]::Create((New-Object System.Net.WebClient).DownloadString('https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.ps1')))

or:

# Linux
# using curl
curl -s https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | sudo bash -s -- --install-root=<your-custom-path>
# using  wget
wget -qO- https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | sudo bash -s -- --install-root=<your-custom-path>

# macOS
# using curl
curl -s https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | bash -s -- --install-root=<your-custom-path>
# using  wget
wget -qO- https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | bash -s -- --install-root=<your-custom-path>

if not specified, the default installation root path is /opt for Linux (or $HOME if the current user is not sudoer), and /Library for macOS.

If you do not want to install some SMS++ dependency, you can run:

# Windows (from a PowerShell as administrator)
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& ([scriptblock]::Create((New-Object System.Net.WebClient).DownloadString('https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.ps1'))) -without<some-dependency>

or:

# Linux
# using curl
curl -s https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | sudo bash -s -- --install-root=<your-custom-path> --without-<some-dependency>
# using  wget
wget -qO- https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | sudo bash -s -- --install-root=<your-custom-path> --without-<some-dependency>

# macOS
# using curl
curl -s https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | bash -s -- --install-root=<your-custom-path> --without-<some-dependency>
# using  wget
wget -qO- https://gitlab.com/smspp/smspp-project/-/raw/develop/INSTALL.sh | bash -s -- --install-root=<your-custom-path> --without-<some-dependency>

according to the following options table:

Unix Windows Description
--without-cplex -withoutCplex skip CPLEX installation
--without-gurobi -withoutGurobi skip Gurobi installation
--without-scip -withoutScip skip SCIP installation
--without-highs -withoutHiGHS skip HiGHS installation
--without-stopt -withoutStOpt skip StOpt installation
--without-coinor -withoutCoinOr skip COIN-OR installation
--without-smspp -withoutSMSpp skip SMS++ installation

Otherwise, if you are already inside the cloned repository, you can run the script via:

# Windows (from a PowerShell as administrator)
.\INSTALL.ps1

or:

# Linux
sudo ./INSTALL.sh

# macOS
./INSTALL.sh

using the same flag options according to the OS, if needed.

If you need more detailed instructions about how to install the project's requirements, please refer to the following guide that contains detailed instructions to help you install the required tools and libraries needed to build SMS++.

[[TOC]]

Required tools

Building SMS++ requires the following tools:

  • A C++17-compliant C++ compiler. At the moment, SMS++ works with either GCC or Clang;
  • CMake, suggested for SMS++ but required for building some requirements;
  • Git and make.

In most cases, tools and requirements can be installed using a common package managers like apt for Debian-based distributions, vcpkg for Windows, or homebrew for macOS.

macOS

Building stuff on macOS requires Apple's Command Line Tools. You can obtain them by either installing XCode and launching it once or by running in the terminal:

xcode-select --install

CLT includes the Clang C/C++ compiler, Git, and make.

We suggest using homebrew for the other tools and requirements. Install it with:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Use it to install CMake:

brew install cmake

Debian/Ubuntu

The required tools can be installed using apt:

sudo apt install build-essential cmake git

build-essential includes GCC and make. If you prefer Clang, run:

sudo apt install clang
sudo update-alternatives --set cc /usr/bin/clang
sudo update-alternatives --set c++ /usr/bin/clang++

Other UNIX/Linux systems

We do not actively support other UNIX and Linux systems, but you can probably adapt the following instructions to your OS with little effort.

Windows

There are two different ways to build SMS++ under Windows.

The first way is using the WSL, so in this case please follow the Debian/Ubuntu part of this guide.

The second one is a native way, does not use any virtualization, and needs:

  • the MSVC toolchain, please check on/off the last version of the MS build tools for the command line and install it, notice that you will need admin rights.

  • the vcpkg package manager for Windows, better if installed under C:\.

The subsequent commands have to be executed in the directory where the vcpkg has been installed to install some libs already present in the UNIX-based systems:

vcpkg install zlib bzip2 pthreads getopt --triplet x64-windows

MSVC includes both GCC and Clang C/C++ compilers, and also a porting of the UNIX make tool. MSVC also includes CMake, to install it check to on C++ CMake for Windows under the Desktop Development with C++ tools list. Otherwise, manually install following the instructions here.

To install Git follow the instructions here.

Getting started

Before installing the required libraries you should assess which SMS++ modules you need: different modules have different requirements, and by excluding some modules you might avoid installing unnecessary software.

Depending on how many modules you need, you can proceed in two ways:

  • Use the SMS++ project (aka umbrella) and comment out the modules you don't need from the CMakeLists.txt file. This is the best solution if you want to install everything except maybe a few modules.
  • Fetch, build, and install the modules individually, starting from the SMS++ core library. This is the best approach if you need only the library and a few other modules.

Once you decide which modules to install and how, you will need to install the required software.

Requirements

Note: requirements are also specified in each module's README file. Moreover, the CMakeLists.txt file of the umbrella sums them up briefly.

The SMS++ core library requires the following libraries (here is why they are needed):

So, you will need at least those. The other submodules add the following (nested) requirements:

  • BundleSolver

    • NDOSolver/FiOracle: it's included as a subproject of BundleSolver, so it will be compiled with the umbrella by default. If you are installing BundleSolver individually, you will need to manually install this first. This library requires these libraries:
      • CoinUtils, required by Clp and Osi;
      • Clp and Osi, optional for NDOSolver/FiOracle but needed by BundleSolver;
      • CPLEX and/or GUROBI, optional requirements for Osi, but needed by BundleSolver.

  • MCFBlock

    • MCFClass: it's included as a subproject of MCFBlock, so it will be compiled with the umbrella by default. If you are installing MCFBlock individually, you will need to manually install this first. Optionally, MCFClass requires CPLEX.

  • MILPSolver

    • CPLEX (optional, minimum version 12.8.0)
    • GUROBI (optional minimum version 10.0.0)
    • SCIP (optional, minimum version 7.0.0)
    • HiGHS (optional, minimum version 1.5.3)

    Both requirements are optional, but you will need at least one of them to obtain a useful solver.

  • SDDPBlock

Below you will find the steps for each requirement.

Boost

On macOS, homebrew's repository includes an updated and working version:

brew install boost

On Debian/Ubuntu, if the repository has a supported version (at least 1.72) you can install it with:

# For the core library:
sudo apt install libboost-dev

# For StOpt (SDDPBlock) also do:
sudo apt install libboost-system-dev libboost-timer-dev libboost-random-dev libboost-mpi-dev

On Windows, you can install it with:

# For the core library:
vcpkg install boost --triplet x64-windows

# For StOpt (SDDPBlock) also do:
vcpkg install boost-mpi --triplet x64-windows

Note: In case of failure of the second command, execute vcpkg\downloads\msmpisetup-<x.y.z>.exe as suggested by the output error message.

Otherwise, you will need to build it from the source. Download the source from here and extract it, then navigate the extracted directory and run:

# If you only need SMS++ core library:
./bootstrap.sh --with-libraries=headers
sudo ./b2 install

# If you also need Boost.system, Boost.timer, Boost.random, and Boost.mpi for SDDPBlock:
./bootstrap.sh --with-libraries=headers,system,timer,random,mpi
sudo ./b2 install

You can find more details on how to obtain and build Boost here.

NetCDF-C++

NetCDF-C++ is a wrapper library for NetCDF-C, so you will need both.

On macOS, homebrew's repository includes a single, updated package that includes both NetCDF-C/C++:

brew install hdf5 netcdf netcdf-cxx

On Windows you can install them with:

vcpkg install netcdf-cxx4 --triplet x64-windows

On Debian/Ubuntu you can install them with:

sudo apt install libnetcdf-c++4-dev

In some Debian and Ubuntu versions, we found that the packages provided in the repositories were missing the configuration file needed by CMake to find the library while building SMS++. If CMake can't find NetCDF-C/C++ while configuring SMS++, try following these instructions to build them manually.

  1. First install NetCDF's requirements:

    # On Debian/Ubuntu
sudo apt install libhdf5-dev libcurl4-openssl-dev

# On macOS
brew install hdf5

  2. Download the latest NetCDF-C release from here and extract it.

  3. In the extracted directory, configure and build the library with CMake:

    mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_UTILITIES=OFF -DENABLE_TESTS=OFF ..
cmake --build .
cmake --install .

  4. Download the latest NetCDF-C++ release from here and extract it.

  5. In the extracted directory, configure and build the library with CMake:

    export CPATH="/usr/include/hdf5/serial/"
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DNCXX_ENABLE_TESTS=OFF ..
cmake --build .
cmake --install .

You can find more details on how to obtain and build NetCDF-C/C++ here.

Eigen

On macOS, homebrew's repository includes an updated and working version:

brew install eigen

On Debian/Ubuntu, the repository should contain an updated and working version:

sudo apt install libeigen3-dev

On Windows, Microsoft's vcpkg repository should contain an updated and working version:

vcpkg install eigen3 --triplet x64-windows

Otherwise, you will need to install it from the source.

  1. Download the latest Eigen release from here and extract it.

  2. In the extracted directory, configure and install the library with CMake:

    mkdir build
cd build
cmake ..
cmake --build .
cmake --install .

You can find more details on how to obtain and install Eigen here.

CPLEX

Install CPLEX using the installer provided by IBM for your OS. It's recommended to install it in the default directory, e.g., /Applications/CPLEX_Studio<ver> for macOS, /opt/ibm/ILOG/CPLEX_Studio<ver> on Linux, or C:\Program Files\IBM\ILOG\CPLEX_Studio<ver> for Windows.

For Windows, it's highly recommended to choose a space-free path, i.e., C:\IBM\ILOG\CPLEX_Studio<ver>, to avoid resource path linking problems in the Coin-OR Osi installation phase.

Note: Under Windows, the CPLEX main lib is called cplex<ver>.lib, but the Makefiles assumes that is just called cplex.lib, so to build SMS++ using them, it's necessary to define the following symlink using a cmd with admin rights from the CPLEX installation lib folder:

cd C:\Program Files\IBM\ILOG\CPLEX_Studio1210\cplex\lib\x64_windows_msvc14\stat_mda (or C:\IBM\ILOG\CPLEX_Studio1210\cplex\lib\x64_windows_msvc14\stat_mda)
mklink cplex.lib cplex<ver>.lib

Under Linux, CPLEX might not be found at runtime, in that case, run:

sh -c "echo '/opt/ibm/ILOG/CPLEX_Studio/cplex/lib/x86-64_linux' > /etc/ld.so.conf.d/cplex.conf"
sudo ldconfig

GUROBI

Install GUROBI using the installer you can find here. It's recommended that you install it in the default directory, e.g., /Library/gurobi<ver> for macOS, /opt/gurobi<ver> for Linux, or C:\gurobi<ver> for Windows.

Note: Under Linux, GUROBI might not be found at runtime, in that case, run:

sudo sh -c "echo '/opt/gurobi<ver>/linux64/lib' > /etc/ld.so.conf.d/gurobi.conf"
sudo ldconfig

Under macOS, if you install GUROBI elsewhere concerning the default location, i.e., /Library/gurobi<ver>, you will need to resign the library:

GUROBI_VERSION=$(ls "${GUROBI_HOME}/lib" | grep -E '^libgurobi[0-9]+\.dylib$' | sed -E 's/^libgurobi([0-9]+)\.dylib$/\1/' | head -n1)
install_name_tool -id "${GUROBI_HOME}/lib/libgurobi${GUROBI_VERSION}.dylib" "${GUROBI_HOME}/lib/libgurobi${GUROBI_VERSION}.dylib"
codesign -s - -f "${GUROBI_HOME}/lib/libgurobi${GUROBI_VERSION}.dylib" "${GUROBI_HOME}/lib/libgurobi${GUROBI_VERSION}.dylib"

SCIP

It's recommended to install the SCIP Optimization Suite using the installers you can find here. It's recommended to install it in the default directory, e.g., /Library/scip for macOS, /opt/scip for Linux, or C:\Program Files\SCIPOptSuite <ver> for Windows.

Before installing the suite, you will need to install the requirements:

# On Debian/Ubuntu
sudo apt install gfortran libtbb-dev

# On macOS
brew install gcc tbb

Once you have downloaded the installer for your OS, launch it:

chmod u+x SCIPOptSuite-<ver>-<OS>.sh
./SCIPOptSuite-<ver>-<OS>.sh --prefix=/opt/scip --exclude-subdir --skip-license

Note: Under Linux, SCIP might not be found at runtime, in that case, run:

sudo sh -c "echo '/opt/scip/lib' > /etc/ld.so.conf.d/scip.conf"
sudo ldconfig

HiGHS

To install HiGHS you will need to build sources. It's recommended to install it in the default directory, e.g., /Library/HiGHS for macOS, /opt/HiGHS for Linux, or C:\HiGHS for Windows.

So, after placing in one of these folders, download the sources:

git clone https://github.com/ERGO-Code/HiGHS.git

then configure them:

cd HiGHS
mkdir build
cd build
# On Debian/Ubuntu
cmake -DFAST_BUILD=ON -DCMAKE_INSTALL_PREFIX=/opt/HiGHS ..
# On Windows
cmake -DFAST_BUILD=ON -DCMAKE_INSTALL_PREFIX=C:/HiGHS ..

finally, build:

# On Debian/Ubuntu
cmake --build .
# On Windows
cmake --build . --config Release

and, optionally, install:

cmake --install .

Note: Under Linux, HiGHS might not be found at runtime, in that case, run:

sudo sh -c "echo '/opt/HiGHS/lib' > /etc/ld.so.conf.d/highs.conf"
sudo ldconfig

COIN-OR CoinUtils

On macOS, homebrew's repository includes an updated version of CoinUtils. This package has the following downside: it depends on OpenBLAS instead of using macOS's own BLAS implementation, so you will install an otherwise useless package.

If you are fine with that, you can do:

brew install coinutils

On Debian/Ubuntu, so you can do:

sudo apt install coinor-libcoinutils-dev

On Windows, in the vcpkg installation folder, you can do:

vcpkg install coinutils pybind11 --triplet x64-windows

Otherwise, you have two choices for installing it from the source:

  • Use coinbrew, COIN-OR's own installation helper
  • Fetch and build the libraries manually

The complexity is more or less the same.

Coinbrew

coinbrew in a helper script that will fetch, build, and install COIN-OR packages. By default, it would also build and install some requirements such as BLAS and LAPACK, but it's recommended to install them first with your package manager to save some time:

  1. On Debian/Ubuntu, install the requirements with apt:

    sudo apt install libbz2-dev liblapack-dev libopenblas-dev

    On Windows, install the requirements with vcpkg:

    vcpkg install blas lapack --triplet x64-windows

    macOS already has those requirements installed.

  2. Get the coinbrew script with:

    curl -O https://raw.githubusercontent.com/coin-or/coinbrew/master/coinbrew
chmod u+x coinbrew

  3. Run coinbrew with the following parameters:

    ./coinbrew build CoinUtils --latest-release \
    --skip-dependencies \
    --prefix=/opt/coin-or \
    --tests=none

See the coinbrew page for further details.

Manual install

In case you need to build the libraries manually, follow these instructions.

  1. On Debian/Ubuntu, install the requirements with apt:

    sudo apt install libbz2-dev liblapack-dev libopenblas-dev

    On Windows, install the requirements with vcpkg:

    vcpkg install blas lapack --triplet x64-windows

    macOS already has those requirements installed.

  2. Download the latest CoinUtils release from here and extract it.

  3. In the extracted directory, configure and build the library with CMake:

    ./configure --prefix=/opt/coin-or
cmake --build .
cmake --install .

COIN-OR Osi/Clp

The pre-compiled packages of these libraries have the following downside: Osi packages do not come with CPLEX support, which is required by BundleSolver; and since Clp packages depend on Osi ones, they cannot be used, either.

For installing Osi and Clp with CPLEX support you have two choices:

  • Use coinbrew, COIN-OR's own installation helper
  • Fetch and build the libraries manually

The complexity is more or less the same.

Coinbrew

See above how to get coinbrew and install CoinUtils. Then follow these steps.

  1. Fetch and install Osi:

    # Set here your main CPLEX Studio directory
CPLEX_DIR=<cplex-studio-dir>
CPLEX_LIB_DIR=`ls -bd1 $CPLEX_DIR/cplex/lib/*/static_pic | tail -n1`

# Set here your main GUROBI directory
GUROBI_DIR=<gurobi-dir>
GUROBI_LIB_DIR=`ls -bd1 $GUROBI_DIR/*/lib | tail -n1`
GUROBI_INCLUDE_DIR=`ls -bd1 $GUROBI_DIR/*/include | tail -n1`

# On Debian/Ubuntu
./coinbrew build Osi --latest-release \
    --skip-dependencies \
    --prefix=/opt/coin-or \
    --tests=none \
    --with-cplex \
    --with-cplex-lib="-L$CPLEX_LIB_DIR -lcplex -lpthread -lm" \
    --with-cplex-incdir="$CPLEX_DIR/cplex/include/ilcplex" \
    --with-gurobi \
    --with-gurobi-lib="-L$GUROBI_LIB_DIR -lgurobi100" \
    --with-gurobi-incdir="$GUROBI_INCLUDE_DIR"

# On macOS
./coinbrew build Osi --latest-release \
    --skip-dependencies \
    --prefix=/opt/coin-or \
    --tests=none \
    --with-cplex \
    --with-cplex-lib="-L$CPLEX_LIB_DIR -lcplex -lm" \
    --disable-cplex-libcheck \
    --with-cplex-incdir="$CPLEX_DIR/cplex/include/ilcplex" \
    --with-gurobi \
    --with-gurobi-lib="-L$GUROBI_LIB_DIR -lgurobi100" \
    --disable-gurobi-libcheck \
    --with-gurobi-incdir="$GUROBI_INCLUDE_DIR"

    Note: On macOS, the configuration script may not be able to properly check the CPLEX library via the CPXgetstat() symbol. If you think that your --with-cplex-lib (or --with-gurobi-lib) flag is correct, you can suppress the check with the --disable-cplex-libcheck (or --disable-gurobi-libcheck) flag.

  2. Fetch and install Clp:

    ./coinbrew build Clp --latest-release \
    --skip-dependencies \
    --prefix=/opt/coin-or \
    --tests=none

See the coinbrew page for further details.

Manual install

On Windows, to be able to install the package coin-or-osi with the interfaces to CPLEX and/or GUROBI, we will need to modify its vcpkg configuration file, so go to vcpkg\ports\coin-or-osi\portfile.cmake and substitute:

--without-cplex
--without-gurobi

with something like this:

--with-cplex
--with-cplex-lib=C:\/IBM\/ILOG\/CPLEX_Studio<ver>\/cplex\/lib\/x64_windows_msvc<ver>\/stat_mda\/cplex<ver>.lib
--with-cplex-incdir=C:\/IBM\/ILOG\/CPLEX_Studio<ver>\/cplex\/include\/ilcplex
--with-cplex-cflags=-IC:\/IBM\/ILOG\/CPLEX_Studio<ver>\/cplex\/include\/ilcplex
--with-cplex-lflags=C:\/IBM\/ILOG\/CPLEX_Studio<ver>\/cplex\/lib\/x64_windows_msvc<ver>\/stat_mda\/cplex<ver>.lib

and this:

--with-gurobi
--with-gurobi-lib=C:\/gurobi<ver>\/win64\/lib\/gurobi<ver>.lib
--with-gurobi-incdir=C:\/gurobi<ver>\/win64\/include
--with-gurobi-cflags=-IC:\/gurobi<ver>\/win64\/include
--with-gurobi-lflags=C:\/gurobi<ver>\/win64\/lib\/gurobi<ver>.lib

respectively, with your paths to the same resources.

Note: It may be needed to not have any white spaces in the paths for this to work properly. Also, notice that the \/ for Windows path specification is not optional.

Then, from the vcpkg installation folder, you can finally install the packages:

vcpkg install coin-or-osi coin-or-clp glpk pybind11 --triplet x64-windows

In case you need to build the libraries manually, follow these instructions.

  1. Download the latest Osi release from here and extract it.

  2. In the extracted directory, configure and build the library with CMake:

    # Set here your main CPLEX Studio directory
CPLEX_DIR=<cplex-studio-dir>
CPLEX_LIB_DIR=`ls -bd1 $CPLEX_DIR/cplex/lib/*/static_pic | tail -n1`

# Set here your main GUROBI directory
GUROBI_DIR=<gurobi-dir>
GUROBI_LIB_DIR=`ls -bd1 $GUROBI_DIR/*/lib | tail -n1`
GUROBI_INCLUDE_DIR=`ls -bd1 $GUROBI_DIR/*/include | tail -n1`

# On Debian/Ubuntu
./configure --prefix=/opt/coin-or \
    --with-cplex \
    --with-cplex-lib="-L$CPLEX_LIB_DIR -lcplex -lpthread -lm" \
    --with-cplex-incdir="$CPLEX_DIR/cplex/include/ilcplex" \
    --with-gurobi \
    --with-gurobi-lib="-L$GUROBI_LIB_DIR -lgurobi100" \
    --with-gurobi-incdir="$GUROBI_INCLUDE_DIR"

# On macOS
./configure --prefix=/opt/coin-or \
    --with-cplex \
    --with-cplex-lib="-L$CPLEX_LIB_DIR -lcplex -lm" \
    --with-cplex-incdir="$CPLEX_DIR/cplex/include/ilcplex" \
    --disable-cplex-libcheck \
    --with-gurobi \
    --with-gurobi-lib="-L$GUROBI_LIB_DIR -lgurobi100" \
    --disable-gurobi-libcheck \
    --with-gurobi-incdir="$GUROBI_INCLUDE_DIR"

cmake --build .
cmake --install .

    Note: On macOS, the configuration script may not be able to properly check the CPLEX library via the CPXgetstat() symbol. If you think that your --with-cplex-lib (or --with-gurobi-lib) flag is correct, you can suppress the check with the --disable-cplex-libcheck (or --disable-gurobi-libcheck) flag.

  3. Download the latest Clp release from here and extract it.

  4. In the extracted directory, configure and build the library with CMake:

    ./configure --prefix=/opt/coin-or
cmake --build .
cmake --install .

StOpt

On the most recent Debian/Ubuntu distributions, the Stochastic Control library is available with apt:

sudo apt install libstopt5 libstopt-dev

Otherwise, you will need to build and install from the source:

  1. Install Eigen, Boost.system, Boost.timer, and Boost.random (see above).

  2. On Debian/Ubuntu, install the requirements with apt:

    sudo apt install zlib1g-dev libbz2-dev

    macOS already has those requirements installed.

  3. Download the latest StOpt source code:

    git clone https://gitlab.com/stochastic-control/StOpt

  4. Then configure and build the library with CMake:

    cd StOpt
mkdir build
cd build
cmake -DBUILD_PYTHON=OFF -DBUILD_TEST=OFF ..
cmake --build .
cmake --install . --prefix /opt/stopt

On Windows, to install the StOpt package we will need to install it before its vcpkg registry since it is not available on the public Microsoft vcpkg repository, so download:

git clone https://gitlab.com/stochastic-control/vcpkg-registry

and then, back to the vcpkg installation folder, and run:

vcpkg install stopt --overlay-ports=C:/vcpkg/vcpkg-registry/ports/stopt --triplet x64-windows

making attention to substitute the right vcpkg path with yours.

SMS++

You can proceed in two ways, depending on how many modules you need:

  • Use the umbrella to fetch multiple modules at once;
  • Fetch, build and install the modules individually.

If you prefer, you can use the instructions in the README files of the individual projects.

Using the umbrella

  1. Fetch the SMS++ project and all its modules at once, with the command:

    git clone -b develop --recurse-submodules https://gitlab.com/smspp/smspp-project.git # see note below
cd smspp-project

    Alternatively, you can save some time by fetching only the modules you need:

    git clone -b develop https://gitlab.com/smspp/smspp-project.git # see note below
cd smspp-project
git submodule update --init SMS++ UCBlock tools # ...

    Note: It is highly recommended to clone the develop branch directly, i.e., -b develop, if any, without passing from the master one, since the development of the SMS++ library is rapid, and the master branch quickly becomes stale.

  1. Optional: edit the CMakeLists.txt file and comment the lines referring to the modules you don't need.

  2. Use CMake to configure and build the project:

    # On Unix
mkdir build
cd build
cmake ..

# On Windows
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake .. # see note below

    paying attention to substitute the right vcpkg path with yours.

    You can specify some configuration options in the cmake command (see here).

    Note: Consider using the CMake flag -Wno-dev to suppress warnings that are intended for the developers of the CMake project and not the users.

  3. Build and install the project with:

    cmake --build . --config Release
cmake --install . --config Release # optional

Alternatively, you can build the project without using CMake. See the Build and install with makefiles section in the README file of the project.

Build the individual modules

Repeat the following steps for each module you want to build (as an example, the steps apply to the SMS++ core library).

  1. Fetch the module with the command:

    git clone -b develop https://gitlab.com/smspp/smspp.git # see note below
cd smspp

    Note: It is highly recommended to clone the develop branch directly, i.e., -b develop, if any, without passing from the master one, since the development of the SMS++ library is rapid, and the master branch quickly becomes stale.

  1. Use CMake to configure the module:

    # On Unix
mkdir build
cd build
cmake ..

# On Windows
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake .. # see note below

    paying attention to substitute the right vcpkg path with yours.

    You can specify some configuration options in the cmake command (see here).

    Note: Consider using the CMake flag -Wno-dev to suppress warnings that are intended for the developers of the CMake project and not the users.

  2. Build and install the project with:

    cmake --build . --config Release
cmake --install . --config Release # see note below

    Note: Installation is required for other modules to find the library. As an alternative, you can use CMake's User Package Registry, see the relevant section in the customization guide.

The test environment

You can find a good example of the above steps for the installation of SMS++ and its requirements in our Test Environment.

You can either use the environment as-is or use its scripts as a reference for installing SMS++ on your machine. In particular, smsbuild script allows to building SMS++ in the two methods described above (with or without the umbrella) and provides several customization options.

Issues and troubleshooting

If you need support, you want to submit bugs or propose a new feature for an individual module, see the Getting help section of the README for that module.

If you need support on the project installation that is not covered by the troubleshooting page, or want to propose a new module, you can open a new issue.

Clone this wiki locally