Linux Build Instructions

These instructions are for building SAM from source on Linux. They should work for most Linux distributions. NREL has built and tested it on recent versions of Ubuntu, Fedora, and Mint, as well as on Red Hat Enterprise Linux (RHEL) 8.

These instructions assume you are installing the files required for the SAM build in folders in your home directory, but you can install them to any folder that has user access. Where ever you see $HOME/<USERNAME> in a path, replace <USERNAME> with your Linux user name, or replace $HOME/<USERNAME> with the path you are using for the installation.

Requirements

Minimum versions of packages required to build SAM:

gcc 4.8.5
libc 2.17
cmake 3.24
g++
git

SAM's code depends on the following packages:

 libcurl4-openssl-dev
 build-essential
 libgtk2.0-dev
 libgl1-mesa-dev
 mesa-common-dev
 freeglut3-dev

Check a package's version:

<package name> --version

On a Debian-based Linux distribution, install a package with:

sudo apt-get install <package name>

Install CMake

If the version of CMake available from your package manager is older than the required version (see above), download the required version from https://cmake.org/download/.

For step-by-step installation instructions, see for example https://www.linuxfordevices.com/tutorials/install-cmake-on-linux.

Install wxWidgets

SAM's user interface is built from wxWidgets 3.2.6.

Download source code for Linux from https://www.wxwidgets.org/downloads/. If the latest version available for download is newer than the one SAM requires, follow the link under "Other Downloads" at the bottom of the page to find the source code for the older version.
Create a folder like $HOME/<USERNAME>/wxWidgets-3.2.6 and extract the archive to that folder.
```
mkdir $HOME/<USERNAME>/wxWidgets-3.2.6
```

Extract the archive from your Downloads folder to the folder you just created.

cd $HOME/<USERNAME>/wxWidgets-3.2.6

tar xvf $HOME/<USERNAME>/Downloads/wxWidgets-3.2.6.tar.bz2

Create a folder for the release build:
```
cd $HOME/<USERNAME>/wxWidgets-3.2.6
```
```
mkdir release-build
```
If you plan to debug wxWidgets, then you should also create a debug-build folder in this step. A debug version of wxWidgets is not required to debug SAM.

Run the configure script with the following options.

Set the prefix path to the folder to be created where you want wxWidgets libraries to be installed. This is a different folder than the one containing the wxWidgets source code.

cd $HOME/<USERNAME>/wxWidgets-3.2.6/release-build

../configure --prefix=$HOME/<USERNAME>/wx-3.2.6 --enable-shared=no --enable-debug=no --with-gtk=2 --with-libjpeg=builtin --with-libpng=builtin --with-regex=builtin --with-libtiff=builtin --with-zlib=builtin --with-expat=builtin --without-libjbig --without-liblzma --without-gtkprint --with-libnotify=no --with-libmspack=no --with-gnomevfs=no --with-opengl=yes --with-sdl=no --with-cxx=11

If you are also building a debug version of wxWidgets then you should run this command again for the debug-build folder with --enable-debug=yes. This step is not required to debug SAM.

Build wxWidgets:
```
make
```
```
make install
```
When the build finishes, you should see the file wx-config in $HOME/<USERNAME>/wx-3.2.6/bin/.
Create a symbolic link so that CMake can find the correct wxWidgets version to run:
```
sudo ln -s $HOME/<USERNAME>/wx-3.2.6/bin/wx-config /usr/local/bin/wx-config-3
```
Use -sf to overwrite an existing symoblic link.

Alternatively, if you are building on a system where you don't have root access, you can create a system variable for the wxWidgets path instead:
```
export WXMSW3=$HOME/<USERNAME>/wx-3.2.6
```

Test the wxWidgets build:

wx-config-3 --cflags

If the build was successful, you should see something like:

-I/home/wx-3.2.6/lib/wx/include/gtk2-unicode-static-3.2 -I/home/wx-3.2.6/include/wx-3.2 -D_FILE_OFFSET_BITS=64 -DwxDEBUG_LEVEL=0 -D__WXGTK__ -pthread

Build GoogleTest

SAM's repositories contain dependencies on Google's C++ unit-test framework Google Test.

Clone GoogleTest and do an out-of-source build for the Release configuration:

cd $HOME/<USERNAME>

git clone https://github.com/google/googletest.git

cd googletest

mkdir build

cd build

cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-std=c++11

make

If the build succeeds, you should see $HOME/<USERNAME>/googletest/build/lib/libgtest.a.

Create a directory for the SAM source code

SAM's build process assumes that directories for the code repositories are in the same directory.

mkdir $HOME/<USERNAME>/sam_dev

This example creates the sam_dev directory in the /home directory, but you can create it in a different directory or use a different name.

Get code repositories

The four SAM code repositories are on GitHub.com:

Clone each repository into a separate directory in $HOME/<USERNAME>/sam_dev.

