Lines Matching full:cmake
2 CMake Primer
10 anyone affiliated with the CMake project. This document may contain
18 The LLVM project and many of the core projects built on LLVM build using CMake.
19 This document aims to provide a brief overview of CMake for developers modifying
22 The official CMake language references is available in the cmake-language
23 manpage and `cmake-language online documentation
24 <https://cmake.org/cmake/help/v3.4/manual/cmake-language.7.html>`_.
29 CMake is a tool that reads script files in its own language that describe how a
30 software project builds. As CMake evaluates the scripts it constructs an
32 fully processed, if there are no errors, CMake will generate build files to
33 actually build the project. CMake supports generating build files for a variety
36 When a user runs CMake it performs a variety of checks similar to how autoconf
38 description scripts CMake caches values into the CMakeCache. This is useful
40 incremental development. CMake caching also has some drawbacks, but that will be
46 CMake's scripting language has a very simple grammar. Every language construct
48 primary types: language-defined (commands implemented in C++ in CMake), defined
49 functions, and defined macros. The CMake distribution also contains a suite of
50 CMake modules that contain definitions for useful functionality.
52 The example below is the full CMake build for building a C++ "Hello World"
53 program. The example uses only CMake language-defined functions.
55 .. code-block:: cmake
61 The CMake language provides control flow constructs in the form of foreach loops
65 .. code-block:: cmake
80 In CMake variables are "stringly" typed. All variables are represented as
82 and results in a literal substitution of the name for the value. CMake refers to
91 .. code-block:: cmake
98 pattern in CMake to conditionally set variables knowing that it will be used in
100 the LLVM CMake build system.
104 .. code-block:: cmake
118 .. code-block:: cmake
127 .. code-block:: cmake
132 pattern is uncommon, but it does occur in LLVM's CMake scripts.
136 Once the LLVM project upgrades its minimum CMake version to 3.1 or later we
138 CMake policies please see the cmake-policies manpage or the `cmake-policies
140 <https://cmake.org/cmake/help/v3.4/manual/cmake-policies.7.html>`_.
145 In CMake lists are semi-colon delimited strings, and it is strongly advised that
149 .. code-block:: cmake
161 One of the more complicated patterns in CMake is lists of lists. Because a list
165 .. code-block:: cmake
175 .. code-block:: cmake
188 This pattern is used throughout CMake, the most common example is the compiler
189 flags options, which CMake refers to using the following variable expansions:
196 associated with them. The variable's type is used by CMake's UI tool to display
198 One of the few examples is PATH variables, which CMake does have some special
199 handling for. You can read more about the special handling in `CMake's set
201 <https://cmake.org/cmake/help/v3.5/command/set.html#set-cache-entry>`_.
206 CMake inherently has a directory-based scoping. Setting a variable in a
208 Variables set in a CMake module that is included in a CMakeLists file will be
214 The CMake set command provides two scope-related options. PARENT_SCOPE sets a
220 In addition to directory-based scope, CMake functions also have their own scope.
226 Unlike C-based languages, CMake's loop and control flow blocks do not have
232 CMake features the same basic control flow constructs you would expect in any
234 CMake, control flow constructs are commands.
240 For the full documentation on the CMake if command go
241 `here <https://cmake.org/cmake/help/v3.4/command/if.html>`_. That resource is
244 In general CMake if blocks work the way you'd expect:
246 .. code-block:: cmake
256 The single most important thing to know about CMake's if blocks coming from a C
263 The most common form of the CMake ``foreach`` block is:
265 .. code-block:: cmake
274 .. code-block:: cmake
302 There is also a more modern CMake foreach syntax. The code below is equivalent
305 .. code-block:: cmake
336 CMake also supports ``while`` loops, although they are not widely used in LLVM.
344 Modules are CMake's vehicle for enabling code reuse. CMake modules are just
345 CMake script files. They can contain code to execute on include as well as
348 In CMake macros and functions are universally referred to as commands, and they
351 In LLVM we have several CMake modules that are included as part of our
354 CMake. We also rely on modules as a way of organizing the build system's
360 When defining a CMake command handling arguments is very useful. The examples
361 in this section will all use the CMake ``function`` block, but this all applies
364 CMake commands can have named arguments, but all commands are implicitly
367 wrapper function for CMake's built in function ``add_dependencies``.
369 .. code-block:: cmake
377 all trailing arguments. When variable arguments are present CMake defines them
380 CMake provides a module ``CMakeParseArguments`` which provides an implementation
383 arguments. CMake's official documentation for the module is in the
384 ``cmake-modules`` manpage, and is also available at the
385 `cmake-modules online documentation
386 <https://cmake.org/cmake/help/v3.4/module/CMakeParseArguments.html>`_.
389 As of CMake 3.5 the cmake_parse_arguments command has become a native command
402 The other difference between CMake functions and macros is how arguments are
407 .. code-block:: cmake
431 LLVM projects provide lots of wrappers around critical CMake built-in commands.
440 all defined in ``AddLLVM.cmake`` which is installed as part of the LLVM
453 CMake has a bunch of useful built-in commands. This document isn't going to
454 go into details about them because The CMake project has excellent
457 * `add_custom_command <https://cmake.org/cmake/help/v3.4/command/add_custom_command.html>`_
458 * `add_custom_target <https://cmake.org/cmake/help/v3.4/command/add_custom_target.html>`_
459 * `file <https://cmake.org/cmake/help/v3.4/command/file.html>`_
460 * `list <https://cmake.org/cmake/help/v3.4/command/list.html>`_
461 * `math <https://cmake.org/cmake/help/v3.4/command/math.html>`_
462 * `string <https://cmake.org/cmake/help/v3.4/command/string.html>`_
464 The full documentation for CMake commands is in the ``cmake-commands`` manpage
465 and available on `CMake's website <https://cmake.org/cmake/help/v3.4/manual/cmake-commands.7.html>`_