3 \brief Documents variables to control the build system and provided CMake
6 ## Variables passable as CMake arguments
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
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
17 The following variables are read by the CMake modules provided by c++utilities
20 None of these are enabled or set by default, unless stated otherwise.
22 * `LIB_SUFFIX=suffix`: suffix for library install directory
23 * `LIB_SUFFIX_32=suffix`: suffix for library install directory
24 * used when building for 32-bit platforms
25 * overrides general `LIB_SUFFIX` when building for 32-bit platforms
26 * `LIB_SUFFIX_64=suffix`: suffix for library install directory
27 * used when building for 64-bit platforms
28 * overrides general `LIB_SUFFIX` when building for 64-bit platforms
29 * `ENABLE_STATIC_LIBS=ON/OFF`: enables building static libs
30 * `DISABLE_SHARED_LIBS=ON/OFF`: disables building shared libs
31 * `STATIC_LINKAGE=ON/OFF`: enables linking applications *preferably* against
33 * by default dynamic libraries are preferred
34 * only affect building applications
35 * `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries *preferably*
36 against static libraries
37 * by default linking against dynamic libraries is preferred
38 * only affects building dynamic libraries
39 * `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
41 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
43 * `LOGGING_ENABLED=ON/OFF`: enables further loggin in some applications
44 * `FORCE_OLD_ABI=ON/OFF`: forces use of old C++ ABI
45 * sets `_GLIBCXX_USE_CXX11_ABI=0`
46 * only relevant when using libstdc++
47 * `EXCLUDE_TESTS_FROM_ALL=ON/OFF`: excludes tests from the all target
49 * `APPEND_GIT_REVISION=ON/OFF`: whether the build script should attempt to
50 append the Git revision and the latest commit ID to the version
51 * displayed via --help
52 * enabled by default but has no effect when the source directory is
53 no Git checkout or Git is not installed
54 * `CLANG_FORMAT_ENABLED=ON/OFF`: enables tidy target for code formatting via
56 * can be made unavailable by setting `META_NO_TIDY` in the project file
57 * only available if format rules are available
58 * also enables tidy check executed via `check` target
59 * `CLANG_SOURCE_BASED_COVERAGE_ENABLED=ON/OFF`: enables `coverage` target to
60 determine source-based test coverage using Clang/llvm
61 * only available when building with Clang under UNIX
62 * coverage report is stored in build directory
63 * `ENABLE_INSTALL_TARGETS=ON/OFF`: enables creation of install targets (enabled
67 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
68 to pass unicode file names correctly, changing this alters ABI
69 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
70 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
71 application meta data and icon (enabled by default)
74 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
75 available and optional
76 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
78 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
79 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
81 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
82 also affects libraries
83 * `SVG_SUPPORT=ON/OFF`: enables SVG support if not enabled anyways by the
85 * `SVG_ICON_SUPPORT=ON/OFF`: enables SVG icon support (only affect static
86 builds where the required Qt plugin will be built-in if this variable is
88 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
90 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
91 for the JavaScript engine
92 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
93 or shared version of Qt (only works with Qt packages provided in the AUR)
94 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
95 modules to link against (only use for modules which can not be added
99 ## Variables to be set in project file
100 The following variables are read by the CMake modules provided by c++utilities
104 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
105 application/library name, mustn't contain spaces
106 * `META_APP_NAME=The Name`: specifies a more readible version of the project
107 name used for instance in about dialog and desktop file
108 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
110 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
111 dialog and desktop file
112 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
113 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
114 version, default is 0
115 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
116 to build an application, a library or a plugin
117 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
118 * `META_NO_TIDY`: disables availability of enabling formatting via
119 `CLANG_FORMAT_ENABLED` for this project
120 * `META_NO_INSTALL_TARGETS`: the project is not meant to be installed, eg.
121 private test helper; prevents creation of install targets
124 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
125 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
127 * `TS_FILES`: specifies Qt translations
128 * `RES_FILES`: specifies Qt resource files
129 * `DBUS_FILES`: specifies files for Qt DBus
130 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
131 only required for Qt Widgets GUI
132 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
133 header/source files and Qt resouce files only required for Qt Quick GUI
134 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
135 created via Doxygen; the first file is used as the main page
136 * `DOC_ONLY_FILES`: specifies documentation-only files
137 * `REQUIRED_ICONS`: names of the icons required by the application and the
138 used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
139 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
140 provides by the project; those files are installed so they can be used by
143 ### Additional build variables
144 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
146 * `LIBRARIES`: specifies libraries to link against
147 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
151 c++utilities and qtutilities provide CMake modules to reduce boilerplate code
152 in the CMake files of my projects. Those modules implement the functionality
153 controlled by the variables documented above. Most important modules are:
155 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
156 * `QtConfig`: does basic Qt-related configuration, reads most of the Qt-specific
157 variables documented above
158 * `QtGuiConfig`: does Qt-related configuration for building a Qt Widgets or
159 Qt Quick based GUI application/library
160 * must be included *before* `QtConfig`
161 * `WebViewProviderConfig`: configures the webview provider
162 * used by Tag Editor and Syncthing Tray to select between Qt WebEngine,
163 Qt WebKit or disabling the built-in webview
164 * `LibraryTarget`: does further configuration for building dynamic and static
165 libraries and plugins; `META_PROJECT_TYPE` can be left empty or set explicitely
167 * `AppTarget`: does further configuration for building an application;
168 `META_PROJECT_TYPE` must be set to `application`
169 * `ShellCompletion`: enables shell completion
170 * only works when using the argument parser provided by the
171 `ApplicationUtilities::ArgumentParser` class of course
172 * `TestTarget`: adds the test target `check`
173 * `check` target is *not* required by target `all`
174 * test target uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES`
176 * test target will automatically link against `cppunit` which is the test
177 framework used by all my projects; set `META_NO_CPP_UNIT=OFF` in the project
179 * `Doxygen`: adds a target to generate documentation using Doxygen
180 * `WindowsResources`: handles creation of Windows resources to set application
181 meta data and icon, ignored on other platforms
182 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
183 module (when all configuration is done)
185 Since those modules make use of the variables explained above, the modules must
186 be included *after* setting those variables. The inclusion order of the modules
189 For an example, checkout the project file of c++utilities itself. The project
190 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
191 cover everything (library, plugin, application, tests, desktop file, Qt
192 resources and translations, ...).