Home » SSTDocumentation » Detailed Build and Installation Instructions for SST 12.1.x

Detailed Build and Installation Instructions for SST 12.1.x

Detailed Build and Installation Instructions for SST 12.1.x

Overview

SST is an open source, cross platform simulation platform that provides a framework to connect multiple simulated hardware object including CPUs, network, memory, etc. Simulations using the toolkit can be run either single node, or run on multiple nodes via MPI. The toolkit provides a parallel discrete event core as well as several programming interfaces including classes to manage random number generation, statistics handling, simulation output and efficient memory pooling for simulation events. The most recent performance evaluation has shown that SST can scale to simulate beyond 1.5M objects and operate efficiently on simulations up to 128 dual-processor nodes.

These instructions are intended to walk the user through a detailed set of steps to build and install SST. It is for users with intermediate knowledge in the operation of Unix/Linux/OSX environments.

NOTE: The following instructions build a basic version of SST and its required external components. Additional (optional) external components can be built to provide additional features. Instructions for these additional components are available at Instructions for Additional External SST Components.

The SST Release Notes identify what operating systems, compiler and external component combinations have been tested and proven to work with SST 12.1.x.

NOTE: Using combinations other than what is identified in the Release Notes may cause build failures and/or unexpected results.

A detailed list of elements provided with the SST distribution are available at SST Element Summary and SST Element Release Matrix.

If you encounter difficulties, go to the SST Support page.

NOTE: Building SST can be cumbersome and error prone due to the sheer number of combinations of operating systems, compiler versions and external components. It is STRONGLY recommended that users closely follow these instructions.

General Build and Install Information

SST does not require root/superuser privileges for installation. Prior to installation, the user will need to decide on directories where SST and its prerequisites can be built and installed. This location should have sufficient space and permissions for building and storage of the libraries and other binaries.

The user is expected to have an intermediate knowledge in the operation of Unix/Linux/OSX environments. They should be able to modify their environment variables, and understand basic build/installation methods, and manipulate the file system.

NOTE: SST and all of its external components should be built using the same compiler type and version. Mixing different compiler types or versions can create binary incompatibilities that can be difficult to diagnose.

Shell Used For Instructions

These instructions are targeted to users running Bourne-compatible shells. Users running different shells will need to adjust these instructions as necessary.

Specific Instructions for Operating Systems and Compilers

There are 2 main operating systems used for SST: Linux and Mac OSX (macOS).

In the Linux OS, gcc is the only supported compiler.
In the Mac OSX OS, clang (XCode) is the only supported compiler

In the instructions that follow, the following icons are used to point out specific issues for an operating system or an operating system with a specific compiler.

- Represents Instructions specific to Linux Operating Systems.

- Represents Instructions specific to Mac OSX Operating Systems.

Required system tools

Refer to SST Build Prerequisites for a list of required system tools necessary for building SST.

- Most Linux Systems contain all the necessary tools required to build SST (either pre-installed or available via the distro.). However, some older versions may need their system tools updated to newer revisions.

NOTE - Newer versions of components for SST (such as OpenMPI) can cause incompatibilites. It is recommended that the versions defined in the SST Release Notes be used if at all possible.

- Mac OSX systems will need the following to be installed on the system before building SST see (Mac OSX Install Options):

XCode and XCode Command line tools
Autotools (automake, autoconf, libtool)
- Installed via MacPorts (Configuring Mac OSX for SST using MacPorts) or Homebrew
- Built separately. (Configuring Autotools on Mac)
Python 3.6 or newer
- Installed via MacPorts (Configuring Mac OSX for SST using MacPorts) or Homebrew
- Built separately or acquired via python.org

Example Build and Install Directories

These instruction use the following conventions (though users can adjust these as they see fit):

Download directory $HOME/scratch
- This directory will contain downloaded source code packages for SST and its dependencies.
- The following directories should be created on the users machine
  - $HOME/scratch
  - $HOME/scratch/src
