CMake on Windows, Linux, and macOS Operating Systems

Overview

The GMAT, GMAT Plugins, and CSALT build process is managed by CMake and custom scripts that automatically install required dependencies. (CSALT currently requires some manual configuration.)   The build process can be broken down into several steps:

1. Clone the GMAT Repositories

2. Download and configure the dependencies (e.g. CSPICE, wxWidgets, etc.)

3. Create the build system using CMake

4. Build GMAT. Optionally, you can also install GMAT after building.

5. Run GMAT

 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 with subfolders as indicated in Figure GMAT_TopFolder.

Open

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.  Public developers can obtain the source code from SourceForge (the Git command is: "git clone git://git.code.sf.net/p/gmat/git gmat-git"). Internal developers should contact the GMAT team for repository URLs.  

Step 2: Download and Configure GMAT Dependencies

GMAT is distributed with a Python script to configure most (but not all) dependencies.  Table GMAT_Depends 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.

Requirements:

• Windows: Visual Studio 2022 (Community 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)
  
  

Open

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

• Run configure.sh on Mac/Linux by name from the Terminal. Run configure.bat on Windows by double-clicking or running it from the Command Prompt.

• On Windows you will be prompted to select 32-vs-64 bit dependencies and a VisualStudio version. Choose according to your VisualStudio installation. On Mac/Linux these choices are currently auto-selected based on the system architecture.
  
  

• The resulting <GMAT>/depends folder structure should look like Figure DependsFolder.

 → (For GMAT R2019a and later) Using Python 3, run the configure.py script to set up core GMAT dependencies.

• Open a Command Prompt (Windows) or system terminal (Linux or Mac).

• If your depends folder of the GMAT repo is not in your Python path, add it to the Python path or change directories to the depends folder (gmat\depends).
  
  

• Run the Python configuration script:

  • On Windows, Execute the command "python configure.py".

  • On Mac or Linux, Execute the command "python3 configure.py".

• The resulting <GMAT>/depends folder structure should look like Figure DependsFolder.

  → Download optional GMAT dependencies.

• See Table GMAT_Depends for dependency download links.

• For Python on Windows, select the option to add to system PATH. The equivalent option on Mac (Shell Profile Updater) is selected by default.

Python Dependency Configuration

As shown in Table GMAT_Depends, multiple GMAT components require a Python distribution be installed on the developer's system. At a minimum, developers are encouraged to install the same version of Python that is used in the GMAT test system. By default GMAT will search for Python versions listed in Table GMAT_Depends, and create versions of each component corresponding to those Python versions. Specifying which version of Python to use at runtime is described in Step 5 (Run GMAT) below.

Developers can override the Python versions that GMAT searches for using the GMAT_PYTHON3_VERSIONS CMake variable. They can also specify a custom Python install location using the GMAT_PYTHON3X_ROOT_DIR CMake variable. These variables are documented in Table CMakeVariables. Modifying either of these variables is uncommon, and should be done with intention and care.

CSALT Dependency Configuration

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

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

Using Project Code

The SNOPT source code is contained in an archive that your team lead will provide to you.  Unpack that archive into your depends folder, and verify the resulting snopt7 fonder contains the file structure shown in Figure SNOPT_Folders.

Windows, Mac, and Linux developers with access to the GMAT internal repository can find prebuilt copies of the SNOPT libraries in platform specific subfolders of the <gmatinternal>/code/CSALTPlugin/snoptlibs folder.  Precompiled libraries are available there for Windows 10, Linux (built on Ubuntu) and Mac OS X (built on High Sierra).  Thise libraries will need to be copied into place in the bin and debug subdirectories of the GMAT output directory that you will configure later in the build configuration.  In the GMAT CMake settings, that directory is labeled GMAT_BUILDOUTPUT_DIRECTORY, and defaults to the <GMAT>/application folder.

Developers working on other platforms will need to build SNOPT for their environments.  The build procedure is described in the snopt7/INSTALL text file.  Be sure to build both the SNOPT shared library and the C++ interface shared library for the target platform. 
 

