C++ Utilities  4.13.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_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
72  by default)
73 * `ENABLE_ESCAPE_CODES_BY_DEAULT`: enables use of escape codes for formatted
74  output by default
75  * enabled by default
76  * see ApplicationUtilities::NoColorArgument and EscapeCodes::enabled
77  * has to be set when building `c++utilities`; projects using that build of
78  `c++utilities` will then use this default
79 
80 #### Variables for specifying location of 3rd party dependencies
81 The build script tries to find the required dependencies at standard loctions
82 using the CMake functions
83 [`find_library`](https://cmake.org/cmake/help/latest/command/find_library.html)
84 and
85 [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html).
86 The behaviour of those functions can be controlled by setting some variables, eg.
87 using a toolchain file. Checkout the CMake documentation for this.
88 
89 If the detection does not work as expected or a library from a non-standard
90 location should be used, the following variables can be used to specify
91 the location of libraries and include directories directly:
92 
93 * `dependency_DYNAMIC_LIB`: specifies the locations of the dynamic libraries
94  for *dependency*
95 * `dependency_STATIC_LIB`: specifies the locations of the static libraries
96  for *dependency*
97 * `dependency_DYNAMIC_INCLUDE_DIR`: specifies the locations of the additional
98  include directories required for using the dynamic version of the *dependency*
99 * `dependency_STATIC_INCLUDE_DIR`: specifies the locations of the additional
100  include directories required for using the static version of the *dependency*
101 
102 Example of passing location of dynamic `iconv` and `zlib` to CMake:
103 ```
104 /opt/osxcross/bin/x86_64-apple-darwin15-cmake \
105  -Diconv_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libiconv.2.tbd \
106  -Diconv_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
107  -Dz_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libz.1.tbd \
108  -Dz_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
109  ...
110 ```
111 
112 *Note about Qt*: Qt modules must be located via `find_package`. So using the variables
113 described above to specify a custom location does not work. Instead, the
114 variable `CMAKE_PREFIX_PATH` can be used to specify the install prefix of the
115 Qt build to use. Set `QT_LINKAGE` to `STATIC` if it is a static build of Qt.
116 
117 #### Windows specific
118 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
119  to pass unicode file names correctly
120  * Changing this option alters the ABI of `c++utilities` and libraries using
121  that feature (eg. `tagparser`).
122  * This feature is implemented in `c++utilities`, so the option must be specified
123  when building `c++utilities`. Specifying it only when building eg. `tagparser`
124  has *no* effect.
125 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
126 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
127  application meta data and icon (enabled by default)
128 
129 #### MacOS specific
130 * `BUNDLE_INSTALL_DESTINATION=/some/path`: specifies the install destination for
131  application bundles; if not specified, the default bin directory is used
132 
133 #### Qt specific
134 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
135  available and optional
136 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
137  and optional
138 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
139 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
140  built-in
141 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
142  also affects libraries
143 * `SVG_SUPPORT=ON/OFF`: enables linking against the static SVG image format
144  plugin
145  * enabled by default
146  * requires the Qt Svg module
147  * only relevant when using static Qt
148 * `SVG_ICON_SUPPORT=ON/OFF`: enables linking against the static SVG icon engine
149  plugin provided by the Qt Svg module
150  * enabled by default
151  * requires the Qt Svg module
152  * only relevant when using static Qt
153  * required to use Breeze icon theme (or any other SVG icon theme)
154 * `IMAGE_FORMAT_SUPPORT`: enables linking against the specified static image
155  format plugins
156  * comma-separated list
157  * by default set to "Gif;ICO;Jpeg", so support for Gif, ICO and Jpeg is
158  enabled by default
159  * note that PNG support is not provided via a plugin, so it should be
160  always available and not be affected by this option
161  * further image formats require building the plugins contained by the
162  additional `qtimageformats` repository
163  * only relevant when using static Qt
164 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
165  for the web view
166 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
167  for the JavaScript engine
168 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
169  or shared version of Qt (only works with Qt packages provided in the AUR)
170 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
171  modules to link against (only use for modules which can not be added
172  automatically)
173 
174 
175 ## Variables to be set in project file
176 The following variables are read by the CMake modules provided by c++utilities
177 and qtutilities.
178 
179 ### Meta data
180 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
181  application/library name, mustn't contain spaces
182 * `META_APP_NAME=The Name`: specifies a more readible version of the project
183  name used for instance in about dialog and desktop file
184 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
185  dialog
186 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
187  dialog and desktop file
188 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
189 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
190  version, default is 0
191 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
192  to build an application, a library or a plugin
193 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
194 * `META_NO_TIDY`: disables availability of enabling formatting via
195  `CLANG_FORMAT_ENABLED` for this project
196 * `META_NO_INSTALL_TARGETS`: the project is not meant to be installed, eg.
197  private test helper; prevents creation of install targets
198 
199 ### Files
200 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
201 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
202  tests
203 * `TS_FILES`: specifies Qt translations
204 * `RES_FILES`: specifies Qt resource files
205 * `DBUS_FILES`: specifies files for Qt DBus
206 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
207  only required for Qt Widgets GUI
208 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
209  header/source files and Qt resouce files only required for Qt Quick GUI
210 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
211  created via Doxygen; the first file is used as the main page
212 * `DOC_ONLY_FILES`: specifies documentation-only files
213 * `REQUIRED_ICONS`: names of the icons required by the application and the
214  used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
215 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
216  provides by the project; those files are installed so they can be used by
217  other projects
218 
219 ### Additional build variables
220 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
221  definitions
222 * `LIBRARIES`: specifies libraries to link against
223 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
224  interface
225 * `META_PUBLIC_SHARED_LIB_DEPENDS`: specifies shared libraries used in the public
226  library interface
227 * `META_PUBLIC_STATIC_LIB_DEPENDS`: specifies static libraries used in the public
228  library interface
229 
230 ## Provided modules
231 c++utilities and qtutilities provide CMake modules to reduce boilerplate code
232 in the CMake files of my projects. Those modules implement the functionality
233 controlled by the variables documented above. Most important modules are:
234 
235 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
236 * `QtConfig`: does basic Qt-related configuration, reads most of the Qt-specific
237  variables documented above
238 * `QtGuiConfig`: does Qt-related configuration for building a Qt Widgets or
239  Qt Quick based GUI application/library
240  * must be included *before* `QtConfig`
241 * `WebViewProviderConfig`: configures the webview provider
242  * used by Tag Editor and Syncthing Tray to select between Qt WebEngine,
243  Qt WebKit or disabling the built-in webview
244 * `LibraryTarget`: does further configuration for building dynamic and static
245  libraries and plugins; `META_PROJECT_TYPE` can be left empty or set explicitely
246  to `library`
247 * `AppTarget`: does further configuration for building an application;
248  `META_PROJECT_TYPE` must be set to `application`
249 * `ShellCompletion`: enables shell completion
250  * only works when using the argument parser provided by the
251  `ApplicationUtilities::ArgumentParser` class of course
252 * `TestTarget`: adds the test target `check`
253  * `check` target is *not* required by target `all`
254  * test target uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES`
255  variables
256  * test target will automatically link against `cppunit` which is the test
257  framework used by all my projects; set `META_NO_CPP_UNIT=OFF` in the project
258  file to prevent this
259 * `Doxygen`: adds a target to generate documentation using Doxygen
260 * `WindowsResources`: handles creation of Windows resources to set application
261  meta data and icon, ignored on other platforms
262 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
263  module (when all configuration is done)
264 
265 Since those modules make use of the variables explained above, the modules must
266 be included *after* setting those variables. The inclusion order of the modules
267 matters as well.
268 
269 For an example, checkout the project file of c++utilities itself. The project
270 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
271 cover everything (library, plugin, application, tests, desktop file, Qt
272 resources and translations, ...).