IXM is a CMake library and thus knowing how to use CMake is imperative. A lot has changed in the CMake command line interface in recent years, and this chapter can act as a bit of a refresher.
Choosing a Build Tool
CMake provides a large set of possible build tools. The fastest and most useful
however is the ninja build tool. IXM works best with
ninja, though it will
always work with any Makefile based generator.
While the authors of CMake recommend against this use of
the ability to glob files in practice has been more useful for automatic
project generation and it is inherent to some of the behavior found in IXM
Using CMake On the Command Line
Until recently, CMake could not easily handle all aspects of the build process. This has, however, changed. These are the most common flags you’ll use when working with CMake.
- This option declares the build directory where CMake will generate all its
files. CMake will generate the build directory for you, though nothing stops
you from creating the directory first. For your sanity, it is recommended you
give this a name in a different location, such as either
target. CMake works best when it treats the source directory and build directory as separate locations. Weird things can (and will) happen otherwise. In some extreme cases, code generation might overwrite existing files.
- This option declares the source directory where CMake will read from the
CMakeLists.txtfile. When configuring from the same directory as the
CMakeLists.txtdirectory, you can simply pass in
- As mentioned above, while we cannot dictate the build tool you use, the
author of IXM highly recommends you use the ninja build tool. Thus, you will
most likely pass this flag as
-G Ninjato CMake’s command line arguments.
- This option is used to set variables into the CMake cache. These can be values used by CMake itself, or even variables expected for use with IXM.
- This option is used to unset variables inside the CMake cache. This can be used to “reset” part of the configuration process and require some parts of CMake to be reconfigured.
- Takes the same directory named used by
-Band will execute the build with the correct build tool. It is used in tandem with
--targetand will remove any concern over what build tool was used to generate the build directory. This is most useful when writing generic scripts, or wrapper Makefiles.
- Requires that you also pass
--build. Takes the name of some target generated by your project. CMake will then only build that target and its dependencies. When this flag is not passed, CMake will build the all target. This option is used to also run custom targets within CMake, such as
clang-formattargets, or static analyzers, as long as they have been configured correctly.
Generating The Build
Configuring (and regenerating) a CMake build is simple. Run the following
command in the same directory as your
cmake -B build -S. -G Ninja -DCMAKE_BUILD_TYPE=Debug
Assuming everything is setup correctly, your build will be ready to run inside
On occasion, it might be necessary to regenerate your build. To do this, simply
-B option with the build directory location. This is also where you
can add or change additional settings with
-D or remove them with
A example of this can be seen when wanting to switch to clang from gcc in a C++ project
cmake -Bbuild -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang
Running the Build
CMake provides the
--build command to execute the correct build tool The
parameter passed to this must be the location of the build directory.
cmake --build build
With the exception of errors in your actual code or project setup (incorrectly setting directories or flags, invalid code, etc.) your project will build.
In recent years, cross compiling has gotten simpler under CMake. In many cases, a toolchain file is needed. However, in the case of some systems such as Android or iOS, all that is needed is the toolchain to be installed, and then to configure CMake’s “system name”:
cmake -Bbuild -DCMAKE_SYSTEM_NAME=Android
This solves most problems for users, and doesn’t require the acquisition of several different toolchain files