Installation

The simplebuild system is supported only on unix systems (macOS and Linux), although it most likely will also work on Windows under the WSL (Windows Subsystem for Linux) with a virtual Ubuntu installation. It is used exclusively by entering shell commands in a terminal interface, so be sure you are familiar with such command line interfaces.

Note

The instructions here concern an installation of the basic simplebuild system. Users who will be using simplebuild with the Geant4-based framework in the “dgcode” bundle should simply skip the instructions here, and instead follow the instructions for how to install both simplebuild and “dgcode” on https://mctools.github.io/simplebuild-dgcode/install.html.

Install via conda

Current status: sbcondastatus sbcondaplatforms

The recommended and easiest way to install simplebuild, is by installing the conda-forge package simple-build-system (plus at least compilers), using a conda environment .yml file like:

name: sbenv
channels:
  - nodefaults
  - conda-forge
dependencies:
  - compilers
  - bash
  - simple-build-system

You can download the above recipe file here: conda_sbenv.yml.

To use it, you must first install conda. Instructions for how to do that is beyond the scope of the present documentation, but in general this can be done in a variety of ways (installing Miniforge, Miniconda, Anaconda, or even via Homebrew). If you don’t have conda installed already and do not have any other reason for a preference, we would recommend to use Miniforge since it is light-weight and supposedly has the fewest legal concerns.

After you have conda installed, download conda_sbenv.yml and run the command:

conda env create -f conda_sbenv.yml

Do not forget that you must activate your newly created environment before using it for the first time in a given terminal session:

conda activate sbenv

Alternatives for experts

The conda recipe above is intended to give a self-contained and reproducible environment with not only simplebuild itself, but also any required tools like a Python interpreter and all the necessary build tools. For special advanced use-cases, experts might simply want to add the simplebuild code itself into an environment where they otherwise have ensured that all of these third-party tools are already available. In such a case, one can simply install simplebuild itself via pip, either via a PyPI package (current version pypistatus_simplebuildsystem):

python3 -mpip install simple-build-system

Or, directly from the latest simplebuild sources at GitHub:

python3 -mpip install git+https://github.com/mctools/simplebuild

With this latter approach, one can even install a specific commit id, branch, or tag by appending @<gitid> to the URL in the last command. For instance:

python3 -mpip install git+https://github.com/mctools/simplebuild@some_experimental_branch

Note about the installed simplebuild environment: when installing via pip, one downside of not using the conda packages is the lack of automatic activation of bundles built with sb (i.e. commands sb_mypkg_mycmd will not be in your PATH, and so on). In conda, this is handled by automatically injecting a sneaky shell function named sb into your shell session when you activate the conda environment. When not using the conda simple-build-system package, you have two options:

  1. Do not get anything done automatically, and resort to either running eval "$(sb --env-setup)" when needed or prefixing all of your commands with sbenv (i.e. run sbenv sb_mypkg_mycmd).

  2. Download this shell snippet and either source it or copy and paste it into the end of the appropriate file shell initialisation file (e.g. ~/.bashrc on Ubuntu or ~/.zshrc on macOS).

Verifying an installation

As a very basic verification of a simplebuild installation, one can create a simple simplebuild configuration and launch a few basic unit tests from the core_val bundle (you can remove the leftover sbverify directory afterwards):

$> conda activate sbenv
(sbenv) $> mkdir sbverify
(sbenv) $> cd sbverify
(sbenv) $> sb --init core_val
sbld:  Created simplebuild.cfg. If you wish you can edit it to fine-tune your configuration
(sbenv) $> sb --tests
sbld:  Inspecting environment via CMake
-- Using CMAKE_BUILD_TYPE=Release
-- The C compiler identification is GNU 13.3.0
-- The CXX compiler identification is GNU 13.3.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /conda/envs/sbenv/bin/x86_64-conda-linux-gnu-cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /conda/envs/sbenv/bin/x86_64-conda-linux-gnu-c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Python executable: /conda/envs/sbenv/bin/python3
-- Python version: 3.12.6
-- Performing Test compiler_supports_Wno-array-bounds
-- Performing Test compiler_supports_Wno-array-bounds - Success
-- Performing Test compiler_supports_Wno-stringop-overread
-- Performing Test compiler_supports_Wno-stringop-overread - Success
-- Found pybind11 version 2.13.6
-- Checking for NCrystal installation
-- Checking for NCrystal installation -- no
-- Skipped unused dependencies: ASE DL Fortran Garfield Geant4 Gemmi
--                              HDF5 Mantidpython Numpy OSG Pandas Pymatgen
--                              ROOT Scipy Spglib Threads ZLib matplotlib
--                              mpmath
-- Configuring done (3.9s)
-- Generating done (0.0s)
-- Build files have been written to: /some/where/sbverify/simplebuild_cache/bld/cmake
sbld:  Environment inspection done (3.9 seconds)
sbld:  Disabled 1 packages due to missing external dependencies
sbld:  Configuration completed => Launching build with 4 parallel processes
make[1]: Entering directory '/some/where/sbverify/simplebuild_cache/bld/makefiles'
Build started
  Updating symlinks Core/python
  Installing Core headers
  Updating symlinks Core/scripts
  Generating Core/__init__.py
  Updating symlinks Core/testlogs
  Updating symlinks CoreTests/scripts
  Updating symlinks CoreTests/testlogs
