C++ Utilities  4.9.1
Common C++ classes and routines used by my applications 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 
16 ### Custom variables
17 The following variables are read by the CMake modules provided by c++utilities
18 and qtutilities.
19 
20 None of these are enabled or set by default, unless stated otherwise.
21 
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
32  static libraries
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
40  (enabled by default)
41 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
42  default)
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
48  (enabled by default)
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
55  `clang-format`
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
64  by default)
65 
66 #### Windows specific
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)
72 
73 #### Qt specific
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
77  and optional
78 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
79 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
80  built-in
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
84  project
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
87  enabled)
88 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
89  for the web view
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
96  automatically)
97 
98 
99 ## Variables to be set in project file
100 The following variables are read by the CMake modules provided by c++utilities
101 and qtutilities.
102 
103 ### Meta data
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
109  dialog
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
122 
123 ### Files
124 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
125 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
126  tests
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
141  other projects
142 
143 ### Additional build variables
144 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
145  definitions
146 * `LIBRARIES`: specifies libraries to link against
147 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
148  interface
149 
150 ## Provided modules
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:
154 
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
166  to `library`
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`
175  variables
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
178  file to prevent this
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)
184 
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
187 matters as well.
188 
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, ...).