You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

CMake on Windows, Linux, and MacOS X Operating Systems

This build system is currently only available when using the GSFC-internal GMAT Git repository.

Overview

Before starting, make sure that you have cloned GMAT from the GSFC-internal repository.

These instructions refer to <GMAT> as the top-level GMAT repository folder.

Figure 1. The <GMAT> repository layout

GMAT Repository Layout

 

The GMAT build process can be broken down into three main steps:

  1. Download and configure the dependencies (e.g. CSPICE, wxWidgets, etc.)
  2. Create the build system using CMake
  3. Build GMAT. Optionally, you can also install GMAT after building.
  4. Run GMAT

The first two steps are generally "one-time" processes that are performed immediately after downloading the GMAT repository. They 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.

Step 1: Download and Configure GMAT Dependencies

The <GMAT>/depends folder contains scripts to automatically download and configure the GMAT dependencies. 

Requirements:

  • Windows: Visual Studio 2010 or 2013 (Express or Paid versions). If using VS2010 Express, you will need the Microsoft 7.1 SDK.
  • Mac: XCode tools, with the command line developer tools
  • Linux: gcc compiler tools

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

GMAT depends folder

 To set up GMAT dependencies, double-click the configure.sh (Mac/Linux) or configure.bat (Windows) script.

  • 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.
  • You can also run these scripts by name from the Terminal (Mac/Linux) or Command Prompt (Windows).

 The script will download, build, and configure the GMAT dependencies. The resulting <GMAT>/depends folder structure should look like Figure 2.

Step 2: Create GMAT Build System Using CMake

Requirements (in addition to Step 1 requirements):

  • All Operating Systems: CMake (Minimum version 2.8.12)
  • Linux: libgtk2.0-dev or libgtk-3-dev
  • Optional: MATLAB (if building MatlabInterface or CInterface plugins)

 Launch the CMake GUI:

Tip: Make sure to select the "Grouped" option in the CMake GUI (Figure 3) to sort CMake variables and make them easier to find.

Figure 3. Components of the CMake GUI

CMake components

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

  1. Enter the full path to the <GMAT> cloned repository on your computer
  2. Enter the full path to the folder where all CMake files and build products should be placed
    1. CMake produces out-of-source builds. It is recommended to use <GMAT>/build/<OS>/cmake-build for this value.
  3. Click "Configure"
    1. CMake may ask for permission to create the folder you chose in Step 2 ("Where to build the binaries")
    2. CMake will ask you to choose a generator (see Figure 4). 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 4. Choosing a generator in CMake

        CMake choose generator

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

      Figure 5. Output of CMake Configure

      CMake initial configure
  4. Use the Configure results output box (Figure 3 section 4a) to change variables in 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)DescriptionAssociated CMake Error
      CSPICE_DIR (Ungrouped)Path to CSPICE root directory
      (containing include/, lib/, etc.) 
      CSPICE NOT FOUND
      F2C_DIR (Ungrouped)Path to F2C root directory
      (containing f2c.h) 
      Note: this should generally be CSPICE_DIR/include
      F2C NOT FOUND
      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. cmake-build-release or cmake-build-debug)
      N/A
      CMAKE_INSTALL_PREFIX (CMAKE)Location to install GMAT when doing make install
      or building the VisualStudio->INSTALL project 
      N/A
      GMAT_GUI (GMAT)Whether to build the GMAT GUIN/A
      GMAT_PROPRIETARYPLUGINS_PATH
      (GMAT)
      Full path to the top-level GMAT Proprietary Plugins folder.
      (containing code/)
      N/A
      Matlab_ROOT_DIR (Matlab)Path to MATLAB root directory
      (on Mac, this is the path to MATLAB_R20xxx.app)
      Matlab NOT FOUND
      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 
      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
  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).

Step 3: Build and Install GMAT

 Go to the build system folder (chosen in Figure 3 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 following projects:

    Figure 5. CMake-generated VisualStudio2013 Solution

    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. ReleaseDebug, 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_binary_path> is the path to the build system folder that you chose in Step 2 (Figure 3 box 2).

  1. Open a command prompt and type the following commands (assuming $ is your command prompt):
    $ cd <CMake_binary_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) Do "make install" if you want a fully standalone and relocatable version of GMAT.

Step 4: Run GMAT

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

  • All Operating Systems: 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 cycle.
  • All Operating Systems: If you built the optional INSTALL project in Step 3, then 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.
  • Windows: You can run the GmatConsole and GmatGUI projects directly from within VisualStudio.

 

  • No labels