Go to the directory you created for the SAM source code.
```
cd $HOME/<USERNAME>/sam_dev
```
Clone the repositories.
```
for repo in lk wex ssc SAM ; do git clone https://github.com/nrel/$repo.git ; done
```
This should create four folders in $HOME/<USERNAME>/sam_dev, each containing files downloaded from GitHub.com.

If you have access to the SAM-private repository and plan to build offical NREL versions of SAM, clone it.
```
git clone https://github.com/NREL/SAM-private.git
```

Depending on NREL's development schedule, by default git clone downloads either the Develop or Patch branch of each repository. The latest code is in the Develop branch. If you are contributing code, you should work with this branch. The code for the most recent version of SAM is in the Patch branch so Develop is likely to be ahead of Patch.

To build a specific version of SAM, you can check out a tag for that version. See List of Tags for SAM Versions for a list of tags for different versions of SAM, SSC, WEX and LK.

Set Environment Variables

The SAM build script uses five environment variables to determine where the files it needs are stored on your computer. Before building the projects, set the following environment variables to point to each of the project folders you created in Step 1.

Name	Value
GTEST	$HOME/googletest/
LKDIR	$HOME/sam_dev/lk/
WEXDIR	$HOME/sam_dev/wex
SSCDIR	$HOME/sam_dev/ssc
SAMNTDIR	$HOME/sam_dev/SAM
RAPIDJSONDIR*	$HOME/sam_dev/ssc
SAMNRELDIR**	$/HOME/sam_dev/SAM-private

*RAPIDJSONDIR is a separate environment variable to make it possible to support builds of WEX that do not depend on SSC.

**SAMNRELDIR is only required if you have access to the SAM-private repository and plan to build official NREL versions of SAM.

You can set these environment variables in your .bashrc file so they are automatically set every time you open a terminal. You can use gedit, nano, or another text editor to open the file:

nano $HOME/.bashrc

And add the following lines to the file:

export GTEST=$HOME/<USERNAME>/googletest
export LKDIR=$HOME/<USERNAME>/sam_dev/lk
export WEXDIR=$HOME/<USERNAME>/sam_dev/wex
export SSCDIR=$HOME/<USERNAME>/sam_dev/ssc
export SAMNTDIR=$HOME/<USERNAME>/sam_dev/SAM
export RAPIDJSONDIR=$HOME/<USERNAME>/sam_dev/ssc
# optional for offical NREL versions of SAM:
export SAMNRELDIR=$HOME/<USERNAME>/sam_dev/SAM-private

Save and close the file, and run the script on the current shell:

source $HOME/.bashrc

Create the SAM CMakeLists.txt file

The CMakeLists.txt file contains instructions for CMake. Use a text editor to create $HOME/sam_dev/CMakeLists.txt and copy the following text into the file and save it:

cmake_minimum_required(VERSION 3.24)

set(CMAKE_OSX_DEPLOYMENT_TARGET "10.15" CACHE STRING "Minimum OS X deployment version")

if (UNIX AND NOT CMAKE_C_COMPILER)
    set(CMAKE_C_COMPILER gcc)
    set(CMAKE_CXX_COMPILER g++)
endif()

if(MSVC)
    set(CMAKE_CONFIGURATION_TYPES "Debug;Release;RelWithDebInfo" CACHE STRING "Debug and Release Builds Configured" FORCE)
endif()

Project(system_advisor_model)

option(SAM_SKIP_TOOLS "Skips the SDKtool and TCSconsole builds" ON)
option(SAM_SKIP_TESTS "Skips building tests" ON)
option(SAMAPI_EXPORT "Exports of ssc binaries to the SAM_api directory; for Unix, also compiles ssc libraries for SAM_api. Required to build PySAM." OFF)
option(SAM_SKIP_AUTOGEN "Skips the generating SAMAPI files from export_config required for PySAM builds." ON) 

add_subdirectory(lk)
add_subdirectory(wex)
add_subdirectory(ssc)
add_subdirectory(SAM)
if (SAMPRIVATE)
    add_subdirectory(SAM-private)
    add_subdirectory(SAM-private/webupd)
endif()

The four CMake options control what projects are included in the build. The default options above are to build SAM without auxiliary tools tcsconsole and SDKtool and without generating files for building the PySAM Python package. To minimize the time it takes for builds and to avoid build errors, use these default options unless you have a reason to change them.

Build an Open Source version of SAM

Create the build folder.
```
cd $HOME/<USERNAME>/sam_dev
```
```
mkdir build
```
If you are building SAM after changing environment variables, making code changes across different repositories, switching between GitHub branches, or other major changes, remove the existing build before starting a new one to prevent linking and build errors.
```
rm -rf build
```

Run CMake to generate project files.

cd $HOME/<USERNAME>/sam_dev/build

cmake .. -DCMAKE_BUILD_TYPE=Release

