From ccfc1c8257374f5296233f5eaf74b0ebf70ec2d8 Mon Sep 17 00:00:00 2001 From: YL Wang <121748352+code4yonglei@users.noreply.github.com> Date: Wed, 4 Sep 2024 10:17:33 +0200 Subject: [PATCH] Important issues for CMakeLists.txt in episode "from sources to executables" --- content/hello-cmake.rst | 117 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/content/hello-cmake.rst b/content/hello-cmake.rst index 2995964..ed6978f 100644 --- a/content/hello-cmake.rst +++ b/content/hello-cmake.rst @@ -104,8 +104,125 @@ Hello, CMake! $ cmake --build build +Important issues for the ``CMakeLists.txt`` file +------------------------------------------------ +1. Any CMake build system will invoke the following commands in its **root** + ``CMakeLists.txt``: + + .. signature:: |cmake_minimum_required| + + .. code-block:: cmake + + cmake_minimum_required(VERSION [...] [FATAL_ERROR]) + + .. parameters:: + + ``VERSION``: Minimum and, optionally, maximum version of CMake to use. + ``FATAL_ERROR``: Raise a fatal error if the version constraint is not satisfied. This option is ignored by CMake >=2.6 + + .. signature:: |project| + + .. code-block:: cmake + + project( + [VERSION [.[.[.]]]] + [DESCRIPTION ] + [HOMEPAGE_URL ] + [LANGUAGES ...]) + + .. parameters:: + + ````: The name of the project. + ``LANGUAGES``: Languages in the project. + + +2. The case of CMake commands does not matter: the DSL is case-insensitive. However, the plain-text files that CMake parses **must be called** ``CMakeLists.txt`` and the case matters! The variable names are also case sensitive! + + +3. The command to add executables to the build system is |add_executable|: + + .. signature:: |add_executable| + + .. code-block:: cmake + + add_executable( [WIN32] [MACOSX_BUNDLE] + [EXCLUDE_FROM_ALL] + [source1] [source2 ...]) + + +4. Using CMake you can abstract the generation of the build system and also the invocation of the build tools. + +.. callout:: Put your ``CMakeLists.txt`` under version control + + All CMake-related files will evolve together with your codebase. It's a good idea to put them under version control. On the contrary, any of the *generated* native build-system files, *e.g.* ``Makefile``-s, should not be version-controlled. + + +.. typealong:: The command-line interface to CMake + + Let us get acquainted with the CMake and especially its command-line interface. + + We can get help at any time with the command + + .. code-block:: bash + + $ cmake --help + + This will output quite a number of options to your screen. We can analyze the last few lines first: + + .. code-block:: text + + Generators + + The following generators are available on this platform (* marks default): + * Unix Makefiles = Generates standard UNIX makefiles. + Green Hills MULTI = Generates Green Hills MULTI files. + Ninja = Generates build.ninja files. + Ninja Multi-Config = Generates build-.ninja files. + Watcom WMake = Generates Watcom WMake makefiles. + CodeBlocks - Ninja = Generates CodeBlocks project files. + CodeBlocks - Unix Makefiles = Generates CodeBlocks project files. + CodeLite - Ninja = Generates CodeLite project files. + CodeLite - Unix Makefiles = Generates CodeLite project files. + Sublime Text 2 - Ninja = Generates Sublime Text 2 project files. + Sublime Text 2 - Unix Makefiles = Generates Sublime Text 2 project files. + Kate - Ninja = Generates Kate project files. + Kate - Unix Makefiles = Generates Kate project files. + Eclipse CDT4 - Ninja = Generates Eclipse CDT 4.0 project files. + Eclipse CDT4 - Unix Makefiles = Generates Eclipse CDT 4.0 project files. + + In CMake terminology, the native build scripts and build tools are called **generators**. On any particular platform, the list will show which native build tools can be used through CMake. They can either be "plain", such as ``Makefile``-s or Ninja, or IDE-like projects. + + The ``-S`` switch specifies which source directory CMake should scan: this is the folder containing the *root* ``CMakeLists.txt``, *i.e.*, the one containing the |project| command. By default, CMake will allow *in-source* builds, *i.e.* storing build artifacts alongside source files. This is **not** good practice: you should always keep build artifacts from sources separate. Fortunately, the ``-B`` switch helps with that, as it is used to give where to store build artifacts, including the generated build system. This is the minimal invocation of ``cmake``: + + .. code-block:: bash + + $ cmake -S. -Bbuild + + To switch to another generator, we will use the ``-G`` switch: + + .. code-block:: bash + + $ cmake -S. -Bbuild -GNinja + + Options to be used at build-system generation are passed with the ``-D`` switch. For example, to change compilers: + + .. code-block:: bash + + $ cmake -S. -Bbuild -GNinja -DCMAKE_CXX_COMPILER=clang++ + + Finally, you can access to the full CMake manual with: + + .. code-block:: bash + + $ cmake --help-full + + You can also inquire about a specific module, command or variable: + + .. code-block:: bash + + $ cmake --help-variable CMAKE_GENERATOR