Debian Codegraph @

cmake/tribits/doc/guides/TribitsCMakeLanguageOverviewAndGotchas.rst

raw
1 CMake Language Overview and Gotchas
2 -----------------------------------
3
4 TriBITS removes a lot of the boiler plate code needed to write a CMake
5 project. As a result, many people can come into a project that uses TriBITS
6 and quickly start to contribute by adding new source files, adding new
7 libraries, adding new tests, and even adding new TriBITS packages and external
8 packages/TPLs; all without really having learned anything about CMake. Often
9 one can use existing example CMake code as a guide and be successful using
10 basic functionality. As long as nothing out of the ordinary happens, many
11 people can get along just fine in this mode for a time.
12
13 However, we have observed that most mistakes and problems that people run into when
14 using TriBITS are due to lack of basic knowledge of the CMake language. One can find
15 basic tutorials and references on the CMake language in various locations online for free.
16 One can also purchase the `official CMake reference book`_. Also, documentation
17 for any built-in CMake command is available locally by running::
18
19 $ cmake --help-command <CMAKE_COMMAND>
20
21 Because tutorials and detailed documentation for the CMake language already
22 exists, this document does not attempt to provide a first reference to CMake
23 (which is a large topic in itself). However, what we try to provide below is
24 a short overview of the more quirky or surprising aspects of the CMake
25 language that a programmer experienced in another language might get tripped
26 up or surprised by. Some of the more unique features of the language are
27 described in order to help avoid some of these common mistakes and provide
28 greater understanding of how TriBITS works.
29
30 .. _Official CMake reference book: http://www.cmake.org/cmake/help/book.html
31
32 The CMake language is used to write CMake projects with TriBITS. In fact the
33 core TriBITS functionality itself is implemented in the CMake language (see
34 `TriBITS System Project Dependencies`_). CMake is a fairly simple programming
35 language with relatively simple rules (for the most part). However, compared
36 to other programming languages, there are a few peculiar aspects to the CMake
37 language that can make working with it difficult if you don't understand these
38 rules. For example there are unexpected variable scoping rules and how arguments
39 are passed to macros and functions can be tricky. Also, CMake has some interesting
40 gotchas. In order to effectively use TriBITS (or just raw CMake) to construct
41 and maintain a project's CMake files, one must know the basic rules of CMake
42 and be aware of these gotchas.
43
44 The first thing to understand about the CMake language is that nearly every
45 line of CMake code is just a command taking a string (or an array of strings)
46 and functions that operate on strings. An array argument is just a single
47 string literal with elements separated by semi-colons ``"<str0>;<str1>;..."``.
48 CMake is a bit odd in how it deals with these arrays, which are just
49 represented as a string with elements separated with semi-colons ``';'``. For
50 example, all of the following are equivalent and pass in a CMake array with 3
51 elements [``A``], [``B``], and [``C``]::
52
53 some_func(A B C)
54 some_func("A" "B" "C")
55 some_func("A;B;C")
56
57 However, the above is *not* the same as::
58
59 some_func("A B C")
60
61 which just passes in a single element with value [``A B C``]. Raw quotes in
62 CMake basically escape the interpretation of space characters as array element
63 boundaries. Quotes around arguments with no spaces does nothing (as seen
64 above, except for the interpretation as variable names in an ``if()``
65 statement). In order to get a quote char [``"``] into string, you must escape
66 it as::
67
68 some_func(\"A\")
69
70 which passes an array with the single argument [``\"A\"``].
71
72 Variables are set using the built-in CMake ``set()`` command that just takes
73 string arguments like::
74
75 set(SOME_VARIABLE "some_value")
76
77 In CMake, the above is identical, in every way, to::
78
79 set(SOME_VARIABLE some_value)
80 set("SOME_VARIABLE";"some_value")
81 set("SOME_VARIABLE;some_value")
82
83 The function ``set()`` simply interprets the first argument to as the name of
84 a variable to set in the local scope. Many other built-in and user-defined
85 CMake functions work the same way. That is, some of the string arguments are
86 interpreted as the names of variables. There is no special language feature
87 that interprets them as variables (except in an ``if()`` statement).
88
89 However, CMake appears to parse arguments differently for built-in CMake
90 control structure functions like ``foreach()`` and ``if()`` and does not just
91 interpret them as a string array. For example::
92
93 foreach (SOME_VAR "a;b;c")
94 message("SOME_VAR='${SOME_VAR}'")
95 endforeach()
96
97 prints ```SOME_VAR='a;b;c'`` instead of printing ``SOME_VAR='a'`` followed by
98 ``SOME_VAR='b'``, etc., as you would otherwise expect. Therefore, this simple
99 rule for the handling of function arguments as string arrays does not hold for
100 CMake logic control commands. Just follow the CMake documentation for these
101 control structures (i.e. see ``cmake --help-command if`` and ``cmake
102 --help-command foreach``).
103
104 CMake offers a rich assortment of built-in commands for doing all sorts of
105 things. Two of these are the built-in ``macro()`` and the ``function()``
106 commands which allow you to create user-defined macros and functions. TriBITS
107 is actually built on CMake functions and macros. All of the built-in and
108 user-defined macros, and some functions take an array of string arguments.
109 Some functions take in positional arguments. In fact, most functions take a
110 combination of positional and keyword arguments.
111
112 Variable names are translated into their stored values using
113 ``${SOME_VARIABLE}``. The value that is extracted depends on if the variable
114 is set in the local or global (cache) scope. The local scopes for CMake start
115 in the base project directory in its base ``CMakeLists.txt`` file. Any
116 variables that are created by macros in that base local scope are seen across
117 an entire project but are *not* persistent across multiple successive
118 ``cmake`` configure invocations where the cache file ``CMakeCache.txt`` is not
119 deleted in between.
120
121 The handling of variables is one area where CMake is radically different from
122 most other languages. First, a variable that is not defined simply returns
123 nothing. What is surprising to most people about this is that it does not
124 even return an empty string that would register as an array element! For
125 example, the following set statement::
126
127 set(SOME_VAR a ${SOME_UNDEFINED_VAR} c)
128
129 (where ``SOME_UNDEFINED_VAR`` is an undefined variable) produces
130 ``SOME_VAR='a;c'`` and *not* ``'a;;c'``! The same thing occurs when an empty
131 variable is de-references such as with::
132
133 set(EMPTY_VAR "")
134 set(SOME_VAR a ${EMPTY_VAR} c)
135
136 which produces ``SOME_VAR='a;c'`` and *not* ``'a;;c'``. In order to always
137 produce an element in the array even if the variable is empty, one must quote
138 the argument as with::
139
140 set(EMPTY_VAR "")
141 set(SOME_VAR a "${EMPTY_VAR}" c)
142
143 which produces ``SOME_VAR='a;;c'``, or three elements as one might assume.
144
145 This is a common error that people make when they call CMake functions
146 (built-in or TriBITS-defined) involving variables that might be undefined or
147 empty. For example, for the macro::
148
149 macro(some_macro A_ARG B_ARG C_ARG)
150 ...
151 endmacro()
152
153 if someone tries to call it with (misspelled variable?)::
154
155 some_macro(a ${SOME_OHTER_VAR} c)
156
157 and if ``SOME_OHTER_VAR=""`` or if it is undefined, then CMake will error out
158 with the error message saying that the macro ``some_macro()`` takes 3
159 arguments but only 2 were provided. If a variable might be empty but that is
160 still a valid argument to the command, then it must be quoted as::
161
162 some_macro(a "${SOME_OHTER_VAR}" c)
163
164 Related to this problem is that if you misspell the name of a variable in a
165 CMake ``if()`` statement like::
166
167 if (SOME_VARBLE)
168 ...
169 endif()
170
171 then it will always be false and the code inside the if statement will never
172 be executed! To avoid this problem, use the utility function
173 `assert_defined()`_ as::
174
175 assert_defined(SOME_VARBLE)
176 if (SOME_VARBLE)
177 ...
178 endif()
179
180 In this case, the misspelled variable would be caught.
181
182 While on the subject of ``if()`` statements, CMake has a strange convention.
183 When you say::
184
185 if (SOME_VAR)
186 do_something()
187 endif()
188
189 then ``SOME_VAR`` is interpreted as a variable and will be considered true and
190 ``do_something()`` will be called if ``${SOME_VAR}`` does *not* evaluate to
191 ``0``, ``OFF``, ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``""``, or ends in the
192 suffix ``-NOTFOUND``. How about that for a true/false rule! To be safe, use
193 ``ON/OFF`` and ``TRUE/FALSE`` pairs for setting variables. Look up native
194 CMake documentation on ``if()`` for all the interesting details and all the
195 magical things it can do.
196
197 **WARNING:** If you mistype ``"ON"`` as ``"NO"``, it evaluates to
198 ``FALSE``/``OFF``! (That is a fun defect to track down!)
199
200 CMake language behavior with respect to case sensitivity is also strange:
201
202 * Calls of built-in and user-defined macros and functions is *case
203 insensitive*! That is ``set(...)``, ``set(...)``, ``set()``, and all other
204 combinations of upper and lower case characters for 'S', 'E', 'T' all call
205 the built-in ``set()`` function. The convention in TriBITS is to use
206 ``lower_case_with_underscores()`` for functions and macros.
207
208 * However, the names of CMake (local or cache/global) variables are *case
209 sensitive*! That is, ``SOME_VAR`` and ``some_var`` are *different*
210 variables. Built-in CMake variables tend use all caps with underscores
211 (e.g. ``CMAKE_CURRENT_SOURCE_DIR``) but other built-in CMake variables tend
212 to use mixed case with underscores (e.g. ``CMAKE_Fortran_FLAGS``). TriBITS
213 tends to use a similar naming convention where project-level and cache
214 variables have mostly upper-case letters except for parts that are proper
215 nouns like the project, package or external package/TPL name
216 (e.g. ``TribitsExProj_TRIBITS_DIR``, ``TriBITS_SOURCE_DIR``,
217 ``Boost_INCLUDE_DIRS``). Local variables and function/macro parameters can
218 use camelCase or lower_case_with_underscores.
219
220 I don't know of any other programming language that uses different case
221 sensitivity rules for variables and functions. However, because we must parse
222 macro and function arguments when writing user-defined macros and functions,
223 it is a good thing that CMake variables are case sensitive. Case insensitivity
224 would make it much harder and more expensive to parse argument lists that take
225 keyword-based arguments.
226
227 Other mistakes that people make result from not understanding how CMake scopes
228 variables and other entities. CMake defines a global scope (i.e. "cache"
229 variables) and several nested local scopes that are created by
230 ``add_subdirectory()`` and entering functions. See `dual_scope_set()`_ for a
231 short discussion of these scoping rules. And it is not just variables that
232 can have local and global scoping rules. Other entities, like defines set
233 with the built-in command ``add_definitions()`` only apply to the local scope
234 and child scopes. That means that if you call ``add_definitions()`` to set a
235 define that affects the meaning of a header-file in C or C++, for example,
236 that definition will *not* carry over to a peer subdirectory and those
237 definitions will not be set (see warning in `Miscellaneous Notes
238 (tribits_add_library())`_).