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
15 * `CMAKE_CXX_FLAGS`: sets flags to be passed to the C++ compiler
18 The following variables are read by the CMake modules provided by c++utilities
21 None of these are enabled or set by default, unless stated otherwise.
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
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
49 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
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
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
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_SOURCE_BASED_COVERAGE_ENABLED=ON/OFF`: enables `coverage` target to
68 determine source-based test coverage using Clang/llvm
69 * only available when building with Clang under UNIX
70 * coverage report is stored in build directory
71 * `ENABLE_INSTALL_TARGETS=ON/OFF`: enables creation of install targets (enabled
74 #### Variables for specifying location of 3rd party dependencies
75 The build script tries to find the required dependencies at standard loctions
76 using the CMake functions
77 [`find_library`](https://cmake.org/cmake/help/latest/command/find_library.html)
79 [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html).
80 The behaviour of those functions can be controlled by setting some variables, eg.
81 using a toolchain file. Checkout the CMake documentation for this.
83 If the detection does not work as expected or a library from a non-standard
84 location should be used, the following variables can be used to specify
85 the location of libraries and include directories directly:
87 * `dependency_DYNAMIC_LIB`: specifies the locations of the dynamic libraries
89 * `dependency_STATIC_LIB`: specifies the locations of the static libraries
91 * `dependency_DYNAMIC_INCLUDE_DIR`: specifies the locations of the additional
92 include directories required for using the dynamic version of the *dependency*
93 * `dependency_STATIC_INCLUDE_DIR`: specifies the locations of the additional
94 include directories required for using the static version of the *dependency*
96 Example of passing location of dynamic `iconv` and `zlib` to CMake:
98 /opt/osxcross/bin/x86_64-apple-darwin15-cmake \
99 -Diconv_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libiconv.2.tbd \
100 -Diconv_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
101 -Dz_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libz.1.tbd \
102 -Dz_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
106 *Note about Qt*: Qt modules must be located via `find_package`. So using the variables
107 described above to specify a custom location does not work. Instead, the
108 variable `CMAKE_PREFIX_PATH` can be used to specify the install prefix of the
109 Qt build to use. Set `QT_LINKAGE` to `STATIC` if it is a static build of Qt.
111 #### Windows specific
112 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
113 to pass unicode file names correctly
114 * Changing this option alters the ABI of `c++utilities` and libraries using
115 that feature (eg. `tagparser`).
116 * This feature is implemented in `c++utilities`, so the option must be specified
117 when building `c++utilities`. Specifying it only when building eg. `tagparser`
119 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
120 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
121 application meta data and icon (enabled by default)
124 * `BUNDLE_INSTALL_DESTINATION=/some/path`: specifies the install destination for
125 application bundles; if not specified, the default bin directory is used
128 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
129 available and optional
130 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
132 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
133 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
135 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
136 also affects libraries
137 * `SVG_SUPPORT=ON/OFF`: enables SVG support if not enabled anyways by the
139 * `SVG_ICON_SUPPORT=ON/OFF`: enables SVG icon support (only affect static
140 builds where the required Qt plugin will be built-in if this variable is
142 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
144 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
145 for the JavaScript engine
146 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
147 or shared version of Qt (only works with Qt packages provided in the AUR)
148 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
149 modules to link against (only use for modules which can not be added
153 ## Variables to be set in project file
154 The following variables are read by the CMake modules provided by c++utilities
158 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
159 application/library name, mustn't contain spaces
160 * `META_APP_NAME=The Name`: specifies a more readible version of the project
161 name used for instance in about dialog and desktop file
162 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
164 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
165 dialog and desktop file
166 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
167 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
168 version, default is 0
169 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
170 to build an application, a library or a plugin
171 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
172 * `META_NO_TIDY`: disables availability of enabling formatting via
173 `CLANG_FORMAT_ENABLED` for this project
174 * `META_NO_INSTALL_TARGETS`: the project is not meant to be installed, eg.
175 private test helper; prevents creation of install targets
178 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
179 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
181 * `TS_FILES`: specifies Qt translations
182 * `RES_FILES`: specifies Qt resource files
183 * `DBUS_FILES`: specifies files for Qt DBus
184 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
185 only required for Qt Widgets GUI
186 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
187 header/source files and Qt resouce files only required for Qt Quick GUI
188 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
189 created via Doxygen; the first file is used as the main page
190 * `DOC_ONLY_FILES`: specifies documentation-only files
191 * `REQUIRED_ICONS`: names of the icons required by the application and the
192 used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
193 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
194 provides by the project; those files are installed so they can be used by
197 ### Additional build variables
198 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
200 * `LIBRARIES`: specifies libraries to link against
201 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
205 c++utilities and qtutilities provide CMake modules to reduce boilerplate code
206 in the CMake files of my projects. Those modules implement the functionality
207 controlled by the variables documented above. Most important modules are:
209 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
210 * `QtConfig`: does basic Qt-related configuration, reads most of the Qt-specific
211 variables documented above
212 * `QtGuiConfig`: does Qt-related configuration for building a Qt Widgets or
213 Qt Quick based GUI application/library
214 * must be included *before* `QtConfig`
215 * `WebViewProviderConfig`: configures the webview provider
216 * used by Tag Editor and Syncthing Tray to select between Qt WebEngine,
217 Qt WebKit or disabling the built-in webview
218 * `LibraryTarget`: does further configuration for building dynamic and static
219 libraries and plugins; `META_PROJECT_TYPE` can be left empty or set explicitely
221 * `AppTarget`: does further configuration for building an application;
222 `META_PROJECT_TYPE` must be set to `application`
223 * `ShellCompletion`: enables shell completion
224 * only works when using the argument parser provided by the
225 `ApplicationUtilities::ArgumentParser` class of course
226 * `TestTarget`: adds the test target `check`
227 * `check` target is *not* required by target `all`
228 * test target uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES`
230 * test target will automatically link against `cppunit` which is the test
231 framework used by all my projects; set `META_NO_CPP_UNIT=OFF` in the project
233 * `Doxygen`: adds a target to generate documentation using Doxygen
234 * `WindowsResources`: handles creation of Windows resources to set application
235 meta data and icon, ignored on other platforms
236 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
237 module (when all configuration is done)
239 Since those modules make use of the variables explained above, the modules must
240 be included *after* setting those variables. The inclusion order of the modules
243 For an example, checkout the project file of c++utilities itself. The project
244 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
245 cover everything (library, plugin, application, tests, desktop file, Qt
246 resources and translations, ...).