Skip to content

Windows Build Instructions

Jump to bottom
dguittet edited this page Aug 28, 2018 · 16 revisions

SAM Build Instructions for Windows

These instructions are for building SAM for Windows with Microsoft Visual Studio Community 2017 (VS 2017) from the C++ source code.

1. Install Visual Studio Community 2017

If you have a different version of Visual Studio installed on your computer, you can install and run VS 2017 side-by-side with the other version.

If you do not have VS 2017 installed on your computer, you can download it from https://www.visualstudio.com/downloads/. Using VS 2017 requires a free Microsoft account, which you will be prompted to create or enter when you first start the program.

2. Build wxWidgets 3.1.1

SAM's user interface uses wxWidgets 3.1.1. You will need to download Windows source code (as either a ZIP or 7Z file) for Version 3.1.1 from https://www.wxwidgets.org/downloads/.

  1. Start VS 2017.

  2. Open the build/msw/wx_vc14.sln Visual Studio Solution file in the folder where you extracted the wxWidgets 3.1.1 files. There are project files for other versions of Visual Studio, so be sure to open the vc14 file.

  3. Build Debug and Release configurations for both 32-bit and 64-bit platforms: In the VS 2017 toolbar, choose the configuration and platform, and then either press the F7 key, or choose Build Solution from the Build menu.

Note. If you only plan to build SAM for one platform, and do not plan to use Visual Studio for debugging, then you can just build a single release version to save time, for example, the Release configuration and 64-bit platform.

If a build fails, you may need to "retarget" the solution by right-clicking the solution name in the Solution Explorer and choosing Retarget solution from the shortcut menu (or from the Project menu).

If the builds succeed, you should see one or all of the following folders in the wxWidgets-3.1.1/build/msw folder, each containing several folders and a handful of .pch files:

vc_mswu (release win32)
vc_mswud (debug win32)
vc_x64_mswu (release x64)
vc_x64_mswud (debug x64)

3. Build Google Test

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

  1. Clone Google Test: git clone https://github.com/google/googletest.git

  2. Start VS 2017.

  3. Open the googletest/googletest/msvc/2010/gtest-md.sln Visual Studio Solution file from the folder where you cloned Google Test. Accept any upgrades that Visual Studio does to the project.

  4. Build Debug and Release configurations for both 32-bit and 64-bit platforms: In the VS 2017 toolbar, choose the configuration and platform, and then either press the F7 key, or choose Build Solution from the Build menu.

Note. If you only plan to build SAM for one platform, and do not plan to use Visual Studio for debugging, then you can just build a single version to save time, for example, the Release configuration and 64-bit platform.

If the builds succeed, you should see one or all of the following folders in the googletest/googletest/msvc/2010/gtest-md folder, each containing a gtest.lib and other build outputs:

Win32-Debug
Win32-Release
x64-Debug
x64-Release

4. Clone or Download the Code Repositories

If you plan to contribute code to the repositories, use GitHub to clone the repositories to your computer. If you want to build your own versions of the software without contributing code, or just want to examine the source code, you can either clone the repositories using GitHub, or download zip files of the repositories and extract them instead.

The repositories required to build SAM are:

For these instructions, we put those four repositories in separate folders named, lk, wex, ssc, and sam in a single parent folder called sam_dev. The build tools use the enviroment variables we set in the next step to find these folders, so you can organize them differently if you want. Be sure that you have both read and write permissions to the folders you use.

sam_dev/lk
sam_dev/wex
sam_dev/ssc
sam_dev/sam

5. Set Environment Variables

Environment variables store values for programs and processes on your computer. SAM's build tools use six 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 2, 3, and 4.

Name Value (Folder Path)
WXMSW3 wxWidgets 3.1.1
GTEST googletest/googletest (look for folder with LICENSE file)
LKDIR sam_dev/lk
WEXDIR sam_dev/wex
SSCDIR sam_dev/ssc
SAMNTDIR sam_dev/sam

Set the environment variables by hand:

  1. If Visual Studio is running, close it.

  2. Use Windows to search for "Environment Variables," and open the System Properties window.

  3. On the Advanced tab, click Environment Variables. The Environment Variables window shows two lists, one for user variables and one for system variables.

  4. Under the user variables list, click New, and type values for the variable name and value. For example, if you put the LK repository in F:\sam_dev\lk, you would set the environment variable's name to "LKDIR" and its value to "F:\sam_dev\lk" (you do not need to type the quotes).

Use a batch file to set the environment variables:

If you build different branches of SAM on a regular basis, you can use a batch file to set environment variable values before you build each branch. For example, you could create a text file named set_env.bat in the F:\SAM_dev folder that contains:

REM wxWidgets-3.1.1 installation folder
setx WXMSW3 C:\wxWidgets-3.1.1
setx GTEST C:\googletest\googletest

REM LK, WEX, SSC and SAM folders
setx LKDIR F:\sam_dev\my_branch\lk\
setx WEXDIR F:\sam_dev\my_branch\wex\
setx SSCDIR F:\sam_dev\my_branch\ssc\
setx SAMNTDIR F:\sam_dev\my_branch\sam\

Then from a Command window, navigate to the F:\sam_dev folder, type set_env and press Enter to automatically create the variables and set their values.

6. Build the projects

For each of the four projects, use VS 2017 to open the solution file (.sln) and build Debug and Release configurations for both 32-bit and 64-bit platforms (or for a single configuration and platform to save time) as you did for wxWidgets. Build the projects in the following order:

  1. lk/build_vs2017/lk_vc14.sln
  2. wex/build_vs2017/wex_vc14.sln
  3. ssc/build_vs2017/ssc_vs2017.sln
  4. sam/build_vs2017/SAMnt_vs2017.sln

The build order is important because of dependencies between the projects, and because the SAM build process copies libcurl library files from the WEX folder to the SAM folder.

If you make changes to a project and are rebuilding it to compile your code, you can skip the preceding project if you did not change it. For example, if you build all four projects, and then make a modification to code in SSC, you only need to build SSC and SAM to build SAM with your changes.

Note. 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. When building LK, WEX or SAM, errors about missing wx/<filename>.h files may indicate that wxWidgets has not been built for the combination of configuration and platform that you are trying to build. For example, if you are building a debug/win32 version of LK and see the messages, you need to first build a debug/win32 version of wxWidgets.

Step-by-step instructions for building SAM in VS 2017

  1. On the File menu, click Open, Project/Solution to open the .sln file for the LK project.

  2. In the toolbar at the top of the Window, choose Debug and Win32 to build the Debug configuration for the 32-bit platform. If you are building a single configuration and platform to save time, choose the Release configuation for your platform (Win32 or x64).

  3. On the Build menu, click Build Solution, or press the F7 key.

  4. The console at the bottom of the window shows you the status of the build. When the build finishes, you should see a message like "Build: 2 succeeded, 0 failed, 0 skipped." You can ignore warnings. Errors will prevent the build from succeeding.

  5. When the build is complete, repeat Steps 2-4 to build Debug and Release configurations for the Win32 and x64 platforms, or skip this step if you are making a single build.

  6. Close the solution, and open the next one (WEX, SSC, SAM), and repeat Steps 1-5 until you have built all four projects.

6. Test the build

After you have built the four projects, test the build by starting SAM and running a simulation.

  1. In the SAM folder, go to deploy\win32 or deploy\x64, and run sam.exe.

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

  3. Choose Photovoltaic (detailed) and Residential (distributed).

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

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

  6. 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.)

Clone this wiki locally