Windows Build Instructions

These instructions are for setting up your computer to build the Windows version of SAM from several open source C++ code repositories.

Revised November 2023

Overview

Build Tools

To build SAM, you need to build CMake, wxWidgets, and Google Test:

CMake is a collection of tools for building software: https://cmake.org/.
wxWidgets is a platform for developing user interfaces: https://www.wxwidgets.org.
Google Test is a C++ test framework: https://github.com/google/googletest.

Version Control and Collaboration

SAM's code repositories are stored on GitHub.com, so you need tools for working with Git. These instructions assume you have installed Git and are familiar with it. (See this basic tutorial if you need help using Git for SAM.)

Git is version control and collaboration software: https://git-scm.com/

Source Code

The C++ and other code to build SAM is in the LK, WEX, SSC, and SAM repositories on GitHub.com:

LK is SAM's built-in LK scripting language: https://github.com/nrel/lk.
WEX contains custom user interface enhancements to wxWidgets: https://github.com/nrel/wex.
SSC is code for SAM's performance and financial models: https://github.com/nrel/ssc. (The SSC API and PySAM Python package provide access to SSC for other software applications.)
SAM is the code for SAM's user interface: https://github.com/nrel/SAM.

The SAM-private repository contains code for official NREL versions of SAM. You only need this code if you are working with NREL's SAM software development team to build an official NREL version of SAM.

SAM-private is code for user registration, Welcome page, web API keys, and other features that are part of the official NREL version of SAM: https://github.com/nrel/SAM-private.

Develop and Patch Branches

The Develop branch of each repository contains the latest code. If you are contributing code, you should work from this branch.

The Patch branch of each repository is active during an update period of a few months after the release of a new version of SAM. During this period, if you are contributing code for an update to the current version, you should work from the Patch branch. (When your work is complete and approved, you should merge the Patch branch into Develop.)

The default branch on GitHub.com is Develop except during update periods, when the default is set to Patch.

Tags for SAM Versions

To build a specific version of SAM, you can check out a tag for that version. See this list of tags for different versions of SAM, SSC, WEX and LK.

Overall Build Steps

The entire setup and build process should take between one and two hours, depending on the options you choose for each step and your internet download speed. Once your computer is set up, it takes several minutes to build SAM for the first time. Subsequent builds are faster depending on your build options and how much code you modify before building.

Download and install Visual Studio Community 2022. (10 minutes, requires Microsoft account and computer restart)
Download and build wxWidgets 3.2.6. (10 minutes)
Download and install CMake 3.24 or higher. (5 minutes)
Clone and build Google Test (requires CMake). (5 minutes)
Clone SAM code repositories. (10-20 minutes, depending on internet speed)
Set environment variables. (5 minutes)
Generate SAM project files for Visual Studio (requires CMake). (5 minutes)
Build SAM. (10 minutes for clean build of SAMOS, longer to build all projects.)
Test the build.

1. Download and Install Visual Studio Community 2022

If you do not have Visual Studio Community 2022 (VS 2022) installed on your computer, download it from https://visualstudio.microsoft.com/.

Using VS 2022 requires a free Microsoft account, which you will be prompted to create or enter when you first start the program.

