| 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())`_). |