1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
# Unofficial Qt CMake Coding Style
CMake scripts are a bit of a wild west. Depending on when the code was written, there were
different conventions as well as syntax facilities available. It's also unfortunate that there is
no agreed upon CMake code formatter similar to clang-format.
https://github.com/cheshirekow/cmake_format exists, but appears abandoned. We might look into
using it at some point.
It's hard to convince people to use a certain code style for a language like CMake.
Nevertheless this short document aims to be a guideline for formatting CMake code within the Qt
project.
## Common conventions
* When in doubt, prefer the local code conventions of the function or file you are editing.
* Prefer functions over macros (macros have certain problems with parameter escaping)
* Prefix macro local variables to avoid naming collisions
## Case Styles
For CMake identifiers we refer to following case styles in the text below.
| Case style name | Example identifier |
|-------------------|----------------------------|
| Snake case | `moc_options` |
| Shouty case | `INTERFACE_LINK_LIBRARIES` |
| Pascal case | `QmlModels` |
## Indentation
* When in doubt, follow local indentation
* Prefer indenting with 4 spaces, e.g.
```
if(1)
if(2)
message("3")
endif()
endif()
```
## Variables
* local variables inside a function should be snake cased => `list_of_arguments`
* local variables inside a macro should be snake cased and have a unique prefix =>
`__qt_list_of_packages`
* If your macro is recursively called, you might need to prepend a dynamically computed prefix
to avoid overriding the same variable in nested calls =>
`__qt_${dependency_name}_list_of_packages`
* cache variables should be shouty cased => `BUILD_SHARED_LIBS`
* Qt cache variables should be prefixed with `QT_`
## Properties
Currently the Qt property naming is a bit of a mess. The upstream issue
https://gitlab.kitware.com/cmake/cmake/-/issues/19261 mentions that properties prefixed with
`INTERFACE_` are reserved for CMake use.
Prefer to use snake case for new property names.
* Most upstream CMake properties are shouty cased => `INTERFACE_LINK_LIBRARIES`
* Properties created in Qt 5 times follow the same CMake convention => `QT_ENABLED_PUBLIC_FEATURES`
No such new properties should be added.
* New Qt properties should be snake cased and prefixed with `qt_` => `qt_qmake_module_name`
* Other internal Qt properties should be snake cased and prefixed with `_qt_` => `_qt_target_deps`
## Functions
* Function names should be snake cased => `qt_add_module`
* public Qt functions should be prefixed with `qt_`
* internal Qt functions should be prefixed with `qt_internal_`
* internal Qt functions that live in public CMake API files should be prefixed with
`_qt_internal_`
* some internal functions that live in public CMake API files are prefixed with
`__qt_internal_`, prefer not to introduce such functions for now
* If a public function takes more than 1 parameter, consider using `cmake_parse_arguments`
* If an internal Qt function takes more than 1 parameter, consider using `qt_parse_all_arguments`
* Public functions should usually have both a version-full and version-less name => `qt_add_plugin`
and `qt6_add_plugin`
### Macros
* Try to avoid macros where a function can be used instead
* A common case when a macro can not be avoided is when it wraps a CMake macro e.g
`find_package` => `qt_find_package`
* Macro names should be snake cased => `qt_find_package`
* Prefix macro local variables to avoid naming collisions => `__qt_find_package_arguments`
## Commands
Command names in CMake are case-insensitive, therefore:
* Only use lower case command names e.g `add_executable(app main.cpp)` not `ADD_EXECUTABLE(app
main.cpp)`
* Command flags / options are usually shouty cased => `file(GENERATE OUTPUT "foo" CONTENT "bar")`
## 'If' command
* Keep the parenthesis next to the `if()`, so don't write `if ()`. `if` is a command name and like
other command names e.g. `find_package(foo bar)` the parenethesis are next to the name.
* To check that a variable is an empty string (and not just a falsy value, think Javascript's
`foo === ""`) use the following snippet
```
if(var_name STREQUAL "")
message("${var_name}")
endif()
```
If you are not sure if the variable is defined, make sure to evaluate the variable name
```
if("${var_name}" STREQUAL "")
message("${var_name}")
endif()
```
* Falsy values are `0`, `OFF`, `NO`, `FALSE`, `N`, `IGNORE`, `NOTFOUND`, the empty string `""`, or
a string ending in `-NOTFOUND`. To check that a variable is NOT falsy use the first suggested
code snippet
```
# Nice and clean
if(var_name)
message("${var_name}")
endif()
# Wrong, can lead to problems due to double variable evaluation
if(${var_name})
message("${var_name}")
endif()
# Incorrect if you want to check for all falsy values. This only checks for string emptiness.
if("${var_name}" STREQUAL "")
message("${var_name}")
endif()
```
* To check if a variable is defined, use
```
if(DEFINED var_name)
endif()
```
* To compare a defined variable's contents to a string, use
```
if(var_name STREQUAL "my_string")
endif()
```
* To compare a defined variable's contents to another defined variable's contents, use
```
if(var_name STREQUAL var_name_2)
endif()
```
* To compare a possibly undefined variable make sure to explicitly evaluate it first
```
if("${var_name}" STREQUAL "my_string")
endif()
if("${var_name}" STREQUAL "${var_name_2}")
endif()
```
## find_package
* Inside Qt module projects, use the private Qt-specific `qt_find_package` macro to look for
dependencies.
* Make sure to specify the `PROVIDED_TARGETS` option to properly register 3rd party target
dependencies with Qt's internal build system.
* Inside examples / projects (which only use public CMake API) use the regular `find_package`
command.
## CMake Target names
* Qt target names should be pascal cased => `QuickParticles`.
* When Qt is installed, the Qt CMake targets are put inside the `Qt6::` namespace. Associated
versionless targets in the `Qt::` namespace are usually automatically created by appropriate
functions (`qt_internal_add_module`, `qt_internal_add_tool`)
* Wrapper 3rd party system libraries usually repeat the target name as the namespace e.g.
```WrapSystemHarfbuzz::WrapSystemHarfbuzz```
## Finding 3rd party libraries via Find modules (FindWrapFoo.cmake)
qmake-Qt uses `configure.json` and `configure.pri` and `QT_LIBS_FOO` variables to implement a
mechnism that searches for system 3rd party libraries.
The equivalent CMake mechanism are Find modules (and CMake package Config files; not to be confused
with pkg-config). Usually Qt provides wrapper Find modules that use any available upstream Find
modules or Config package files.
The naming convention for the files are:
* `FindWrapFoo.cmake` => `FindWrapPCRE2.cmake`
* `FindWrapSystemFoo.cmake` => `FindWrapSystemPCRE2.cmake`
|