Run make to build the open source version of SAM.
```
make
```
When the build finishes, there should be an executable SAMOS.bin file and the libssc.so library file in $HOME/<USERNAME>/sam_dev/build/SAM/deploy/linux_64. Depending on your build options, there may also be other files in that folder.

Run the open source version SAM.

Run the following commands to set LD_LIBRARY_PATH so the linker can find shared libraries, set GTK2_RC_FILES for a custom Gtk theme for SAM, and run the executable:

cd $HOME/<USERNAME>/sam_dev/build/SAM/deploy
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/<USERNAME>/sam_dev/build/deploy/linux_64
export GTK2_RC_FILES=home/<USERNAME>/sam_dev/build/deploy/linux_64/GtkTheme/gtk-2.0/gtkrc
exec linux_64/SAMOS.bin

Optional: Create a shell script to run the open source version of SAM

To avoid retyping commands every time you run SAM, create a shell script file named "SAM" with no file extension. Use a text editor to create the script with the following contents (remember to change paths) and save it.

#!/bin/sh
cd $HOME/<USERNAME>/sam_dev/build/SAM/deploy
export LD_LIBRARY_PATH=$HOME/<USERNAME>/sam_dev/build/SAM/deploy/linux_64
export GTK2_RC_FILES=$HOME/<USERNAME>/sam_dev/build/SAM/deploy/linux_64/GtkTheme/gtk-2.0/gtkrc 
exec $HOME/<USERNAME>/sam_dev/build/SAM/deploy/linux_64/SAMOS.bin

The first time you run the script, set access permissions on the file to allow it to run. Once you do this, you can execute SAM by running the script. You do not need to set permissions every time you run the script.

Set execute permissions on the shell script you just wrote:
```
chmod u+x /path/to/SAM
```
Run SAM:
```
cd /path/to/SAM
```
```
./SAM
```

Optional: Build repositories separately

You can build each repository separately if you do not plan to run SAM. For example, you can build the SSC library without building SAM.

Build each project in the following order: LK, WEX, SSC, SAM. To only build WEX, you must build LK first. To only build SSC, you must also build LK and WEX. To build SAM, you must also build LK, WEX, and SSC.

For Release builds:

cd $HOME/<USERNAME>/sam_dev/<project name>

mkdir build

cd build

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

Optional: Build an official NREL version of SAM

If you have access to the SAM-private repository to build official NREL versions, you can build SAM to test features specific to the official version such as weather file downloads and other API integrations, software registration, and updates.

Generate build files for the open source version of SAM and SDKtool with -DSAM_SKIP_TOOLS=0 and build the open source version of SAM. Delete the old build folders first if necessary.
```
rm -rf $SSCDIR/build/sdktool
```
```
cd $HOME/<USERNAME>/sam_dev
```
```
rm -rf build
```
```
mkdir build
```
```
cd build
```
```
cmake .. -DCMAKE_BUILD_TYPE=Release -DSAM_SKIP_TOOLS=0
```
```
make
```
Build SDKtool

The SAM build requires the SDKtool executable. The SDKtool makefile should have been generated in the previous step with the -DSAM_SKIP_TOOLS=0 option.
```
cd $SSCDIR/build/sdktool
```
```
make
```
When the build finishes, you should see the SDKtool executable in $SSCDIR/build/sdktool.

Run the following commands to create build files and targets for LK, WEX, SSC, and SAM.

rm -rf $LKDIR/build && mkdir $LKDIR/build && cd $LKDIR/build && cmake .. -DCMAKE_BUILD_TYPE=Release && cmake --build . -j8 --target lk
rm -rf $WEXDIR/build && mkdir $WEXDIR/build && cd $WEXDIR/build && cmake .. -DCMAKE_BUILD_TYPE=Release && cmake --build . -j8 --target wex
cd $SSCDIR/build && cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=-std=c++11 -DSAMAPI_EXPORT=0 && cmake --build . -j8 --target ssc
rm -rf $SAMNTDIR/build && mkdir $SAMNTDIR/build && cd $SAMNTDIR/build && cmake .. -DCMAKE_BUILD_TYPE=Release -DSAMAPI_EXPORT=0 && make -j8

Because we created a new SSC build folder for SDKtool, we don't want to delete it here.

You can create a shell script to avoid typing those commands each time you create the build files. For example, copy and paste the commands into a text file named "cmake_setup.sh" and then run bash cmake_setup.sh.

Build the executable for an official NREL version of SAM.
```
cd $SAMNRELDIR/build_linux
```
```
make clean
```
```
make setup
```
```
make
```
```
make package
```
When you are prompted for a folder to install the executable, press Enter to use the default path, or type a different path. If you use a path for an existing installation, that intallation will be overwritten.
Run the official NREL version of SAM.
```
cd path/to/installation/folder
```
```
./SAM
```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly