-
Notifications
You must be signed in to change notification settings - Fork 149
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.
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>
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.
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
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
.
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.
The four SAM code repositories are on GitHub.com:
- https://github.com/NREL/SAM/
- https://github.com/NREL/ssc/
- https://github.com/NREL/wex/
- https://github.com/NREL/lk/
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.
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
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 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 thelibssc.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
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
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
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
. -
Set the SAM version number: Use a text editor to open
$SAMNRELDIR/build_linux/Makefile
and setSAMVER
to the version number (yyyy.m.d). -
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