Installing global system modules
  Building Core/pycpp_misc/mod.o
  Building Core/libsrc/FPE.o
  Building Core/libsrc/File.o
  Building Core/libsrc/FindData.o
  Building Core/libsrc/String.o
  Building Core/libsrc/static_asserts.o
  Building Core/pycpp_FPE/mod.o
  Building Core/app_cmakebuildtype/main.o
  Building CoreTests/app_testpycpp/main.o
  Building CoreTests/app_testformat/main.o
  Building CoreTests/app_teststring/main.o
  Building CoreTests/app_build_is_debug/main.o
  Building CoreTests/app_testfile/main.o
  Building CoreTests/app_testsdk/main.o
  Building CoreTests/app_forcefpe/main.o
  Creating shared library for package Core
  Creating application sb_core_cmakebuildtype
  Creating application sb_coretests_testformat
  Creating application sb_coretests_teststring
  Creating application sb_coretests_build_is_debug
  Creating application sb_coretests_testfile
  Creating application sb_coretests_testsdk
  Creating application sb_coretests_forcefpe
  Creating python module Core.misc
  Creating application sb_coretests_testpycpp
Package CoreTests done
  Creating python module Core.FPE
Package Core done
All done
make[1]: Leaving directory '/some/where/sbverify/simplebuild_cache/bld/makefiles'
sbld:  Summary:
sbld: 
sbld:    Main bundle pkg root             : /some/where/sbverify
sbld:    Installation directory           : /some/where/sbverify/simplebuild_cache/install
sbld:    Build directory                  : /some/where/sbverify/simplebuild_cache/bld
sbld:    Package search path              : /some/where/sbverify (no pkgs)
sbld:                                       ${CONDA_PREFIX}/lib/python3.12/site-packages/_simple_build_system/data/pkgs-core (1 pkgs)
sbld:                                       ${CONDA_PREFIX}/lib/python3.12/site-packages/_simple_build_system/data/pkgs-core_val (1 built, 1 skipped)
sbld:    System                           : Linux-6.8.0-1014-azure
sbld:    Required dependencies            : C[GNU/13.3.0] CMake[3.30.4] CXX[GNU/13.3.0]
sbld:                                       Python[3.12.6] pybind11[2.13.6]
sbld:    Optional dependencies present    : <none>
sbld:    Optional dependencies missing[*] : ASE DL Fortran Garfield Geant4 Gemmi HDF5
sbld:                                       Mantidpython NCrystal Numpy OSG Pandas Pymatgen
sbld:                                       ROOT Scipy Spglib Threads ZLib matplotlib
sbld:                                       mpmath
sbld:    Package filter[*]                : <none>
sbld:    Build mode                       : release
sbld:  
sbld:    2 packages built successfully    : Core CoreTests
sbld:    1 package skipped due to [*]     : CoreLinkTests
sbld: 
sbld:  Running tests in /some/where/sbverify/simplebuild_cache/bld/testresults:
sbld: 
make[1]: Entering directory '/some/where/sbverify'
make[1]: Leaving directory '/some/where/sbverify'
sbld:   ---------------------------------------+-----------+--------+----------+------------------
sbld:    Test job results                      | Time [ms] | Job EC | Log-diff | Trouble info
sbld:   ---------------------------------------+-----------+--------+----------+------------------
sbld:    sb_coretests_testfile                 |      11   |   OK   |    --    | --
sbld:    sb_coretests_testformat               |       8   |   OK   |    --    | --
sbld:    sb_coretests_testfpe                  |      18   |   OK   |    --    | --
sbld:    sb_coretests_testlibsymbols           |      20   |   OK   |    --    | --
sbld:    sb_coretests_testnodostxt             |     180   |   OK   |    --    | --
sbld:    sb_coretests_testpycpp                |      93   |   OK   |    --    | --
sbld:    sb_coretests_testpylibsymbols         |     158   |   OK   |    --    | --
sbld:    sb_coretests_testpyquery              |     211   |   OK   |    --    | --
sbld:    sb_coretests_testsdk                  |       6   |   OK   |    --    | --
sbld:    sb_coretests_teststring               |       6   |   OK   |    --    | --
sbld:   ---------------------------------------+-----------+--------+----------+------------------
sbld: 
sbld:    Test results are also summarised in: simplebuild_test_results_junitformat.xml
sbld: 
sbld:    All tests completed without failures!
sbld: 
sbld:  Build done. You are all set to begin using the software!
sbld: 
sbld:  To see available applications, type "sb_" and hit the TAB key twice.
sbld:

The important thing to notice here is that several unit tests were launched, and the message All tests completed without failures! tells us that they all completed without problems.