Configure CMake Build Process

CMake is a third-party, open-source tool for build process management. To build code generated from MATLAB^® code, the software provides CMake toolchain definitions for:

• Microsoft^® Visual C++^® and MinGW^® on Windows^®, GCC on Linux^®, and Xcode on Mac computers, using Ninja and makefile generators.

• Microsoft Visual Studio^® and Xcode project builds.

If a supported toolchain is installed on your development computer, you can specify the corresponding CMake toolchain definition during code generation. When you generate code, CMake:

1. Uses configuration (CMakeLists.txt) files to generate standard build files.

2. Runs the compiler and other build tools to create executable code.

You can also:

• Provide custom CMake toolchain definitions by using the target package. For more information, see Create Custom CMake Toolchain Definition.

• Generate only code and a configuration file for algorithm export.

Specify CMake Toolchain Definition

Using MATLAB Coder App

To open the Code Generation Configuration dialog box, click Settings on the MATLAB Coder™ tab of the toolstrip. On the Hardware pane:

1. Specify your hardware board and, optionally, hardware implementation parameters. This information determines the selection of toolchain definitions that is available. The default value, MATLAB Host Computer, is applicable for deploying to the computer where MATLAB is running. For more information, see Available CMake Toolchain Definitions.

2. Specify these build process parameters:

   • Toolchain — From the drop-down list, select a CMake toolchain definition.

   • Build configuration — Select one of these values:

     • Release — Optimizations enabled.

     • Debug — Optimizations disabled, debug symbols generated.

     • RelWithDebInfo — Optimizations enabled, debug symbols generated.

     • MinSizeRel — Optimized for size, debug symbols not generated.

     • Specify — Enables you to specify toolchain details through the CMake Configure and CMake Build fields.

   • Toolchain details — If Build configuration is Specify, populate these fields:

     • CMake Configure — Additional command-line arguments to pass to CMake when generating the project build system builder artifacts for the downstream tools.

     • CMake Build — Additional command-line arguments to pass to CMake when using it in build mode.

At Command Line

In a coder.CodeConfig or coder.EmbeddedCodeConfig object:

1. If necessary, configure the target hardware by assigning a coder.hardware object to the Hardware property or modifying the HardwareImplementation property by assigning a coder.HardwareImplementation object. This information determines the selection of toolchain definitions that is available. For more information, see Available CMake Toolchain Definitions.

2. Specify the build process by assigning the Toolchain and the BuildConfiguration properties. If you set BuildConfiguration to 'Specify', use the CustomToolchainOptions property for customization of settings for tools in the selected toolchain. For more information on the available BuildConfiguration options, see the previous section.

For more information, see https://cmake.org/cmake/help/latest/manual/cmake.1.html.

Available CMake Toolchain Definitions

Platform	Shipped Toolchain Definition	Device Vendor and Type that Make Definition Available
Windows	Microsoft Visual C++ 2017 v15.0 | CMake/nmake (64-bit Windows)	Intel-x86-64 (Windows64) AMD-x86-64 (Windows64)
	Microsoft Visual C++ 2017 v15.0 | CMake/Ninja (64-bit Windows)
	Microsoft Visual Studio Project 2017 | CMake (64-bit Windows)
	Microsoft Visual Studio Project 2019 | CMake (64-bit Windows)
	Microsoft Visual Studio Project 2022 | CMake (64-bit Windows)
	Microsoft Visual C++ 2019 v16.0 | CMake/Ninja (64-bit Windows)
	Microsoft Visual C++ 2022 v17.0 | CMake/nmake (64-bit Windows)
	Microsoft Visual C++ 2022 v17.0 | CMake/Ninja (64-bit Windows)
	MinGW64 | CMake/gmake (64-bit Windows)
	MinGW64 | CMake/Ninja (64-bit Windows)
	Microsoft Visual C++ 2017 v15.0 | CMake/nmake (32-bit Windows)	Intel-x86-32 (Windows32) AMD-x86-32 (Windows32)
	Microsoft Visual C++ 2017 v15.0 | CMake/Ninja (32-bit Windows)
	Microsoft Visual Studio Project 2017 | CMake (32-bit Windows)
	Microsoft Visual Studio Project 2019 | CMake (32-bit Windows)
	Microsoft Visual Studio Project 2022 | CMake (32-bit Windows)
	Microsoft Visual C++ 2019 v16.0 | CMake/nmake (32-bit Windows)
	Microsoft Visual C++ 2019 v16.0 | CMake/Ninja (32-bit Windows)
	Microsoft Visual C++ 2022 v17.0 | CMake/nmake (32-bit Windows)
	Microsoft Visual C++ 2022 v17.0 | CMake/Ninja (32-bit Windows)
