Skip to content

Linux Build Instructions

Jump to bottom
Paul Gilman edited this page Nov 12, 2024 · 88 revisions

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.

  1. 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.

  2. Create a folder like /home/<USERNAME>/wxWidgets-3.2.6 and extract the archive to that folder.

    mkdir /home/<USERNAME>/wxWidgets-3.2.6

  3. 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

  4. 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.

  5. 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.

  6. Build wxWidgets:

    make

    make install

    When the build finishes, you should see the file wx-config in /home/<USERNAME>/wx-3.2.6/bin/.

  7. 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

  8. Test the wxWidgets build:

    wx-config-3 --cflags

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

    -I/home/wx-3.2.0/lib/wx/include/gtk2-unicode-static-3.1 -I/home/wx-3.2.0/include/wx-3.1 -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.

  1. Go to the directory you created for the SAM source code.

    cd /home/<USERNAME>/sam_dev

  2. 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.

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.

If you have access to the SAM-private repository to build offical NREL versions of SAM, clone it. You may need to use GitHub CLI (sudo apt install gh) to clone the private repository.

git clone https://github.com/NREL/SAM-private.git

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

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

If you have access to the SAM-private repository and plan to build official NREL versions of SAM, set the environment variable for SAM-private:

export SAMNRELDIR=/home/<USERNAME>/sam_dev/SAM-private

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.

Create build folder

mkdir -p /home/<USERNAME>/sam_dev/build/Release

If you plan to debug SAM, create a separate folder for a Debug version

mkdir -p /home/<USERNAME>/sam_dev/build/Debug

If you are building SAM after changing environment variables, making code changes across different repositories, switching between GitHub branches, or other major changes, removing the existing build before starting a new one may prevent link and build errors.

rm -rf $HOME/sam_dev/build

Build an Open Source version of SAM

For a Release build:

cd /home/<USERNAME>/sam_dev/build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

For a Debug build, use cd /home/<USERNAME>/sam_dev/build/Debug and set -DCMAKE_BUILD_TYPE=Debug.

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.

To run SAM, execute the SAMOS.bin file. Before you execute the file, set LD_LIBRARY_PATH so the linker can find shared libraries, and use GTK2_RC_FILES to set a custom Gtk theme for SAM:

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

Write a shell script to run 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 and save it in /home/<USERNAME>/sam_dev/SAM/build/deploy with the following contents (remember to change the paths as appropriate):

#!/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 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.

  1. Set execute permissions on the shell script you just wrote:
cd /home/<USERNAME>/sam_dev/build/SAM/deploy
chmod u+x SAM
  1. Run SAM:
cd /home/<USERNAME>/sam_dev/SAM/build/deploy
./SAM

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 -p build/Release

cd build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

For Debug builds, use cd /home/<USERNAME>/sam_dev/<project name>/build/Debug and and set -DCMAKE_BUILD_TYPE=Debug.

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.

  1. Build the open source version of SAM.
cd /home/<USERNAME>/sam_dev/build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make
  1. Build SDKtool
cd /home/<USERNAME>/sam_dev/ssc

mkdir -p build/Release

cd build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

To build an official NREL version of SAM, you must have the /home/<USERNAME>/sam_dev/SAM-private repository, and set the SAMPRIVATE option in the CMakeLists.txt file to ON.

If you build the official NREL version of SAM, its executable is /home/<USERNAME>/sam_dev/build/SAM-private/deploy/linux_64/SAM.bin.

Build SDKtool ssc/build

build_linux make clean make setup make -j8 make package

Clone this wiki locally