Installation directory $HOME/local
- This directory will be the installation directory for SST and its dependencies.
- The following directories should be created on the users machine
  - $HOME/local
  - $HOME/local/packages

Other Possible Tasks for Users

For most users, following these instructions will get SST up and running. However there may be rare circumstances that the user will have implement additional changes to their system to resolve problems.

The user may have to possibly modify their system environment in the following possible ways:

Modifying the $PATH environment variable to include directories as needed
Modifying compiler options in makefiles so that the appropriate directories are searched during the build.
Modifying the $LD_LIBRARY_PATH environment variable to include directories that are searched for shared libraries at runtime (for .so files).
For Mac OSX, modifying the $DYLD_LIBRARY_PATH environment variable to include directories that are searched for shared libraries at runtime (for .dylib files).
Modifying the $MANPATH environment variable to include directories so that they are searched for man page documentation.

It is expected that the user has sufficent knowledge and experience in Linux and/or Mac OSX operating systems to understand and manage these changes.

Building A Basic SST System

SST recommends that one external component (OpenMPI) be built, installed and available on the user’s machine. After this component is available, then SST itself can be built and installed.

Additional external components can be built to provide additional features. Instructions for these additional components are available at Instructions for Additional External SST Components.

NOTE: If OpenMPI is not available, the SST-Core must be configured with the --disable-mpi option (see configure instructions below). With OpenMPI disabled, the user will be unable to run multi-node simulations.

External Dependent Components

OpenMPI 4.0.5 (Strongly Recommended)

SST 12.1.x is regularly tested with OpenMPI 4.0.5, and this version is known to work with SST. Installation of an MPI package from source code is typically unnecessary, since many Linux distributions and MacOS X package managers provide OpenMPI as an optional installable package. Instructions for building OpenMPI 4.0.5 follow.

OpenMPI can be obtained online at http://www.open-mpi.org/software/ompi/v4.0/

1. Download the OpenMPI archive file openmpi-4.0.5.tar.gz to $HOME/scratch/src

2. Unarchive the compressed tar file

$ cd $HOME/scratch/src
$ tar xfz openmpi-4.0.5.tar.gz
$ cd openmpi-4.0.5

3. Decide on an installation location. For this example: $HOME/local/packages/OpenMPI-4.0.5. Note this location will contain bin, lib, include, and other directories for use of OpenMPI.

4. Set the home directory environment variable of the OpenMPI installation.

$ export MPIHOME=$HOME/local/packages/OpenMPI-4.0.5

5. Configure OpenMPI to be installed in $MPIHOME

$ ./configure --prefix=$MPIHOME

6. Build and install OpenMPI

$ make all install

7. Update your PATH environment variable so that it contains the bin directory of the OpenMPI installation location. Also set the MPICC and MPICXX variables to point to the correct MPI compiler options. initialization file.

$ export PATH=$MPIHOME/bin:$PATH
$ export MPICC=mpicc
$ export MPICXX=mpicxx

8. Set the PMIX_MCA_gds to hash. This corrects some know issues with OpenMPI 4.0.5

$ export PMIX_MCA_gds=hash

9. OPTIONAL - In some cases, it may be necessary to specify the location of the OpenMPI library files for proper operation of SST.

$ export LD_LIBRARY_PATH=$MPIHOME/lib:$LD_LIBRARY_PATH
$ export DYLD_LIBRARY_PATH=$MPIHOME/lib:$DYLD_LIBRARY_PATH
$ export MANPATH=$MPIHOME/share/man:$DYLD_LIBRARY_PATH

10. To make the changes to the environment variables a permanent change, it may require editing of your login shell’s initialization file.

SST Build Architecture

NOTE - SST is comprised of at least two separate packages:

The first package is the SST-Core, which contains the simulation engine and API interface to simulation elements.
The second package(s) are the SST Elements, which contain simulation models and support elements.
- The majority of Elements included with SST reside in the SST-Elements package, but other Elements (e.g., SST-Macro) are available seperately.
- This independent core and elements architecture allows for easier development and support for 3rd party elements.
- The SST-Core MUST be built and installed first before any elements can be built.
- The SST-Elements package is optional, however it does contain a number of support elements that can be used by 3rd party elements.

NOTE - SST (7.x and later) no longer requires that Boost be built as part of the core.

* Some 3rd party elements may require Boost - It is recommended NOT to build SST-Core with Boost until it is confirmed that it is necessary.

SST Core 12.1.x Build and Installation

After the prerequisite Components (OpenMPI and other optional components) have been successfully installed, the SST-Core can then be built and installed.

NOTE: The following instructions assume SST-Core is being built from the tarfile distribution.
- If desired, the latest stable development version of SST-Core can be acquired from here. See What’s Next for more information.

1. Obtain the SST-Core 12.1.x source code and save it in $HOME/scratch/src. The tarfile can be downloaded from here.

Note: The following instructions assume SST-Core version 12.1.0. The user will need to adjust the directory name to match the SST-Core version.

$ cd $HOME/scratch/src
$ tar xfz sstcore-12.1.0.tar.gz
$ cd $HOME/scratch/src/sstcore-12.1.0

2. Set the home directory environment variable to the SST-Core installation (i.e. where you want the SST-Core files installed), and the source directory.

$ export SST_CORE_HOME=$HOME/local/sstcore-12.1.0
$ export SST_CORE_ROOT=$HOME/scratch/src/sstcore-12.1.0

3. Review prerequisite package installation locations and use this to construct a configure line for SST-Core. For more information on SST-Core configuration click here or run $ ./configure –help

4. Configure SST-Core, being sure to make configure reference the location of SST-Core’s local prerequisite packages.

$ ./configure --prefix=$SST_CORE_HOME [other configure settings as needed]

5. Build and install SST-Core

$ make all
$ make install

6. Update your PATH environment variable so that it contains the bin directory of the SST-Core installation location.

$ export PATH=$SST_CORE_HOME/bin:$PATH

7. Test your SST-Core install

$ which sst
$ sst --version
$ sst-info
$ sst-test-core

8. To make the changes to the environment variables a permanent change, it may require editing of your login shell’s initialization file.

SST Elements 12.1.x Build and Installation

After SST-Core has been successfully installed, SST-Elements can then be built and installed.

NOTE: The following instructions assume SST-Elements is being built from the tarfile distribution.
- If desired, the latest stable development version of SST-Elements can be acquired from here. See What’s Next for more information.

1. Obtain the SST-Elements 12.1.x source code and save it in $HOME/scratch/src. The tarfile can be downloaded from here.

Note: The following instructions assume SST-Elements version 12.1.0. The user will need to adjust the directory name to match the SST-Elements version.

$ cd $HOME/scratch/src
$ tar xfz sstelements-12.1.0.tar.gz
$ cd $HOME/scratch/src/sst-elements-library-12.1.0

2. Set the home directory environment variable to the SST-Elements installation (i.e. where you want the SST-Elements files installed), and the source directory.

$ export SST_ELEMENTS_HOME=$HOME/local/sstelements-12.1.0
$ export SST_ELEMENTS_ROOT=$HOME/scratch/src/sst-elements-library-12.1.0

3. Review prerequisite package installation locations and use this to construct a configure line for SST-Elements. For more information on SST-Elements configuration click here or run $ ./configure –help

4. Configure SST-Elements, being sure to make configure reference the location of SST-Elements’s local prerequisite packages.

$ ./configure --prefix=$SST_ELEMENTS_HOME --with-sst-core=$SST_CORE_HOME [other configure settings as needed]

5. Build and install SST-ELEMENTS (This will register SST-Elements with the SST-Core)

$ make all
$ make install

6. Update your PATH environment variable so that it contains the bin directory of the SST-ELEMENTS installation location.

$ export PATH=$SST_ELEMENTS_HOME/bin:$PATH

7. Test your SST-Elements install

$ which sst
$ sst --version
$ sst-info
$ sst-test-elements -w "*simple*"

8. To make the changes to the environment variables a permanent change, it may require editing of your login shell’s initialization file.

Testing SST 12.1.x Functionality

1. Run a very simple sanity test

$ sst --version

2. Verify elements are installed (should generate a list of elements)

$ sst-info

3. Run the full suite of tests

$ sst-test-core
$ sst-test-elements (NOTE: This will take a long time to run. 
                     For a shorter sanity check, try 'sst-test-elements -w "*simple*"'.)

Other SST Elements

Additional SST elements are available at the GitHub sstsimulator organization page.

NOTE: The SST-Core bin directory must be in the PATH envronment variable

1. Verify that applications in the SST-Core bin directory are found in the proper directory defined by the PATH environment variable>

$ which sst-register
$ which sst-config

sst-external-element

The sst-external-element element is an example template to demonstrate how to build a standalone 3rd party element.

After SST-Core has been successfully installed, the sst-external-element element can then be built and installed.

Note: The instructions below assume the user will clone the external element. The user may also download the sst-external-element 12.1.x released element

1. Clone the master branch of sst-external-element in $HOME/scratch/src. The repository can be found here.

$ cd $HOME/scratch/src
$ git clone https://github.com/sstsimulator/sst-external-element.git
$ cd $HOME/scratch/src/sst-external-element
$ git checkout v12.1.0_Final

2. Build and install sst-external-element (This will register sst-external-element with the SST-Core)

$ cd src
$ make

juno

The juno element is a very lightweight processor model which executes programs written in a simple assembly.

After SST-Core and SST-Elements have been successfully installed, the juno element can then be built and installed.

Note: The instructions below assume the user will clone the external element. The user may also download the juno 12.1.x released element

1. Clone the master branch of juno in $HOME/scratch/src. The repository can be found here.

$ cd $HOME/scratch/src
$ git clone https://github.com/sstsimulator/juno.git
$ cd $HOME/scratch/src/juno
$ git checkout v12.1.0_Final

2. Build and install juno (This will register juno with the SST-Core)

$ cd src
$ make
$ cd ..

3. Build the juno assembler

$ cd asm
$ make
$ cd ..

To use the assembler

<juno root dir>/asm/sst-juno-asm -i <inputfile>.juno -o <outputfile>.bin

Example:
$ cd ./test/asm/
$ ../../asm/sst-juno-asm -i sum.juno -o sum.bin
$ cd ../sst
$ JUNO_EXE=../asm/sum.bin sst juno-test.py

balar

The balar element is a GPU Simulation model based on the PTX virtual ISA. It integrates GPGPU-Sim into the SST simulation infrastructure.

SUPPORT NOTICE: Between the SST-11 and SST-12 releases, Intel stopped distributing Pin 2.14, which Balar depends on. As a result, Balar support is limited in SST-12: if the user has a copy of the Pin 2.14 package, that continues to work but users without Pin 2.14 will be unable to run Balar. The SST team is working on a replacement that does not depend on Pin and expects this replacement to be available by SST 13.

NOTE: SST-Core must be built with --disable-mpi and --disable-mem-pools for Balar with GPGPU-Sim to run properly

DEPENDENCIES:

SST-Elements must be configured with PIN Tool Version 2. PIN Tool Version 3 is NOT supported.
CUDA 9.1 must be installed on the system. GPGPU-Sim and Balar do not compile properly with newer versions.
- CUDA Downloads are available here

- Instructions specific to Linux Operating Systems.

1. Clone and Setup GPGPUSIM per these instructions.

2. Ensure that SST-Core has been configured and built with --disable-mpi and --disable-mem-pools

3. Configure SST-Elements to include Pin 2.14, Cuda, and GPGPUSim. Build and install Elements.

NOTE: balar is now included as part of sst-elements

$ cd $SST_ELEMENTS_ROOT
$ ./configure --prefix=$SST_ELEMENTS_HOME --with-sst-core=$SST_CORE_HOME --with-pin=$PIN_HOME --with-cuda=$CUDA_ROOT --with-gpgpusim=$GPGPUSIM_ROOT <other configure optons as desired>
$ make
$ make install