Run the Visual Studio installer and select the following three workloads:
- Desktop development with C++
- Python development (for SAM's integration with Python)
- Linux and embedded development with C++ (for CMake)
If you have a different version of Visual Studio installed on your computer, you can install and run VS 2022 side-by-side with the other version.
Start VS 2022 and sign in to your Microsoft account or create one.

2. Download and Build wxWidgets 3.2.6

SAM's user interface uses wxWidgets 3.2.6, the latest stable release as of September 9, 2024. Other versions of wxWidgets may or may not work with SAM. Links for downloading different versions of wxWidgets are at https://www.wxwidgets.org/downloads/ with older versions available from the GitHub Release Archive listed under "Other Downloads" at the bottom of the page.

Download the Windows source code either as a ZIP or 7Z file for Version 3.2.6 from https://github.com/wxWidgets/wxWidgets/releases/tag/v3.2.6, and extract the files to a folder on your computer, for example c:/wxWidgets-3.2.6.
Start VS 2022 and open the c:/wxWidgets-3.2.6/build/msw/wx_vc17.sln solution file. There are project files for other versions of Visual Studio, so be sure to open the vc17 file. The vc17 solution is for VS 2022.
Build a 64-bit Release version: In the VS 2022 toolbar, choose the Release configuration and the x64 platform, and then either press the F7 key, or choose Build Solution from the Build menu.
When the build completes, choose Debug x64 and build it. In Windows, you must build a Debug version of WxWidgets to debug SAM itself.

If the builds succeed, you should see a message that the build for 24 projects succeeded. You should also see vc_x64-mswu (and vc_x64-mswud if you built Debug) folders in c:/wxWidgets-3.2.6/build/msw, each containing several folders and .pch files.

3. Download and Install CMake

SAM requires CMake 3.24 or higher to generate build files for Windows, Linux, and Mac.

Download the Windows x64 installer for the latest release of CMake from https://cmake.org/download/.
Run the installer and follow the prompts to install CMake, and check the Add CMake to the System Path for … option for either a single user or all users.

The installer should automatically add C:/Program Files/CMake/bin to the Windows system path. To verify, type "env" in the Windows Start menu, open the Environment Variables window, and double click the Path variable under System variables. You can add the path manually if it is not in the Path list.

4. Clone and Build Google Test

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

Clone Google Test from https://github.com/google/googletest.git. From a command window:
```
cd path/to/my/repos
```
```
git clone https://github.com/google/googletest.git
```
Until issue issue https://github.com/NREL/ssc/issues/806 is resolved, check out commit b85864c64758dec007208e56af933fc3f52044ee:
```
cd path/to/googletest
```
```
git checkout b85864c
```
This should result in HEAD is now at b85864c6 Eliminate the legacy GTEST_COMPILE_ASSERT_ macro.
Go to the top-level googletest folder that contains ci, docs, googlemock andgoogletest, and create a build folder:
```
mkdir path/to/googletest/build
```
Go to the build folder that you just created:
```
cd path/to/googletest/build
```
Run CMake to generate Visual Studio project files:

Note the two periods .. at the end of the CMake command to ensure the command finds the CmakeLists.txt file in the parent folder.
```
cmake -G "Visual Studio 17 2022" -DCMAKE_CONFIGURATION_TYPES="Release;Debug" -Dgtest_force_shared_crt=ON ..
```
If CMake succeeds, you should see the path/to/googletest/build/googletest/gtest.sln file.
In VS 2022, open the gtest.sln file and build x64 Debug and Release configurations.

If the builds succeed, you should see Release and Debug folders in path/to/googletest/build/lib that contain gtest.lib among other files.

5. Clone SAM Code Repositories

Create a parent folder to store the repositories, for example path/to/sam_dev:
```
mkdir path/to/sam_dev
```

Clone each repository into the parent folder.

cd path/to/sam_dev

git clone https://github.com/nrel/lk.git

git clone https://github.com/nrel/wex.git

git clone https://github.com/nrel/ssc.git

git clone https://github.com/nrel/SAM.git

If you have access to the SAM-private repository to build official NREL versions of SAM. Choose the web browser authentication method to verify that your GitHub.com account has access to the repository:

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

6. Set Environment Variables

SAM's build tools use Windows environment variables to determine where the files it needs are stored on your computer.

Close any open Command windows and VS 2022 if it is running.
Open the Windows System Properties window, and on the Advanced tab, click Environment Variables, or type "env" in the Windows search bar and click Edit the system environment variables.
Under the user variables list, click New, and type values for the variable name and value for each item in the table below.

For example, if you put the LK repository in c:/sam_dev/lk, you would set the environment variable's name to "LKDIR" and its value to "c:/sam_dev/lk" (you do not need to type the quotes).

LKDIR path/to/sam_dev/lk

WEXDIR path/to/sam_dev/wex

SSCDIR path/to/sam_dev/ssc

SAMNTDIR path/to/sam_dev/SAM

RAPIDJSONDIR* path/to/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 to build official NREL versions of SAM:

SAMNRELDIR path/to/sam_dev/SAM-private
Create the following user variables to point to the Google Test, wxWidgets and CMake folders:

GTDIR path/to/googletest

WXMSW3 path/to/wxWidgets-3.2.6

CMAKEBUILDDIR path/to/sam_dev/build
Close the System Properties window.
You may need to restart your computer at this point to avoid CMake errors in the next step.

7. Generate SAM VS 2022 Project Files

This step is required the first time you build SAM, and after adding or removing .cpp source files from the LK, WEX, SSC, or SAM repositories.

Use a text editor to create an "umbrella CMake file" named CMakeLists.txt in the SAM parent folder (path/to/sam_dev/CMakeLists.txt in our example) with the following contents:

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)