Building SNOPT from SBS Source

SBS delivers the SNOPT code in an archive file.  Unpack the SNOPT 7.5 archive, snopt7.5-1.4 into the depends folder.  On success, the depends folder should contain the snopt7 folder used to build CSALT.  Follow the SNOPT build instructions, found in the INSTALL text file of the snopt7 folder, to create theSNOPT shared library and the SNOPT C++ interface library.  Once built, the libraries snopt7 and snopt7_cpp (with platform specific file extensions) are located in the lib/.libs folder.  Copy the shared libraries to the .lib folder, completing installation.

A note for Windows developers:  SNOPT is coded in Fortran.  You will need a Fortran compiler to build SNOPT for your workstation.  The libraries built for the GMAT development team were compiled using the Intel Fortran compiler.  Windows users of the CSALT libraries also install the Intel redistributable libraries as part of the GMAT/CSALT installation procedure. (See "Additional CSALT Dependencies" in Table GMAT_Depends)

Step 3: Create GMAT Build System Using CMake

Requirements (in addition to Step 1 requirements):

• All Operating Systems: CMake (Minimum version 3.19.0)

• Linux: libgl1-mesa-dev, libglu1-mesa-dev, libgtk-3-dev (or libgtk2.0-dev), tcsh (or csh)

• Optional: MATLAB (if building MatlabInterface or CInterface plugins). On macOS, the following must be done in Matlab once to initialize its internal compiler:

  • Launch Matlab, run the command: mex -setup

  • If Matlab gives a "No supported compiler or SDK was found" error, then a patch to Matlab must be applied. This is a known incompatibility between Matlab R2015a/b and XCode 7. The patch and instructions to apply it can be found here on the MathWorks website. This problem with Matlab is documented on the GMAT Bugtracker Issue 5634.

• Optional: Python

→ Launch the CMake GUI:

Tip: Select the "Grouped" option in the CMake GUI (Figure CMakeGUI) to sort CMake variables and make them easier to find.

Tip: Select the "Advanced" option in the CMake GUI (Figure CMakeGUI) to display variables, such as PYTHON_LIBRARY, that are normally hidden.

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

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

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 CMakeGenerator). See the CMake Generator webpage for an explanation of available generators.
      Recommended generators are:

      1. Mac: Unix Makefiles (XCode has been observed to work but has not been tested by the GMAT team)

      2. Linux: Unix Makefiles

      3. Windows: Visual Studio 17 2022 with Platform Generator as x64
         NOTE: GMAT no longer supports 32-bit executables on Windows
         
         

         Figure CMakeGenerator. Choosing a generator in CMake

   3. CMake will start the configuration process, after which the Variable List and Configure Results sections (Figure CMakeGUI sections 4a and 4b) will be populated as seen in Figure CMakeConfigure.
      
      

      Figure CMakeConfigure: Output of CMake Configure

4. Use the Configure results output box (Figure CMakeGUI section 4a) to change variables in the CMake variable list (Figure CMakeGUI 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:

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 CMakeGUI box 2).

→ Using CMake Command Line instead CMake GUI

CMake is fully scriptable and can be called from the command line instead of using the GUI. This is especially useful on operating systems (e.g. Red Hat Linux 7) where the GUI is unavailable.

1. Create the folder where the GMAT build system should be placed

   • cd <GMAT>/build; mkdir macosx-cmake; cd macosx-cmake

2. Tell CMake to run from the base <GMAT> folder and specify options
   
   

   • cmake [options] ../..

   • All options from above can be specified using -DOPTION=VALUE formatting. e.g. -DPLUGIN_CINTERFACE=OFF. Multiple such options can be specified.

   • CMake will perform both "Configure" and "Generate" steps at once, and place build system files in the current directory.

→ CMake Settings for CSALT

Beginning with the beta leading to GMAT R2019a, builds for the Collocation Stand Alone Library and Toolkit (CSALT) are incorporated into the GMAT build system.  The CSALT dependencies are included in the list of dependencies above.  CSALT users set up the build system by following these additional steps:

