440 lines · plain
1============2CMake Primer3============4 5.. contents::6 :local:7 8.. warning::9 Disclaimer: This documentation is written by LLVM project contributors `not`10 anyone affiliated with the CMake project. This document may contain11 inaccurate terminology, phrasing, or technical details. It is provided with12 the best intentions.13 14 15Introduction16============17 18The LLVM project and many of the core projects built on LLVM build using CMake.19This document aims to provide a brief overview of CMake for developers modifying20LLVM projects or building their own projects on top of LLVM.21 22The official CMake language reference is available in the cmake-language23manpage and `cmake-language online documentation24<https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html>`_.25 2610,000 ft View27==============28 29CMake is a tool that reads script files in its own language that describe how a30software project builds. As CMake evaluates the scripts, it constructs an31internal representation of the software project. Once the scripts have been32fully processed, if there are no errors, CMake will generate build files to33actually build the project. CMake supports generating build files for a variety34of command line build tools as well as for popular IDEs.35 36When a user runs CMake it performs a variety of checks similar to how autoconf37worked historically. During the checks and the evaluation of the build38description scripts CMake caches values into the CMakeCache. This is useful39because it allows the build system to skip long-running checks during40incremental development. CMake caching also has some drawbacks, but that will be41discussed later.42 43Scripting Overview44==================45 46CMake's scripting language has a very simple grammar. Every language construct47is a command that matches the pattern _name_(_args_). Commands come in three48primary types: language-defined (commands implemented in C++ in CMake), defined49functions, and defined macros. The CMake distribution also contains a suite of50CMake modules that contain definitions for useful functionality.51 52The example below is the full CMake build for building a C++ "Hello World"53program. The example uses only CMake language-defined functions.54 55.. code-block:: cmake56 57 cmake_minimum_required(VERSION 3.20.0)58 project(HelloWorld)59 add_executable(HelloWorld HelloWorld.cpp)60 61The CMake language provides control flow constructs in the form of ``foreach`` loops62and ``if`` blocks. To make the example above more complicated you could add an if63block to define "APPLE" when targeting Apple platforms:64 65.. code-block:: cmake66 67 cmake_minimum_required(VERSION 3.20.0)68 project(HelloWorld)69 add_executable(HelloWorld HelloWorld.cpp)70 if(APPLE)71 target_compile_definitions(HelloWorld PUBLIC APPLE)72 endif()73 74Variables, Types, and Scope75===========================76 77Dereferencing78-------------79 80In CMake, variables are "stringly" typed. All variables are represented as81strings throughout evaluation. Wrapping a variable in ``${}`` dereferences it82and results in a literal substitution of the name for the value. CMake refers to83this as "variable evaluation" in their documentation. Dereferences are performed84*before* the command being called receives the arguments. This means85dereferencing a list results in multiple separate arguments being passed to the86command.87 88Variable dereferences can be nested and be used to model complex data. For89example:90 91.. code-block:: cmake92 93 set(var_name var1)94 set(${var_name} foo) # same as "set(var1 foo)"95 set(${${var_name}}_var bar) # same as "set(foo_var bar)"96 97Dereferencing an unset variable results in an empty expansion. It is a common98pattern in CMake to conditionally set variables knowing that it will be used in99code paths that the variable isn't set. There are examples of this throughout100the LLVM CMake build system.101 102An example of variable empty expansion is:103 104.. code-block:: cmake105 106 if(APPLE)107 set(extra_sources Apple.cpp)108 endif()109 add_executable(HelloWorld HelloWorld.cpp ${extra_sources})110 111In this example the ``extra_sources`` variable is only defined if you're112targeting an Apple platform. For all other targets the ``extra_sources`` will be113evaluated as empty before add_executable is given its arguments.114 115Lists116-----117 118In CMake, lists are semicolon-delimited strings, and it is strongly advised that119you avoid using semicolons in lists; it doesn't go smoothly. A few examples of120defining lists:121 122.. code-block:: cmake123 124 # Creates a list with members a, b, c, and d125 set(my_list a b c d)126 set(my_list "a;b;c;d")127 128 # Creates a string "a b c d"129 set(my_string "a b c d")130 131Lists of Lists132--------------133 134One of the more complicated patterns in CMake is lists of lists. Because a list135cannot contain an element with a semicolon to construct a list of lists you136make a list of variable names that refer to other lists. For example:137 138.. code-block:: cmake139 140 set(list_of_lists a b c)141 set(a 1 2 3)142 set(b 4 5 6)143 set(c 7 8 9)144 145With this layout you can iterate through the list of lists printing each value146with the following code:147 148.. code-block:: cmake149 150 foreach(list_name IN LISTS list_of_lists)151 foreach(value IN LISTS ${list_name})152 message(${value})153 endforeach()154 endforeach()155 156You'll notice that the inner foreach loop's list is doubly dereferenced. This is157because the first dereference turns ``list_name`` into the name of the sub-list158(a, b, or c in the example), then the second dereference is to get the value of159the list.160 161This pattern is used throughout CMake, the most common example is the compiler162flags options, which CMake refers to using the following variable expansions:163``CMAKE_${LANGUAGE}_FLAGS`` and ``CMAKE_${LANGUAGE}_FLAGS_${CMAKE_BUILD_TYPE}``.164 165Other Types166-----------167 168Variables that are cached or specified on the command line can have types169associated with them. The variable's type is used by CMake's UI tool to display170the right input field. A variable's type generally doesn't impact evaluation;171however, CMake does have special handling for some variables such as ``PATH``.172You can read more about the special handling in `CMake's set documentation173<https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry>`_.174 175Scope176-----177 178CMake inherently has a directory-based scoping. Setting a variable in a179CMakeLists file, will set the variable for that file, and all subdirectories.180Variables set in a CMake module that is included in a CMakeLists file will be181set in the scope they are included from, and all subdirectories.182 183When a variable that is already set is set again in a subdirectory it overrides184the value in that scope and any deeper subdirectories.185 186The CMake set command provides two scope-related options. ``PARENT_SCOPE`` sets a187variable into the parent scope, and not the current scope. The ``CACHE`` option sets188the variable in the CMakeCache, which results in it being set in all scopes. The189``CACHE`` option will not set a variable that already exists in the ``CACHE`` unless the190``FORCE`` option is specified.191 192In addition to directory-based scope, CMake functions also have their own scope.193This means variables set inside functions do not bleed into the parent scope.194This is not true of macros, and it is for this reason LLVM prefers functions195over macros whenever reasonable.196 197.. note::198 Unlike C-based languages, CMake's loop and control flow blocks do not have199 their own scopes.200 201Control Flow202============203 204CMake features the same basic control flow constructs you would expect in any205scripting language, but there are a few quirks because, as with everything in206CMake, control flow constructs are commands.207 208If, ElseIf, Else209----------------210 211.. note::212 For the full documentation on the CMake if command go213 `here <https://cmake.org/cmake/help/v3.4/command/if.html>`_. That resource is214 far more complete.215 216In general, CMake ``if`` blocks work the way you'd expect:217 218.. code-block:: cmake219 220 if(<condition>)221 message("do stuff")222 elseif(<condition>)223 message("do other stuff")224 else()225 message("do other other stuff")226 endif()227 228The single most important thing to know about CMake's ``if`` blocks coming from a C229background is that they do not have their own scope. Variables set inside230conditional blocks persist after the ``endif()``.231 232Loops233-----234 235The most common form of the CMake ``foreach`` block is:236 237.. code-block:: cmake238 239 foreach(var ...)240 message("do stuff")241 endforeach()242 243The variable argument portion of the ``foreach`` block can contain dereferenced244lists, values to iterate, or a mix of both:245 246.. code-block:: cmake247 248 foreach(var foo bar baz)249 message(${var})250 endforeach()251 # prints:252 # foo253 # bar254 # baz255 256 set(my_list 1 2 3)257 foreach(var ${my_list})258 message(${var})259 endforeach()260 # prints:261 # 1262 # 2263 # 3264 265 foreach(var ${my_list} out_of_bounds)266 message(${var})267 endforeach()268 # prints:269 # 1270 # 2271 # 3272 # out_of_bounds273 274There is also a more modern CMake foreach syntax. The code below is equivalent275to the code above:276 277.. code-block:: cmake278 279 foreach(var IN ITEMS foo bar baz)280 message(${var})281 endforeach()282 # prints:283 # foo284 # bar285 # baz286 287 set(my_list 1 2 3)288 foreach(var IN LISTS my_list)289 message(${var})290 endforeach()291 # prints:292 # 1293 # 2294 # 3295 296 foreach(var IN LISTS my_list ITEMS out_of_bounds)297 message(${var})298 endforeach()299 # prints:300 # 1301 # 2302 # 3303 # out_of_bounds304 305Similar to the conditional statements, these generally behave how you would306expect, and they do not have their own scope.307 308CMake also supports ``while`` loops, although they are not widely used in LLVM.309 310Modules, Functions and Macros311=============================312 313Modules314-------315 316Modules are CMake's vehicle for enabling code reuse. CMake modules are just317CMake script files. They can contain code to execute on include as well as318definitions for commands.319 320In CMake, macros and functions are universally referred to as commands, and they321are the primary method of defining code that can be called multiple times.322 323In LLVM we have several CMake modules that are included as part of our324distribution for developers who don't build our project from source. Those325modules are the fundamental pieces needed to build LLVM-based projects with326CMake. We also rely on modules as a way of organizing the build system's327functionality for maintainability and reuse within LLVM projects.328 329Argument Handling330-----------------331 332When defining a CMake command handling arguments is very useful. The examples333in this section will all use the CMake ``function`` block, but this also applies334to the ``macro`` block as well.335 336CMake commands can have named arguments that are required at every call site. In337addition, all commands will implicitly accept a variable number of extra338arguments (In C parlance, all commands are varargs functions). When a command is339invoked with extra arguments (beyond the named ones) CMake will store the full340list of arguments (both named and unnamed) in a list named ``ARGV``, and the341sublist of unnamed arguments in ``ARGN``. Below is a trivial example of342providing a wrapper function for CMake's built in function ``add_dependencies``.343 344.. code-block:: cmake345 346 function(add_deps target)347 add_dependencies(${target} ${ARGN})348 endfunction()349 350This example defines a new macro named ``add_deps`` which takes a required first351argument, and just calls another function passing through the first argument and352all trailing arguments.353 354CMake provides a module ``CMakeParseArguments`` which provides an implementation355of advanced argument parsing. We use this all over LLVM, and it is recommended356for any function that has complex argument-based behaviors or optional357arguments. CMake's official documentation for the module is in the358``cmake-modules`` manpage, and is also available at the359`cmake-modules online documentation360<https://cmake.org/cmake/help/v3.4/module/CMakeParseArguments.html>`_.361 362.. note::363 As of CMake 3.5 the cmake_parse_arguments command has become a native command364 and the CMakeParseArguments module is empty and only left around for365 compatibility.366 367Functions Vs Macros368-------------------369 370Functions and Macros look very similar in how they are used, but there is one371fundamental difference between the two. Functions have their own scope, and372macros don't. This means variables set in macros will bleed out into the calling373scope. That makes macros suitable for defining very small bits of functionality374only.375 376The other difference between CMake functions and macros is how arguments are377passed. Arguments to macros are not set as variables, instead dereferences to378the parameters are resolved across the macro before executing it. This can379result in some unexpected behavior if using unreferenced variables. For example:380 381.. code-block:: cmake382 383 macro(print_list my_list)384 foreach(var IN LISTS my_list)385 message("${var}")386 endforeach()387 endmacro()388 389 set(my_list a b c d)390 set(my_list_of_numbers 1 2 3 4)391 print_list(my_list_of_numbers)392 # prints:393 # a394 # b395 # c396 # d397 398Generally speaking, this issue is uncommon because it requires using399non-dereferenced variables with names that overlap in the parent scope, but it400is important to be aware of because it can lead to subtle bugs.401 402LLVM Project Wrappers403=====================404 405LLVM projects provide lots of wrappers around critical CMake built-in commands.406We use these wrappers to provide consistent behaviors across LLVM components407and to reduce code duplication.408 409We generally (but not always) follow the convention that commands prefaced with410``llvm_`` are intended to be used only as building blocks for other commands.411Wrapper commands that are intended for direct use are generally named following412with the project in the middle of the command name (i.e. ``add_llvm_executable``413is the wrapper for ``add_executable``). The LLVM ``add_*`` wrapper functions are414all defined in ``AddLLVM.cmake`` which is installed as part of the LLVM415distribution. It can be included and used by any LLVM sub-project that requires416LLVM.417 418.. note::419 420 Not all LLVM projects require LLVM for all use cases. For example compiler-rt421 can be built without LLVM, and the compiler-rt sanitizer libraries are used422 with GCC.423 424Useful Built-in Commands425========================426 427CMake has a collection of useful built-in commands. This document isn't going to428go into details about them because The CMake project has excellent429documentation. To highlight a few useful functions see:430 431* `add_custom_command <https://cmake.org/cmake/help/v3.4/command/add_custom_command.html>`_432* `add_custom_target <https://cmake.org/cmake/help/v3.4/command/add_custom_target.html>`_433* `file <https://cmake.org/cmake/help/v3.4/command/file.html>`_434* `list <https://cmake.org/cmake/help/v3.4/command/list.html>`_435* `math <https://cmake.org/cmake/help/v3.4/command/math.html>`_436* `string <https://cmake.org/cmake/help/v3.4/command/string.html>`_437 438The full documentation for CMake commands is in the ``cmake-commands`` manpage439and available on `CMake's website <https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html>`_440