option(SAMPRIVATE "Release build of SAM" OFF)

add_subdirectory(lk)
add_subdirectory(wex)
add_subdirectory(ssc)
add_subdirectory(sam)
if (SAMPRIVATE)
    add_subdirectory(SAM-private)
    add_subdirectory(SAM-private/webupd)
endif()

Note. If you need to build a Release version with debugging information to help with troubleshooting the Release version, add the RelWithDebInfo configuration type: set(CMAKE_CONFIGURATION_TYPES "Debug;Release;RelWithDebInfo" CACHE STRING "Debug and Release Builds Configured" FORCE).

Open a terminal window, and create a folder named build in the SAM parent folder (path/to/sam_dev/build).
```
cd path/to/sam_dev
```
```
mkdir build
```
If this is not your first time building SAM and you want to remove an older build (it is not necessary to remove the older build unless you are having problems building or after re-running cmake because you added .cpp files to one of the repositories):
```
cd path/to/sam_dev
```
```
rmdir /Q/S build
```
```
mkdir build
```
You should now have a directory structure for SAM that looks like this (for our example, this would be the contents of path/to/sam_dev):
```
build
lk
SAM
ssc
wex
CMakeLists.txt
```
Go to the build folder you created above.
```
cd path/to/sam_dev/build
```
Run CMake to generate the Visual Studio solution and project files. This command builds Debug and Release files for the open source version of SAM, which is all you need for most development tasks. To build the official NREL version of SAM, and/or to generate API files for PySAM, choose the appropriate CMake options described below.

Note the two periods .. at the end of the CMake command to ensure the command runs the CmakeLists.txt file you created in the parent folder:
```
cmake -G "Visual Studio 17 2022" -DCMAKE_CONFIGURATION_TYPES="Debug;Release"  -DSAM_SKIP_AUTOGEN=1 -DSAMAPI_EXPORT=0 -DSAMPRIVATE=0 -DCMAKE_SYSTEM_VERSION=10.0 ..
```
Note If your CMakeLists.txt file sets the RelWithDebInfo configuration type, be sure to also include it in your cmake command here: -DCMAKE_CONFIGURATION_TYPES="Debug;Release;RelWithDebInfo".

When CMake finishes, you should see the system_advisor_model.sln Visual Studio solution file with supporting files, Debug and Release folders, and a folder each for SAM, SSC, WEX, and LK among other files and folders in the path/to/sam_dev/build/ folder.

If you get build errors about missing files, check the environment variables to makes sure they are correctly named and point to the correct folders.
CMake Options

Note the letter "D" precedes each option in the cmake command.
- CMAKE_CONFIGURATION_TYPES
  
  Options to build debug, release, or both versions.
```
"Debug" = build files for a debug version. Choose this option if you plan to use VS 2022 debug tools.
"Release" = build files for a release version. Choose this option to run SAM without using VS 2022 debug tools.
"Debug;Release" = build files for both debug and release versions.
```
- SAM_SKIP_AUTOGEN
  
  Skip automatic regeneration of SAMAPI files from export_config. SAMAPI files are for the PySAM Python package.
```
1 = skip generation of SAMAPI files. Use this option for faster build times when you do not need to generate SAMAPI files.
0 = regenerate files. Use this option if you are committing code to the Develop or Patch branch of SSC that adds, removes, or modifies input or output variables, or adds or removes compute modules. 
```
- SAMAPI_EXPORT
  
  Export SSC binaries to the SAM_api folder. These files are for the PySAM Python package. (Unix also compiles libraries for SAM_API).
```
1 = export binaries. Use this option if you are committing code to the Develop or Patch branch of SSC that adds, removes, or modifies input or output variables, or adds or removes compute modules.
0 = no export. Use this option for faster build times when you do not need to build files for PySAM.
```
- SAMPRIVATE
  
  Build solution file for official NREL release version of SAM.
```
1 = include private (SAM) and open source (SAMOS) projects in the solution. Use this option if you are building an official NREL release and have access to the private SAM-private repository.
0 = include only the open source (SAMOS) project in the solution. Use this option if you are building an open source version of SAM.
```
- CMAKE_SYSTEM_VERSION CMake version number.
(Optional, but recommended): Add an .editorconfig file to the path/to/sam_dev folder to ensure your code is formatted consistently with project standards.