Linux	GNU gcc/g++ | CMake/gmake (64-bit Linux)	Intel-x86-64 (Linux 64) AMD-x86-64 (Linux 64)
	GNU gcc/g++ | CMake/Ninja (64-bit Linux)
Mac	Xcode with Clang | CMake/gmake (64-bit Mac)	Intel-x86-64 (Mac OS X) AMD-x86-64 (Mac OS X)
	Xcode with Clang | CMake/Ninja (64-bit Mac)
	Xcode with Clang Project | CMake (64-bit Mac)

Note

If the Test hardware is the same as production hardware check box is not selected, the Test hardware settings for device vendor and type control the availability of shipped toolchain definitions.

Generate Only Code and CMake Configuration File for Algorithm Export

When you generate only the C/C++ source code for your MATLAB code, you can instruct the code generator to also produce a CMakeLists.txt file that does not depend on specific build tools. Do one of the following:

• In a coder.CodeConfig or coder.EmbeddedCodeConfig object, set the Toolchain property to "CMake".

• Open the Code Configuration Settings dialog box by clicking Settings on the MATLAB Coder tab of the toolstrip. On the Hardware pane, set Toolchain to CMake.

To export generated code to another development environment, use this workflow:

1. Package the generated code to produce a ZIP file that contains the source code and CMake configuration file. Use the hierarchical packaging type. See packNGo and Package Code for Other Development Environments.

2. Relocate the ZIP file to your development environment.

3. Unzip the packaged files.

4. Use the CMake build tool and configuration file to create an executable file.

If the ZIP file contains mlrFiles.zip, static dependencies from your matlabroot folder tree, you must specify the location of the unzipped files for the CMake build tool. In your development environment, set the MATLAB_ROOT CMake cache entry by running this command:

cmake -S pathToSource -B pathToProposedLocationOfDerivedFiles 
-DMATLAB_ROOT=pathToUnzippedmlrFiles

Configure Use of Position-Independent Code

By default, the code generator produces a CMake configuration (CMakeLists.txt) file that builds position-independent code.

If you only generate code and use the CMake configuration file for algorithm export, you can override the default behavior by setting the CMAKE_POSITION_INDEPENDENT_CODE variable when you run cmake:

cmake -S pathToSource -B pathToProposedLocationOfDerivedFiles 
-DMATLAB_ROOT=pathToUnzippedmlrFiles -DCMAKE_POSITION_INDEPENDENT_CODE=OFF

If you define a custom toolchain, you can set the variable by using the CommandLineCacheEntries property of the target.CMakeBuilder (Simulink Coder) class:

toolchain = target.create('Toolchain','Name','My Toolchain','MakeToolType','CMake');
toolchain.Builder.CommandLineCacheEntries(end+1) = ...
  target.create('CMakeCacheEntry','Name','CMAKE_POSITION_INDEPENDENT_CODE','Value','OFF');

If you use a predefined toolchain, you can use the following code in a before_make build hook or a PostCodeGenerationCommand hook:

cfg = coder.make.CMakeListsConfiguration(buildInfo);
cfg.PositionIndependentCode = 'Off';

For more information, see Customize Build Process with STF_make_rtw_hook File (Embedded Coder) and Customize Post-Code-Generation Build Processing (Embedded Coder).