Skip to content

Linux Build Instructions

Jump to bottom
Paul Gilman edited this page Nov 8, 2023 · 83 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>

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

1. Clone the SAM code repositories

The source code for the LK, WEX, SSC, and SAM projects should go in a single parent directory such as sam_dev in these instructions.

The git clone command automatically creates a folder for the repository, so you do not need to create a folder before you clone a repository.

mkdir /home/<USERNAME>/sam_dev

cd /home/<USERNAME>/sam_dev

for repo in lk wex ssc SAM ; do git clone https://github.com/nrel/$repo ; done

Notes.

Linux paths are case sensitive, so be careful to use "SAM" (and "SAM-private" for official NREL builds) for your folder names.

You can also download the repositories from GitHub as .zip files instead of cloning them. If you do that, be sure to extract them into directories named lk, wex, ssc, and SAM so that the makefiles can find them.

The latest code is in the Develop branch of each repository. If you are contributing code, you should work in Develop. 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, you may need to use GitHub CLI (sudo apt install gh) to clone the private repository.

2. Install wxWidgets

SAM's user interface is built from wxWidgets 3.2.3.

  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.3 and extract the archive to that folder.

    mkdir /home/<USERNAME>/wxWidgets-3.2.3

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

    cd /home/<USERNAME>/wxWidgets-3.2.3

    tar cxvfj /home/<USERNAME>/Downloads/wxWidgets-3.2.3.tar.bz2

  4. Create a folder for the release build:

    cd /home/<USERNAME>/wxWidgets-3.2.3

    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.3/release-build

    ../configure --prefix=/home/<USERNAME>/wx-3.2.3 --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.3/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.3/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.3

  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

3. Install GoogleTest

SAM's repositories contain dependencies on the Google Test framework Google Test, which is a C++ unit-test framework.

Clone Google Test 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.

4. 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/<USERNAME>/googletest/
LKDIR /home/<USERNAME>/sam_dev/lk/
WEXDIR /home/<USERNAME>/sam_dev/wex
SSCDIR /home/<USERNAME>/sam_dev/ssc
SAMNTDIR /home/<USERNAME>/sam_dev/SAM
RAPIDJSONDIR* /home/<USERNAME>/sam_dev/ssc
SAMNRELDIR* /home/<USERNAME>/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 are building an official NREL version of SAM from the SAM-private repository.

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

5. Install LK, WEX, SSC, then SAM

There are two build methods:

  1. Create and run an umbrella CMakeLists.txt file to bundle the four projects into one project. This is the best option if you are building an executable version of SAM.

  2. Build each project individually. This is a good option if you only need to build libraries for a single project.

Method 1: Build SAM from an umbrella file

Use a text editor to create a CMakeLists.txt file and put it in /home/<USERNAME>/sam_dev that contains the four folders for the LK, WEX, SSC, and SAM repositories.

The file should contain the following text:

option(SAM_SKIP_TOOLS "Skip generating sdktool" ON)
option(SAM_SKIP_TESTS "Skip building GTest files" ON)
option(SAMAPI_EXPORT "Export SSC binaries to SAM_api folder for PySAM" OFF)
option(SAM_SKIP_AUTOGEN "Skip generating SAMAPI from export_config for PySAM" ON)
option(SAMPRIVATE "Build NREL version of SAM" OFF)

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" CACHE STRING "Debug and Release Builds Configured" FORCE)
endif()

Project(system_advisor_model VERSION 1.0.0)

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 options at the top of the file are set to build an open source version of SAM without optional tools like sdktool and without generating files for PySAM.

cd /home/<USERNAME>/sam_dev

mkdir -p build/Release

cd build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

To build a Debug version, create a build/Debug folder and run CMake with -DCMAKE_BUILD_TYPE=Debug.

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.

To remove the build, delete the build folder:

cd /home/<USERNAME>/sam_dev

rm -r build

To rebuild, remove the build and then repeat the build steps above.

Method 2: Build repositories separately

For each project, in the order LK, WEX, SSC, SAM, do an out-of-source build from the command line for either the Debug or Release configuration:

cd /home/<USERNAME>/sam_dev/<project name>

mkdir -p build/Release

cd build/Release

cmake ../.. -DCMAKE_BUILD_TYPE=Release

make

To make a debug version, create a build/Debug folder and run CMake with "Debug" as the build type.

6. Run SAM

When the SAM 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

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

Write a shell script to run SAM

To avoid retyping these 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, you will need to 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
Clone this wiki locally