Configuration

The CSALT build is controlled by checkboxes on the CMake GUI in the Ungrouped Entries section if CSALT has not been built before, or in the GMAT section if it has been built.  The CSALT build toggle is labeled GMAT_INCLUDE_CSALT as seen in Figure CMakeCSALT.

When you activate the CSALT build setting and configure the CMake build again, another CSALT setting, GMAT_INCLUDE_CSALT_TESTPROGRAM, will be added to the Ungrouped Entries group.  This switch controls builds of the CSALT test program.  The next time (and all subsequent times) that the CMake GUI configure button is toggled, the CSALT settings will be grouped together, as in the image above.

The GMAT CSALT interface is part of the GMAT internal repository.  Users with access to that repository can build the GMAT interface plugins for CSALT (PLUGIN_PROPRIETARY_CSALT) and the EMTG spacecraft models (PLUGIN_PROPRIETARY_EMTG_MODELS).

Activating the CSALT build switches turns on the corresponding build settings, producing the CSALT.  Installing the resulting build includes installation of the SNOPT and CSALT libraries and the CSALT test executable (if selected to build).  The GMAT interfaces can be activated by adding the PLUGIN entries for the build CSALT libraries in the GMAT startup file.

Step 4: Build and Install GMAT

→ Go to the build system folder (chosen in Figure CMakeGUI box 2), and follow the OS-specific instructions below.

Windows (Visual Studio)

1. Open the GMAT.sln Visual Studio solution.
   After loading, you should see the projects as seen in Figure GMAT_VS.
   
   

   Figure GMAT_VS. CMake-generated Visual Studio 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.

macOS and Linux (makefiles)

Makefiles are run through the command line, which on Mac and Linux can be accessed via the Terminal application.

In these instructions, <CMake_build_path> is the path to the build system folder that you chose in Step 2 (Figure CMakeGUI box 2).

1. Open a command prompt and type the following commands (assuming $ is your command prompt):
   $ cd <CMake_build_path>
$ make
   
   

   • Note: if you know your computer has N cores, you can also do "make -jN" to significantly speed up the compile time

2. (Optional) Type "make install" if you want a fully standalone and distributable version of GMAT.

Possible Build Errors

See Table BuildErrors in case there are build errors when compiling or installing GMAT.

Step 5: Configure and Run GMAT

After building, you have several options for how to run GMAT:

• GMAT Users: After building the INSTALL project in Step 4, a standalone copy of GMAT is placed in the CMAKE_INSTALL_PREFIX folder that you chose in Step 2. The GMAT executables will be in the bin/ subfolder.

• GMAT Developers: GMAT executables and plugins are placed in the <GMAT>/application directory. You can run GMAT from the bin/ (or debug/) subfolders without having to perform the optional INSTALL step. This allows for a more rapid edit-build-test development cycle. On Windows, you can also run the GmatConsole and GmatGUI projects directly from within VisualStudio. This allows for in-program debugging with breakpoints.

  1. Select the configuration that you want to run (Release, Debug, etc.)

  2. Right-click on the GmatConsole or GmatGUI project, and select "Set as Startup Project"

  3. Select menu item Debug -> Start Debugging (or Start Without Debugging for Release configurations

• ALL: Configure the interfaces desired (e.g., Matlab, Python) using the instructions in the GMAT UserGuide locally installed in the /docs/help/ directory.

Python Version Selection

As listed in Table GMAT_Depends, several GMAT components depend on Python. These components will have multiple built versions in the GMAT plugin/ subfolder, with names that clearly identify which version of Python they use. Examples of these plugins can be seen in Figure PythonPlugins.

When running GMAT, the gmat_startup_file.txt file should contain a PLUGIN line corresponding to the desired Python-supported version of each plugin as seen in Figure GmatStartup.

Known Issues and Work-Arounds

wxWidgets on Mac

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

The GMAT project has incorporated the OpenFramesInterface (OFI) plugin as a 3D visualization replacement for OrbitView. Follow the OFI build instructions to include the OFI in your GMAT build.