What’s Next…

It is recommended that the user update their login shell scripts to include updated $PATH, $LD_LIBRARY_PATH and $DYLD_LIBRARY_PATH settings.
Refer to the documentation section at sst-simulator.org for more information on SST operation.
Additional external components can be built to provide additional features. Instructions for these additional components are available at Instructions for Additional External SST Components.
Developers and Researchers are encouraged to be part of SST Development. Contact SST Support to be added to the team..
To clone the latest project source code on the devel branch (from GitHub):
- Using Git
  - git clone -b devel https://github.com/sstsimulator/sst-core.git
  - git clone -b devel https://github.com/sstsimulator/sst-elements.git
- The build process is the same as described above, except the user must perform a $ ./autogen.sh to create a configure file. This must occur before running the configure script.
- The source for SST-Core and SST-Elements are stored in two repositories (SST-Core and SST-Elements). Each repository contains two primary development branches (devel and master):
  - The devel branch is under active development.
    - Code is submitted to the devel branch via Pull Requests.
    - The Pull Requests to both repositories are automatically tested (but not exhaustively) before merging. Due to superficial testing of pull requests, it is possible that the code in the devel branch could be non-operational or contain bugs.
  - A full exhaustive test suite is run nightly on the devel branches of SST (Core and Elements). When these tests pass, the devel branches are then merged into the appropriate master branches.
  - The master branch is exhaustively tested and will contain the latest stable version of SST-Core and SST-Elements
    - To retrieve the master branches:
      - git clone -b master https://github.com/sstsimulator/sst-core.git
      - git clone -b master https://github.com/sstsimulator/sst-elements.git

Configuration selection for Internal Elements and Optional/Required External Components

Below is a description of the Elements provided with SST 12.1.x. Most elements are automatically included in the configuration. Some elements are only enabled when the –with-“external component” is set. For more information, see Instructions for Additional External SST Components

HDF5
- Enabled by SST-Core Configure: –with-hdf5=”path to HDF5”
ariel
- Enabled by SST-Elements Configure: –with-pin=”path to Intel Pin”
balar
- Enabled by SST-Core Configure:
  - –disable-mpi
  - –disable-mem-pools
- Enabled by SST-Elements Configure:
  - –with-pin=”path to Intel Pin”
    - This must be Pin 2.14
  - –with-cuda=”path to CUDA compilier”
  - –with-gpgpusim=”path to GPGPUSIM”
cacheTracer
- Always Enabled
cassini
- Always Enabled
Cramsim
- Always Enabled
ember
- Always Enabled
firefly
- Always Enabled
hermes
- Always Enabled
kingsley
- Always Enabled
memHierarchy
- Always Enabled
- Optional Features Enabled by SST-Elements Configure: –with-dramsim=”path to DRAMSim2”
- Optional Features Enabled by SST-Elements Configure: –with-dramsim3=”path to DRAMsim3”
- Optional Features Enabled by SST-Elements Configure: –with-nvdimmsim=”path to NVDimmSim”
- Optional Features Enabled by SST-Elements Configure: –with-hybridsim=”path to HybridSim”
- Optional Features Enabled by SST-Elements Configure: –with-ramulator=”path to Ramulator”
- Optional Features Enabled by SST-Elements Configure: –with-hbmdramsim=”path to HBMDramsim2”
- Optional Features Enabled by SST-Elements Configure: –with-goblin-hmcsim=”path to HMCSim”
merlin
- Always Enabled
Messier
- Always Enabled
miranda
- Always Enabled
- Optional Spike Simulator Support Enabled by SST-Elements Configure: –with-stake=”path to Spike”
prospero
- Always Enabled
rdmaNic
- Always Enabled
Samba
- Always Enabled
shogun
- Always Enabled
simpleElementExample
- Always Enabled
thornhill
- Always Enabled
vanadis
- Always Enabled - Does require musl compiler to build mips/riscv binaries.
VaultSimC
- Always Enabled
zodiac
- Always Enabled