8. Build SAM

Start VS 2022 and open the system_advisor_model.sln solution file from Step 7 above.
In most cases, you only need to build the SAMOS project:
- Choose the SAMOS project in the Solution Explorer. (Press Ctrl+; to display the Solution Explorer if you don't see it.)
- Choose Release or Debug from the toolbar at the top of the window. (If you included the "RelWithDebInfo" configuration type when you generated the project above, there should also be an option for RelWithDebInfo.)
- Choose Build SAMOS from the Build menu (or press Ctrl+B). This builds an executable version of SAM from the SAM, SSC, WEX, and LK and other dependent projects.

Building all of the projects in the solution takes more time than just building SAMOS, creates executables for SDKtool and TCSconsole, and generates and a large number of API files for PySAM that you may not need.

If you have access to the SAM-private repository to build official NREL versions of SAM and used the SAMPRIVATE = 1 option in the cmake command above, there will be two SAM projects: SAMOS is the open source version of SAM, and SAM is the official NREL version of SAM. Build SAM to test features specific to the official version such as weather file downloads and other API integrations, software registration, and updates.

The official version (SAM) requires a registration key to run, and includes features such as downloads from the SAM user interface for NSRDB weather files, URDB electricity rate data, and Cambium market price data.
The open source version (SAMOS) runs without a registration key. The download features only work in SAMOS if you modify path/to/samdev/SAM/src/private.h to add valid API keys.

By default, the VS 2022 startup project is set to ALL_BUILD. If you want to run SAM from VS 2022 from the Debug menu or by pressing Ctrl+F5 or F5 without building extra projects that are not necessary to run SAM, you can change the startup project to SAMOS (or SAM for the official NREL version of SAM). To change the startup project, right-click the project name (SAMOS or SAM) in the Solution Explorer and click Set as Startup Project.

If your code contribution involves adding or changing default values of inputs, you should include export_config and SAM_api in your builds to update the default values in files for PySAM. This requires -DSAM_SKIP_AUTOGEN=0 and -DSAMAPI_EXPORT=1 in your cmake command above so that the projects are available in your Visual Studio solution. You only need to build a Release version for this to avoid conflicts when both jobs try to run simultaneously. (Building Debug and Release versions is redundant for this purpose, there is no export_configd.exe, for example.)

You can also use batch build to choose what projects to build: On the Build menu, click Batch Build.

The build process creates files in the following folders:

For open-source builds, the SAMOS executable SAMOS.exe and supporting files are in path/to/sam_dev/SAM/deploy/x64. This folder contains dependent libraries, including a copy of SSC library files. This makes it possible to test SAM with runtime files from the runtime/, libraries/ and weather file folders from the SAM code repository to facilitate source control.
For official NREL builds, the SAM executable SAM.exe and supporting files are in path/to/sam_dev/SAM-private/build_windows/deploy/x64. The runtime files in the deploy folder for these builds are copies from the code repository, so any changes to those files should be made on the originals in the SAM and SAM-Private repositories, and require rebuilding SAM to test.
SSC library files are in path/to/sam_dev/build/ssc/ssc/[Release/Debug/RelWithDebInfo].

9. Test the Build

After you have built the solution, test the build by starting SAM and running a simulation. The executable file depends on the version you built:
- For the open source version of SAM, go to path/to/sam_dev/SAM/deploy/x64 and run SAMOS.exe.
- For the official NREL version of SAM, go to path/to/sam_dev/SAM-private/build_windows/deploy/x64, and run SAM.exe.
- Debug versions are in the same folders, but have "d" in the file name: SAMOSd.exe and SAMd.exe.
You can also start SAM from the VS 2022 Debug menu.
To test basic functionality:

After SAM starts, on SAM's Welcome page, click Start a new project.

Choose Photovoltaic, Detailed PV Model and Distributed, Residential Owner.

Click Simulate at the bottom left of the SAM window. SAM should run a simulation and display results.

Click Macros under the Simulate button, click one of the macro names, and click Run macro or View code. The macro should and you should see the macro code, indicating that LK built correctly.

On the Location and Resource page, click View data. A DView window should open indicating that the WEX project DView built correctly. (SAM also uses DView to display data on the Results page.)

If you are testing an official NREL version, test the download features on the Location and Resource and Electricity Rates pages.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly