CMake on Windows, Linux, and MacOS X Operating Systems

...

 The first two three steps are generally "one-time" processes and result in a build system (e.g. Visual Studio solution or makefiles) that will intelligently rebuild GMAT components as needed when source or configuration files are changed. NOTE: These instructions refer to <GMAT> as the top-level GMAT repository folder.

Figure 1. The <GMAT> repository layout

Step 1: Clone the GMAT Git Repositories

GMAT uses to Git repositories for source code version control.  The "Public" repository contains code that has been approved for general open source release.  The internal repository contains proprietary and/or sensitive components that cannot be released open source.  For public developers, you can obtain the source code from SourceForge ( The Git command is: "git clone sshhttps://YOURUSERNAME@gitgit.code.sf.net/p/gmat/git gmat-git"). For internal developers, contact the GMAT team for repository URLs.  

...

GMAT is distributed with a Python script to configure most (but not all) dependencies.  Table 1 describes all software dependencies for GMAT.  The <GMAT>/depends folder contains scripts to automatically download and configure the core GMAT dependencies.  Note, to build without MATLAB or Python (or other non-Core dependencies), you can simply uncheck the plugins that require those dependencies later in the CMAKE configuration (see the "Used in GMAT" column in the table below).  Core dependencies are required to build even the minimal GMAT distribution.

...

• Windows: Visual Studio 2017 (Express or Paid versions). 
• Mac: XCode tools (preferably v7+), with the command line developer tools (GCC  4.8.5 or greater)
  
• Linux: GCC compiler tools (GCC  4.8.5 or greater)
  

Figure 2. <GMAT>/depends folder layout after dependency configuration

→ (For GMAT R2018a and earlier) Run the configure.sh (Mac/Linux) or configure.bat (Windows) script to set up core GMAT dependencies.

...

CSALT requires installation of the code and build files for two additional third-party components: Boost (code only) and SNOPT (code and libraries).  The Boost code is downloaded automatically as part of the CMAKE configuration process. (See Step 3 of this guide.)  The SNOPT code and libraries should be placed in a folder named snopt7.  The dependency folder ("depends"), configured to include the CSALT dependencies, is shown in Figure 3. Note that some of the items in the depends folder do not appear until either (1) the configure.py script is run or (2) the CMAKE configuration process is run. (See Step 3 of this guide.)

Figure 3. <GMAT>/depends folder layout, including the folders for CSALT builds

When the Boost and SNOPT folders are configured correctly, the code for the corresponding components should be directly inside of the Boost_1_71_0 and snopt7 folders, as shown in Figure 4.

Figure 4. A view showing contents of the boost and part of the snopt7 folders

SNOPT Setup

CSALT is built to use SNOPT 7.5.  Civil servant members of the GMAT development team can obtain a copy of the SNOPT code from the GMAT Project lead.  Subcontractors should obtain a copy from their company GMAT point of contact.  Other GMAT developers should contact Stanford Business Software, Inc. (SBS) for a licensed copy of the software package.  Setup for the SNOPT package is different for developers that have access to the code from the GMAT project than for developers that are using code from SBS. 

...

Tip: All CMake commands can also be performed on the command-line instead of using the GUI. See below for instructions.

Figure 5. Components of the CMake GUI

→ Enter values into the CMake GUI in the following order (as annotated in Figure 5):

1. Enter the full path to the <GMAT> cloned repository on your computer
2. Enter the full path to the folder where the GMAT build system should be placed
   1. CMake produces out-of-source builds. It is recommended to use <GMAT>/build/<OS>-cmakebuild for this value.
3. Click "Configure"
   1. CMake may ask for permission to create the folder you specified in Step 2 ("Where to build the binaries")
   2. CMake will ask you to choose a generator (see Figure 6). See the CMake Generator webpage for an explanation of available generators.
      Recommended generators are:
      1. Mac: Unix Makefiles (although XCode has also been observed to work)
      2. Linux: Unix Makefiles
      3. Windows: Visual Studio (note e.g. "Visual Studio 12 2013" is 32-bit, whereas "Visual Studio 12 2013 x64" is 64-bit)
         

         Figure 6. Choosing a generator in CMake

         
         

   3. CMake will start the configuration process, after which the Variable List and Configure Results sections (Figure 5 sections 4a and 4b) will be populated:
      

      Figure 7. Output of CMake Configure

      
      

4. Use the Configure results output box (Figure 3 section 4a) to change variables in the CMake variable list (Figure 3 section 4b) as follows:

   1. Always start at the top of the configure results output box and correct errors one-by-one
   2. For each error: change the appropriate CMake variable, re-configure, confirm the error was fixed (in the results output box), then repeat for next error

   3. In addition to errors, there are several CMake variables that allow you to control how the build system configures GMAT:

      CMake Variable (Group)	Description	Associated CMake Error
      CMAKE_BUILD_TYPE (CMAKE)	On makefile systems, this specifies the desired build type On VisualStudio/XCode systems, this specifies all possible build types Valid values: Release, Debug, RelWithDebInfo, MinSizeRel Note: On makefile systems, you should create a separate out-of-source build folder for each desired build type (Figure 3 box 2). (e.g. cmakebuild-release or cmakebuild-debug)	N/A
      CMAKE_INSTALL_PREFIX (CMAKE)	Location to install GMAT when doing make install or building the VisualStudio->INSTALL project  Note: This is autofilled to <GMAT>/GMAT-<release>-<OS>-<BitType> for convenience.  Note libraries are only placed here when building AND installing.  Note this directory must be different than "Where to build the binaries", and the target of GMAT_BUILDOUTPUT_DIRECTORY.	N/A
      CSPICE_DIR (Ungrouped)	Path to CSPICE root directory (containing include/, lib/, etc.)	CSPICE NOT FOUND (make sure to run depends script from Step 1)
      F2C_DIR (Ungrouped)	Path to F2C root directory (containing f2c.h)  Note: this should generally be CSPICE_DIR/include	F2C NOT FOUND (make sure to run depends script from Step 1)
      GMAT_ADDITIONAL_PLUGINS (GMAT)	Full path to a text file containing locations of additional (i.e. 3rd-party) GMAT plugins. The file contents should follow the following format:  Plugin1Name = /full/path/to/Plugin1/folder  Plugin2Name = ./relative/path/to/Plugin2/folder Where the plugin name is whatever you want (usually the plugin's common name) and relative paths are with respect to the file location.	N/A
      GMAT_BUILDOUTPUT_DIRECTORY (GMAT)	Location to place libraries and executables when building but NOT installing.   Note this directory must be different than "Where to build the binaries", and the target of CMAKE_INSTALL_PREFIX.
      GMAT_PROPRIETARYPLUGINS_PATH (GMAT)	Full path to the top-level GMAT Proprietary Plugins code/ folder. (folder that contains CMakeLists.txt) This will be automatically found if you name it gmatinternal-git and place it next to the main <GMAT> repository folder.	N/A
      Matlab_ROOT_DIR (Matlab)	Path to MATLAB root directory (on Mac, this is the path to MATLAB_R20xxx.app)	Matlab NOT FOUND (make sure MATLAB is installed)
      PLUGIN_XXX (PLUGIN)	Whether to build a particular GMAT Plugin Note: the proprietary plugins only show up here if GMAT_PROPRIETARY_PLUGINS has been correctly set Note: additional (external) plugins only show up here of GMAT_ADDITIONAL_PLUGINS has been correctly set	N/A
      wxWidgets_ROOT_DIR (wxWidgets)	Mac/Linux: Path to wxWidgets wx-config utility (usually this is the wxWidgets bin/ folder) Windows: Path to wxWidgets (containing include/ and lib/)	wxWidgets NOT FOUND (make sure to run depends script from Step 1)
      PYTHON_LIBRARY (PYTHON) (Advanced Variable)	Use a specific installation of Python for GMAT's PythonInterface plugin. If this variable is blank, the latest version of Python that can be found in default locations will be used. Set this to the FULL PATH to pythonXX.lib (e.g. C:/path/to/python35.lib) if you installed Python to a custom location.	Python NOT FOUND (make sure Python is installed, and variable is set properly)
      XercesC_INCLUDE_DIR XercesC_LIBRARY (Xerces)	Xerces library and include folder locations.	Failed to find XercesC (make sure to run depends script from Step 1)

5. When all CMake errors are handled and you have specified all desired GMAT options, click "Generate".
   CMake will create the build system in the chosen out-of-source build folder (Figure 3 box 2).

...

1. Open the GMAT.sln Visual Studio solution. After loading, you should see the following projects:
   

   Figure 8. CMake-generated VisualStudio2013 Solution

   
   NOTE: This list may vary according to the GMAT plugins you chose in Step 2.
   The common projects you will see are:
   • ALL_BUILD: The default startup project. Ensures that all other projects are up-to-date, then builds them.
   • ZERO_CHECK: Performs the work to ensure all other projects are up-to-date. It is automatically built along with all other projects.
   • INSTALL:  Creates a standalone GMAT folder containing all executables, plugins, data files, samples, and documentation.
   • GmatBase, GmatConsole, GmatGUI, Plugins: The various GMAT components. You can build these individually if desired.
2. Choose a build configuration, e.g. Release, Debug, etc.
3. Build the ALL_BUILD project. Depending on your system speed and number of selected GMAT components, this may take a while!
4. (Optional) Build the INSTALL project if you want a fully standalone and relocatable version of GMAT.

...

wxWidgets v3.0.2 has a known bug (documented here) on Mac OSX 10.10+ that causes a build error. As of R2016a, the GMAT dependency configuration script (configure.sh) implements this fix internally, so GMAT users do not need to take any additional action for wxWidgets to build on Mac. THIS IS NO LONGER AN ISSUE since switching to wxWidgets 3.0.4.

Including the OpenFramesInterface 3D Visualization Plugin

...