Skip to content

Mac Build Instructions

Jump to bottom
Paul Gilman edited this page Nov 15, 2023 · 42 revisions

These instructions were written and tested in July 2023 on macOS 13.4.1 Ventura using the following:

  • Xcode 14.3.1
  • CMake 3.26.5 (minimum CMake 3.24)
  • wxWidgets 3.2.3
  • GoogleTest 1.14.0
  • Git 2.39.2
  • GNU Make 3.81

Builds should work on computers running macOS 10.15 or later with either Apple Silicon or Intel processors.

Before building SAM, you must build GoogleTest and wxWidgets from source.

Note These instructions place code repositories in your mac's Home directory using the $HOME environment variable. This makes it possible for you to copy and paste commands from the instructions to your Terminal. If you want to use different directories for your installation, replace "$HOME" in the instructions with a different directory path.

Install Xcode Command Line Tools

To install Command Line Tools, open a terminal window, and type the following command:

xcode-select --install

If Command Line Developer tools is not installed, you should see a message asking if you want to install them. Click Install.

Install CMake

The SAM build uses CMAKE to generate makefiles.

  1. Download the appropriate pre-compiled binary distribution appropriate for your Mac and copy CMake.app to the Applications directory.

  2. Add a symbolic link to /usr/local/bin (assuming you copied CMake to your Applications directory) to make CMake available for the command line.

    /Applications/CMake.app/Contents/bin/cmake-gui --install

To see other ways to enable CMake for the command line, in the CMake application, go to Tools, How to Install for Command Line Use.

Install wxWidgets

SAM builds require at least the version of wxWidgets shown above, it may work with more recent versions.

  1. Download source code for macOS 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. Extract the downloaded archive.

    tar xvfj $HOME/Downloads/wxWidgets-3.2.3.tar.bz2 $HOME/

    This example extracts the source code to a wxWidgets-3.2.3 directory in your Home directory, but you can put it in a directory other than your Home directory.

    The $HOME/wxWidgets-3.2.3 directory should contain several files and folders including CMakeLists.txt, README.md, and a build directory.

  3. Go to the build directory.

    cd $HOME/wxWidgets-3.2.3/build

  4. Run configure to generate makefiles.

    ../configure --prefix=$HOME/local/wx-3.2.3/Release --enable-stl=yes --enable-shared=no --disable-debug_flag --with-cocoa --enable-universal_binary=x86_64,arm64 --enable-unicode --enable-webview --disable-mediactrl --with-cxx=11 --with-macosx-version-min=10.15  --with-libjpeg=builtin --with-libpng=builtin --with-regex=builtin --with-libtiff=builtin --with-zlib=builtin --with-expat=builtin

  5. Run make to generate non-source files and install wxWidgets.

    $ make clean
$ make
$ make install

    This installs wxWidgets in ~/local/wx-3.2.3.

    Note. Use make -j'nproc' to run jobs in parallel for a faster build. See this StackExchange discussion for details.

  6. Create a symbolic link to the wxWidgets installation directory so that the SAM build process can find the files it needs.

    ln -s ~/local/wx-3.2.3/Release/bin/wx-config /usr/local/bin/wx-config-3

    Use -sf to overwrite an existing symoblic link.

  7. Test the installation.

    wx-config-3 --cflags

    If the installation was successful, you should see:

    -I/Users/[user]/local/wx-3.2.3/lib/wx/include/osx_cocoa-unicode-static-3.2 -I/Users/[user]/local/wx-3.2.3/include/wx-3.2 -D_FILE_OFFSET_BITS=64 -DwxDEBUG_LEVEL=0 -D__WXMAC__ -D__WXOSX__ -D__WXOSX_COCOA__

Build GoogleTest

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

  1. Clone the GoogleTest repository into a directory of your choice. This example uses the Home directory, but you can choose a different one.

    cd $HOME && git clone https://github.com/google/googletest.git

    This creates the $HOME/googletest directory containing files from the GitHub repository.

  2. Create a directory for the build in the googletest directory.

    cd $HOME/googletest && mkdir build && cd build

  3. Run CMake from the build directory to generate the build files.

    cmake .. -DCMAKE_BUILD_TYPE=Release

  4. Run make to install GoogleTest.

    make

    If the builds succeed, you should see a lib directory in $HOME/googletest/build that contains the libgtest.a file.

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/sam_dev

This example creates the sam_dev directory in your $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/sam_dev.

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

    cd $HOME/sam_dev

  2. Clone the repositories.

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

    This should create four folders in $HOME/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.

Set environment variables

The SAM build process use five environment variables to determine where the files it needs are stored on your computer. Before building SAM, set the following environment variables to point to each of the project folders.

To make these environment variables permanent, set them in your shell startup script ($HOME/.zshrc for zsh on newer macs or $HOME/.bash_profile for sh on older ones) and then close and reopen Terminal to update the environment variables. For example to use the nano text editor to open the shell startup script for zsh: nano $HOME/.zshrc.

