C++ Utilities  4.9.0
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, 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
31  static libraries
32 * `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
33  (enabled by default)
34 * `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
35  default)
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
40  (enabled by default)
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
47  `clang-format`
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
55 
56 #### Windows specific
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)
62 
63 #### Qt specific
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
67  and optional
68 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
69 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
70  built-in
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
74  project
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
77  enabled)
78 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
79  for the web view
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
86  automatically)
87 
88 
89 ## Variables to be set in project file
90 The following variables are read by the CMake modules provided by c++utilities
91 and qtutilities.
92 
93 ### Meta data
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
99  dialog
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
110 
111 ### Files
112 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
113 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
114  tests
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
129  other projects
130 
131 ### Additional build variables
132 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
133  definitions
134 * `LIBRARIES`: specifies libraries to link against
135 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
136  interface
137 
138 ## Provided modules
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
147  of course
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
152  meta data and icon
153 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
154  module (when all configuration is done)
155 
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, ...).