Mac Build Instructions

These instructions were written and tested in January 2022 with macOS 11.6.1 on an Intel based Mac and macOS 12.0.1 on an Apple Silicon based Mac, Xcode 13.1 with Command Line Developer Tools. They assume that you have at least installed Command Line Developer Tools on your Mac so that you can compile C++ projects from the command line in a terminal window. See this helpful blog for more about Xcode and Command Line Developer Tools. The builds are performed with OS X 10.15 support using the "-mmacosx-version-min=10.15" in both the CFLAGS and CXXFLAGS.

To install the Command Line Tools package in macOS Sierra, 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: you do not need to get Xcode if you do not want the full Xcode package.

Decide where to store the SAM source code

The SAM project depends on wxWidgets libraries, which you can build in any directory. You will create a symbolic link and change the PATH environment to tell the SAM makefiles where to find the libraries.

The source code for the LK, WEX, SSC, and SAM projects should go in a single parent directory. If you already have a directory for your projects, you can use it, or you can create a new one specifically for SAM. These instructions use the following directory structure as an example:

.../sam_dev/wxWidgets-3.1.5
.../sam_dev/lk
.../sam_dev/wex
.../sam_dev/ssc
.../sam_dev/sam

The lk, wex, ssc, and sam directories should all be in one directory. The wxWidgets directory does not have to be in the same directory as those four.

Get the code repositories

Download the wxWidgets 3.1.5 source code for Linux, OS X, etc. from https://github.com/wxWidgets/wxWidgets/releases/tag/v3.1.5. The code repository is available in several zip formats. These instructions explain how to unzip the following file:
```
wxWidgets-3.1.5.tar.bz2
```
Clone the SAM code repositories:
```
cd sam_dev
for repo in lk wex ssc sam ; do git clone https://github.com/nrel/$repo ; done
```
The latest code is in the Develop branch of each repository. If you are contributing code, you should work with this branch. 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 git clone command automatically creates a directory for the repository, so you do not need to create a directory before you clone it. For example if you clone the lk repository into your sam_dev directory, Git will create an lk directory for the repository.

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

Install wxWidgets 3.1.5

Create a wxWidgets-3.1.5 directory, and extract the compressed file and tarball into it:
```
bunzip2 –d wxWidgets-3.1.5.tar.bz2
tar xvf wxWidgets-3.1.5.tar
```
Note: You may be able to use tar xvjf without first running bunzip2 according to this article on thegeekstuff.

You should now have a directory named wxWidgets-3.1.5 that contains several files and directories:

Go to the build folder and run the configure command (Universal binary library for both Intel and Apple Silicon based Macs):

cd wxWidgets-3.1.5/build
    
    Release version
../configure --prefix=$HOME/local/wx-3.1.5/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

    Debug version
../configure --prefix=$HOME/local/wx-3.1.5/Debug --enable-stl=yes --enable-debug --enable-debug_info --enable-shared=no --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

Type the following make commands to install wxWidgets. The makefile will install wxWidgets in ~/local/wx-3.1.5:
```
make clean
make
make install
```
Note: You can use -j to increase the number of jobs and speed up the build, for example make -j2 or make -j8. See this discussion on Stackexchange.

When the installation finishes, you should see the following message:

Create a symbolic link to the wxWidgets installation directory.

ln -s ~/local/wx-3.1.5/bin/wx-config /usr/local/bin/wx-config-3

Test the installation:

wx-config-3 --cflags

If the installation was successful, you should see:

-I/Users/<USER>/local/wx-3.1.5/lib/wx/include/osx_cocoa-unicode-static-3.1 -I/Users/<USER>/local/wx-3.1.5/include/wx-3.1 -D_FILE_OFFSET_BITS=64 -DwxDEBUG_LEVEL=0 -D__WXMAC__ -D__WXOSX__ -D__WXOSX_COCOA__

Build 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 Debug or Release configuration:

git clone https://github.com/google/googletest.git
mkdir googletest/build
cd googletest/build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j4
rm -rf .
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

If the builds succeed, you should see googletest/build/lib/libgtest<d>.a.

Set Environment Variables

Environment variables store values for programs and processes on your computer. The SAM build script use five environment variables to determine where the files it needs are stored on your computer. Before building the projects, you should set the following environment variables to point to each of the project folders you created in Step 1.

To conveniently set your environment variables to be set every time you open a terminal, set them in your user .bash_profile file:

export GTEST=/path/to/googletest
export LKDIR=/path/to/lk
export WEXDIR=/path/to/wex
export SSCDIR=/path/to/ssc
export SAMNTDIR=/path/to/SAM

Reopen the terminal to update the environment variables.

Build SAM (XCode)

The build requires CMake 3.19 or higher.

In the sam_dev folder, save the following text as CMakeLists.txt:

option(SAM_SKIP_TOOLS "Skips the sdktool and tcsconsole builds" OFF)
option(SAM_SKIP_TESTS "Skips building tests" OFF)
option(SAMAPI_EXPORT "Export of ssc binaries to the SAM_api directory; for Unix, compile ssc libraries for SAM_api" ON)
option(SAM_SKIP_AUTOGEN "Skips the automatic regeneration of SAMAPI files from export_config" 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)

There are four CMake options used for build settings:

SAM_SKIP_TOOLS allows skipping sandboxes and the tcsconsole executables. Off by default.

SAM_SKIP_TESTS allows skipping the Test project in SSC. Off by default.

SAMAPI_EXPORT turns on the SAM api project for producing PySAM files. On by default.

SAM_SKIP_AUTOGEN allows skipping re-generation of the SAM api files. On by default. If you will be making development versions of PySAM, this should be OFF.

Clean previous build (if desired) from the sam_dev folder:
```
rm -rf build
mkdir build
```

Clean the XCode derived data (if desired):

rm -rf /Users/<username>/Library/Developer/Xcode/DerivedData/

Make the "Debug" XCode project (if desired):

mkdir build/Debug && cd build/Debug && cmake ../.. -GXcode -T buildsystem=12 -DSAMAPI_EXPORT=0 -DCMAKE_BUILD_TYPE="Debug" "-DCMAKE_OSX_ARCHITECTURES=x86_64;arm64" -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO

Make the "Release" XCode project:

mkdir build/Release && cd 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

In the sam_dev folder, there should be a build/Debug' and a build/Release` folder if both steps 4 and 5 were completed.
From the desired build folder, e.g. for the Release build sam_dev/build/Release:
```
open system_advisor_model.xcodeproj/
```
Once in XCode, select the desired configuration to build and run. Note that the build/Release folder only contains the Release build and the Debug build will not run in XCode, and vice versa.

Build SAM (Command Line)