export GTEST=$HOME/googletest
export LKDIR=$HOME/sam_dev/lk
export WEXDIR=$HOME/sam_dev/wex
export SSCDIR=$HOME/sam_dev/ssc
export SAMNTDIR=$HOME/sam_dev/SAM
export RAPIDJSONDIR=$HOME/sam_dev/ssc

To verify that the environment variables are set:

printenv

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:

option(SAM_SKIP_TOOLS "Skips the sandbox, sdktool and tcsconsole builds." ON)
option(SAM_SKIP_TESTS "Skips building the SSC Test project." ON)
option(SAMAPI_EXPORT "Build SAM API project to export SSC binaries to the SAM_api directory for PySAM. For Unix, compile ssc libraries for SAM_api." OFF)
option(SAM_SKIP_AUTOGEN "Skips the automatic regeneration of SAM API files from export_config for PySAM." ON)
      
cmake_minimum_required(VERSION 3.19)
      
Project(system_advisor_model VERSION 1.0.0)
      
add_subdirectory(lk)
add_subdirectory(wex)
add_subdirectory(ssc)
add_subdirectory(sam)

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

The build folder contains executable and runtime files generated by the build process.

mkdir -p $HOME/sam_dev/build/Release

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

 mkdir -p $HOME/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 Option 1: Build with make

Build SAM with make to build SAM for your computer's architecture (Intel or Apple).

  1. Run CMake to generate makefiles.

    cd $HOME/sam_dev/build/Release && cmake ../.. -DCMAKE_BUILD_TYPE=Release

    If you are building Release and Debug versions, run CMake again for the Debug version.

    cd $HOME/sam_dev/build/Debug && cmake ../.. -DCMAKE_BUILD_TYPE=Debug

  2. Run make to build SAM.

    make

    If you are building from the Release and Debug directories, run make from each one.

    When the build finishes, you should see SAMOS.app in the $HOME/sam_dev/build/Release/sam directory. For Debug, the SAMOSd.app is in $HOME/sam_dev/build/Debug/sam.

  3. Run SAM.

    open $HOME/sam_dev/build/Release/sam/SAMOS.app

    If you built Release and Debug versions of SAM, run SAMOS.app from .../build/Release/sam, and SAMOSd.app from .../build/Debug/sam.

Build Option 2: Build with XCode IDE

Build SAM in XCode to use the XCode IDE to explore or modify SAM's source code, and to build SAM for both Intel and Apple architectures.

  1. Run CMake to generate an XCode project.

    cd $HOME/sam_dev/build/Release && cmake ../.. -GXcode -T buildsystem=12 -DSAMAPI_EXPORT=0 -DCMAKE_BUILD_TYPE="Release" -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO

    To build a project for debugging, use cd $HOME/sam_dev/build/Debug and set -DCMAKE_BUILD_TYPE="Debug".

    CMake should create a system_advisor_model.xcodeproj file in the $HOME/sam_dev/build/Release directory, and if you built a Debug version, a separate system_advisor_model.xcodeproj file in the $HOME/sam_dev/build/Debug folder.

    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 XCode DerivedData folder before running cmake may prevent link and build errors.

    rm -rf $HOME/Library/Developer/Xcode/DerivedData/

  2. Start XCode and open the system_advisor_model project for either the Release or Debug build.

    open system_advisor_model.xcodeproj

  3. Choose the SAMOS scheme (SAMOSd for Debug builds): Product, Scheme, Choose Scheme, SAMOS.

  4. Choose the Release or Debug build configuration: Product, Scheme, Edit Scheme, Info, Build Configuration, [Debug/Release].

    Be sure to choose the configuration that matches the project: A "Command PhaseScriptExecution failed with a nonzero exit code" error toward the end of the build may indicate that you chose the Debug configuration for the Release project or vice versa.

  5. Build the project: Product, Build.

    The build takes a few minutes. When the build finishes, you should see "Build Succeeded."

  6. Run SAM: Product, Run.

Test the build

The Welcome page of open-source builds of SAM displays "Please setup API keys, see private.h for details...". The private.h file contains credentials for several APIs used by NREL versions of SAM to access online databases such as for weather file downloads. It is not necessary to modifiy private.h to run and test SAM.

  1. When SAM starts, click Start a new project, and then click Photovoltaic (detailed) and Residential (distributed), and OK.

  2. On the Location and Resource page, click View data. That should open a DView window with data from the weather file selected on the Location and Resource page. DView is from WEX, so that confirms that WEX built correctly.

  3. Close the DView window.

  4. Click through the input pages to see that they display correctly. The user interface uses libraries from wxWidgets and WEX.

  5. Click Simulate in the bottom left corner of the SAM window. SAM should run a simulation and display results on the Results page. The results page also uses DView from WEX, and displays data generated by SSC.

  6. Click Macros (under the Simulate button), and click the Inverter Sizing Information button. Click Run macro at the top of the window. The macro should run and display a window with information about the inverter's performance. That confirms that LK (also from WEX) is working.

Clone this wiki locally