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, used when
24 building for 32-bit platforms
25 * `LIB_SUFFIX_64=suffix`: suffix for library install directory, used when
26 building for 64-bit platforms
27 * `ENABLE_STATIC_LIBS=ON/OFF`: enables building static libs
28 * `DISABLE_SHARED_LIBS=ON/OFF`: disables building shared libs
29 * `STATIC_LINKAGE=ON/OFF`: enables linking applications against static libraries
30 * `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries against
32 * `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
34 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
36 * `LOGGING_ENABLED=ON/OFF`: enables further loggin in some applications
37 * `FORCE_OLD_ABI=ON/OFF`: forces use of old C++ ABI
38 (sets `_GLIBCXX_USE_CXX11_ABI=0`)
39 * `EXCLUDE_TESTS_FROM_ALL=ON/OFF`: excludes tests from the all target
41 * `APPEND_GIT_REVISION=ON/OFF`: whether the build script should attempt to
42 append the Git revision and the latest commit ID to the version
43 * displayed via --help
44 * enabled by default but has no effect when the source directory is
45 no Git checkout or Git is not installed
46 * `CLANG_FORMAT_ENABLED=ON/OFF`: enables tidy target for code formatting via
48 * can be made unavailable by setting `META_NO_TIDY` in the project file
49 * only available if format rules are available
50 * also enables tidy check executed via `check` target
51 * `CLANG_SOURCE_BASED_COVERAGE_ENABLED=ON/OFF`: enables `coverage` target to
52 determine source-based test coverage using Clang/llvm
53 * only available when building with Clang under UNIX
54 * coverage report is stored in build directory
57 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
58 to pass unicode file names correctly, changing this alters ABI
59 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
60 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
61 application meta data and icon (enabled by default)
64 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
65 available and optional
66 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
68 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
69 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
71 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
72 also affects libraries
73 * `SVG_SUPPORT=ON/OFF`: enables SVG support if not enabled anyways by the
75 * `SVG_ICON_SUPPORT=ON/OFF`: enables SVG icon support (only affect static
76 builds where the required Qt plugin will be built-in if this variable is
78 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
80 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
81 for the JavaScript engine
82 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
83 or shared version of Qt (only works with Qt packages provided in the AUR)
84 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
85 modules to link against (only use for modules which can not be added
89 ## Variables to be set in project file
90 The following variables are read by the CMake modules provided by c++utilities
94 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
95 application/library name, mustn't contain spaces
96 * `META_APP_NAME=The Name`: specifies a more readible version of the project
97 name used for instance in about dialog and desktop file
98 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
100 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
101 dialog and desktop file
102 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
103 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
104 version, default is 0
105 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
106 to build an application, a library or a plugin
107 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
108 * `META_NO_TIDY`: disables availability of enabling formatting via
109 `CLANG_FORMAT_ENABLED` for this project
112 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
113 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
115 * `TS_FILES`: specifies Qt translations
116 * `RES_FILES`: specifies Qt resource files
117 * `DBUS_FILES`: specifies files for Qt DBus
118 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
119 only required for Qt Widgets GUI
120 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
121 header/source files and Qt resouce files only required for Qt Quick GUI
122 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
123 created via Doxygen; the first file is used as the main page
124 * `DOC_ONLY_FILES`: specifies documentation-only files
125 * `REQUIRED_ICONS`: names of the icons required by the application and the
126 used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
127 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
128 provides by the project; those files are installed so they can be used by
131 ### Additional build variables
132 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
134 * `LIBRARIES`: specifies libraries to link against
135 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
139 Most important modules:
140 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
141 * `LibraryTarget`: does further configuration for building dynamic and static
142 libraries and plugins; `META_PROJECT_TYPE` must be set accordingly
143 * `AppTarget`: does further configuration for building an application;
144 `META_PROJECT_TYPE` must be set accordingly
145 * `ShellCompletion`: enables shell completion; only works when using the
146 argument parser provided by the ApplicationUtilities::ArgumentParser class
148 * `TestTarget`: adds the test target `check` which is *not* required by target
149 `all`; uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES` variables
150 * `Doxygen`: adds a target to generate documentation using Doxygen
151 * `WindowsResources`: handles creation of windows resources to set application
153 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
154 module (when all configuration is done)
156 The inclusion order of the modules matters.
157 For an example, checkout the project file of c++utilities itself. The project
158 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
159 cover everything (library, plugin, application, tests, desktop file, Qt
160 resources and translations, ...).