C++ Utilities  4.15.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
doc/buildvariables.md
Go to the documentation of this file.
1 # Build system
2 
3 \brief Documents variables to control the build system and provided CMake
4  modules
5 
6 ## Variables passable as CMake arguments
7 
8 ### Useful variables provided by CMake itself
9 * `CMAKE_INSTALL_PREFIX=path`: specifies the final install prefix (temporary
10  install prefix is set via `make` argument `DESTDIR=path`)
11 * `CMAKE_BUILD_TYPE=Release/Debug`: specifies whether to do a debug or a release
12  build
13 * `CMAKE_SKIP_BUILD_RPATH=OFF`: ensures the rpath is set in the build tree
14 * `CMAKE_INSTALL_RPATH=rpath`: sets the rpath used when installing
15 * `CMAKE_CXX_FLAGS`: sets flags to be passed to the C++ compiler
16 
17 ### Custom variables
18 The following variables are read by the CMake modules provided by c++utilities
19 and qtutilities.
20 
21 None of these are enabled or set by default, unless stated otherwise.
22 
23 * `LIB_SUFFIX=suffix`: suffix for library install directory
24 * `LIB_SUFFIX_32=suffix`: suffix for library install directory
25  * used when building for 32-bit platforms
26  * overrides general `LIB_SUFFIX` when building for 32-bit platforms
27 * `LIB_SUFFIX_64=suffix`: suffix for library install directory
28  * used when building for 64-bit platforms
29  * overrides general `LIB_SUFFIX` when building for 64-bit platforms
30 * `ENABLE_STATIC_LIBS=ON/OFF`: enables building static libs
31 * `DISABLE_SHARED_LIBS=ON/OFF`: disables building shared libs
32 * `STATIC_LINKAGE=ON/OFF`: enables linking applications *preferably* against
33  static libraries
34  * by default dynamic libraries are preferred
35  * only affect building applications
36 * `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries *preferably*
37  against static libraries
38  * by default linking against dynamic libraries is preferred
39  * only affects building dynamic libraries (static libraries are just archives
40  of objects and hence *not linked* against their dependencies when being built)
41  * note that static libraries are always preferred to provide the dependency
42  of another static library
43  * eg. linking against static `c++utilities` requires also linking against
44  its dependency `iconv`; the static version of `iconv` is preferred
45  * this behaviour has actually nothing to do with `STATIC_LIBRARY_LINKAGE`
46  and can currently not be controlled
47 * `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
48  (enabled by default)
49 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
50  default)
51 * `LOGGING_ENABLED=ON/OFF`: enables further loggin in some applications
52 * `FORCE_OLD_ABI=ON/OFF`: forces use of old C++ ABI
53  * sets `_GLIBCXX_USE_CXX11_ABI=0`
54  * only relevant when using libstdc++
55 * `EXCLUDE_TESTS_FROM_ALL=ON/OFF`: excludes tests from the all target
56  (enabled by default)
57 * `APPEND_GIT_REVISION=ON/OFF`: whether the build script should attempt to
58  append the Git revision and the latest commit ID to the version
59  * displayed via `--help`
60  * enabled by default but has no effect when the source directory is
61  no Git checkout or Git is not installed
62 * `CLANG_FORMAT_ENABLED=ON/OFF`: enables tidy target for code formatting via
63  `clang-format`
64  * can be made unavailable by setting `META_NO_TIDY` in the project file
65  * only available if format rules are available
66  * also enables tidy check executed via `check` target
67 * `CLANG_TIDY_ENABLED=ON/OFF`: enables target `static-check` for static code
68  analysis with `clang-tidy`
69  * can be made unavailable by setting `META_NO_STATIC_ANALYSIS` in the
70  project file
71 * `CLANG_SOURCE_BASED_COVERAGE_ENABLED=ON/OFF`: enables `coverage` target to
72  determine source-based test coverage using Clang/llvm
73  * only available when building with Clang under UNIX
74  * coverage report is stored in build directory
75 * `ENABLE_INSTALL_TARGETS=ON/OFF`: enables creation of install targets (enabled
76  by default)
77 * `ENABLE_ESCAPE_CODES_BY_DEAULT`: enables use of escape codes for formatted
78  output by default
79  * enabled by default
80  * see ApplicationUtilities::NoColorArgument and EscapeCodes::enabled
81  * has to be set when building `c++utilities`; projects using that build of
82  `c++utilities` will then use this default
83 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native functions to open file streams
84  * Allows opening files which have non-ASCII in the path under Windows.
85  * Allows to use native file descriptors which is required to open files
86  from URLs provided by Android's Storage Access Framework.
87  * Changing this option alters the ABI of `c++utilities` and other libraries
88  exposing that ABI (eg. `tagparser` and `passwordfile`).
89  * This feature is implemented in `c++utilities`, so the option must be specified
90  when building `c++utilities`. Specifying it only when building eg. `tagparser`
91  has *no* effect.
92 
93 #### Variables for specifying location of 3rd party dependencies
94 The build script tries to find the required dependencies at standard loctions
95 using the CMake functions
96 [`find_library`](https://cmake.org/cmake/help/latest/command/find_library.html)
97 and
98 [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html).
99 The behaviour of those functions can be controlled by setting some variables, eg.
100 using a toolchain file. Checkout the CMake documentation for this.
101 
102 If the detection does not work as expected or a library from a non-standard
103 location should be used, the following variables can be used to specify
104 the location of libraries and include directories directly:
105 
106 * `dependency_DYNAMIC_LIB`: specifies the locations of the dynamic libraries
107  for *dependency*
108 * `dependency_STATIC_LIB`: specifies the locations of the static libraries
109  for *dependency*
110 * `dependency_DYNAMIC_INCLUDE_DIR`: specifies the locations of the additional
111  include directories required for using the dynamic version of the *dependency*
112 * `dependency_STATIC_INCLUDE_DIR`: specifies the locations of the additional
113  include directories required for using the static version of the *dependency*
114 
115 *Note about Qt*: Qt modules are always configured using the CMake packages via
116 `find_package`. So using the variables described above to specify a custom location
117 does not work. Instead, the variables `CMAKE_FIND_ROOT_PATH` or `CMAKE_PREFIX_PATH`
118 can be used to specify the install prefix of the Qt build to use. Set `QT_LINKAGE`
119 to `STATIC` if it is a static build of Qt.
120 
121 ##### Examples
122 Example of passing location of dynamic `iconv` and `zlib` to CMake:
123 ```
124 /opt/osxcross/bin/x86_64-apple-darwin15-cmake \
125  -Diconv_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libiconv.2.tbd \
126  -Diconv_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
127  -Dz_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libz.1.tbd \
128  -Dz_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
129  ...
130 ```
131 
132 Here's an example of passing the location of the Android SDK/NDK to compile for Android.
133 This time the `iconv` library is located by specifying its install prefix via
134 `CMAKE_FIND_ROOT_PATH`. The include directories are not automatically added for that
135 library, so this must still be done manually:
136 ```
137 _android_arch=arm64-v8a
138 cmake \
139  -DCMAKE_SYSTEM_NAME=Android \
140  -DCMAKE_SYSTEM_VERSION=21 \
141  -DCMAKE_ANDROID_ARCH_ABI=$_android_arch \
142  -DCMAKE_ANDROID_NDK=/opt/android-ndk \
143  -DCMAKE_ANDROID_SDK=/opt/android-sdk \
144  -DCMAKE_ANDROID_STL_TYPE=gnustl_shared \
145  -DCMAKE_INSTALL_PREFIX=/opt/android-libs/$_android_arch \
146  -DCMAKE_FIND_ROOT_PATH="/opt/android-ndk/sysroot;/opt/android-libs/$_android_arch" \
147  -Diconv_DYNAMIC_INCLUDE_DIR="/opt/android-libs/$_android_arch/include" \
148  -Diconv_STATIC_INCLUDE_DIR="/opt/android-libs/$_android_arch/include" \
149  ...
150 ```
151 
152 #### Windows specific
153 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
154 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
155  application meta data and icon (enabled by default)
156 
157 #### MacOS specific
158 * `BUNDLE_INSTALL_DESTINATION=/some/path`: specifies the install destination for
159  application bundles; if not specified, the default bin directory is used
160 
161 #### Qt specific
162 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
163  available and optional
164 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
165  and optional
166 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
167 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
168  built-in
169 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
170  also affects libraries
171 * `SVG_SUPPORT=ON/OFF`: enables linking against the static SVG image format
172  plugin
173  * enabled by default
174  * requires the Qt Svg module
175  * only relevant when using static Qt
176 * `SVG_ICON_SUPPORT=ON/OFF`: enables linking against the static SVG icon engine
177  plugin provided by the Qt Svg module
178  * enabled by default
179  * requires the Qt Svg module
180  * only relevant when using static Qt
181  * required to use Breeze icon theme (or any other SVG icon theme)
182 * `IMAGE_FORMAT_SUPPORT`: enables linking against the specified static image
183  format plugins
184  * comma-separated list
185  * by default set to "Gif;ICO;Jpeg", so support for Gif, ICO and Jpeg is
186  enabled by default
187  * note that PNG support is not provided via a plugin, so it should be
188  always available and not be affected by this option
189  * further image formats require building the plugins contained by the
190  additional `qtimageformats` repository
191  * only relevant when using static Qt
192 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
193  for the web view
194 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
195  for the JavaScript engine
196 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
197  or shared version of Qt (only works with Qt packages provided in the AUR)
198 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
199  modules to link against (only use for modules which can not be added
200  automatically)
201 
202 
203 ## Variables to be set in project file
204 The following variables are read by the CMake modules provided by c++utilities
205 and qtutilities.
206 
207 ### Meta data
208 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
209  application/library name, mustn't contain spaces
210 * `META_APP_NAME=The Name`: specifies a more readible version of the project
211  name used for instance in about dialog and desktop file
212 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
213  dialog
214 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
215  dialog and desktop file
216 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
217 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
218  version, default is 0
219 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
220  to build an application, a library or a plugin
221 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
222 * `META_NO_TIDY`: disables availability of enabling formatting via
223  `CLANG_FORMAT_ENABLED` for this project
224 * `META_NO_INSTALL_TARGETS`: the project is not meant to be installed, eg.
225  private test helper; prevents creation of install targets
226 
227 ### Files
228 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
229 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
230  tests
231 * `TS_FILES`: specifies Qt translations
232 * `RES_FILES`: specifies Qt resource files
233 * `DBUS_FILES`: specifies files for Qt DBus
234 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
235  only required for Qt Widgets GUI
236 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
237  header/source files and Qt resouce files only required for Qt Quick GUI
238 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
239  created via Doxygen; the first file is used as the main page
240 * `DOC_ONLY_FILES`: specifies documentation-only files
241 * `REQUIRED_ICONS`: names of the icons required by the application and the
242  used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
243 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
244  provides by the project; those files are installed so they can be used by
245  other projects
246 
247 ### Additional build variables
248 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
249  definitions
250 * `LIBRARIES`: specifies libraries to link against
251 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
252  interface
253 * `META_PUBLIC_SHARED_LIB_DEPENDS`: specifies shared libraries used in the public
254  library interface
255 * `META_PUBLIC_STATIC_LIB_DEPENDS`: specifies static libraries used in the public
256  library interface
257 
258 ## Provided modules
259 c++utilities and qtutilities provide CMake modules to reduce boilerplate code
260 in the CMake files of my projects. Those modules implement the functionality
261 controlled by the variables documented above. Most important modules are:
262 
263 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
264 * `QtConfig`: does basic Qt-related configuration, reads most of the Qt-specific
265  variables documented above
266 * `QtGuiConfig`: does Qt-related configuration for building a Qt Widgets or
267  Qt Quick based GUI application/library
268  * must be included *before* `QtConfig`
269 * `WebViewProviderConfig`: configures the webview provider
270  * used by Tag Editor and Syncthing Tray to select between Qt WebEngine,
271  Qt WebKit or disabling the built-in webview
272 * `LibraryTarget`: does further configuration for building dynamic and static
273  libraries and plugins; `META_PROJECT_TYPE` can be left empty or set explicitely
274  to `library`
275 * `AppTarget`: does further configuration for building an application;
276  `META_PROJECT_TYPE` must be set to `application`
277 * `ShellCompletion`: enables shell completion
278  * only works when using the argument parser provided by the
279  `ApplicationUtilities::ArgumentParser` class of course
280 * `TestTarget`: adds the test target `check`
281  * `check` target is *not* required by target `all`
282  * test target uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES`
283  variables
284  * test target will automatically link against `cppunit` which is the test
285  framework used by all my projects; set `META_NO_CPP_UNIT=OFF` in the project
286  file to prevent this
287 * `AndroidApk`: adds a target to create an APK package for Android using
288  androiddeployqt
289 * `Doxygen`: adds a target to generate documentation using Doxygen
290 * `WindowsResources`: handles creation of Windows resources to set application
291  meta data and icon, ignored on other platforms
292 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
293  module (when all configuration is done)
294 
295 Since those modules make use of the variables explained above, the modules must
296 be included *after* setting those variables. The inclusion order of the modules
297 matters as well.
298 
299 For an example, checkout the project file of c++utilities itself. The project
300 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
301 cover everything (library, plugin, application, tests, desktop file, Qt
302 resources and translations, ...).