C++ Utilities  4.8.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 displayed
43  via --help (enabled by default but has no effect when the source directory is
44  no Git checkout or Git is not installed)
45 
46 #### Windows specific
47 * `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
48  to pass unicode file names correctly, changing this alters ABI
49 * `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal
50 * `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
51  application meta data and icon (enabled by default)
52 
53 #### Qt specific
54 * `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
55  available and optional
56 * `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available
57  and optional
58 * `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications
59 * `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to
60  built-in
61 * `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but
62  also affects libraries
63 * `SVG_SUPPORT=ON/OFF`: enables SVG support if not enabled anyways by the
64  project
65 * `SVG_ICON_SUPPORT=ON/OFF`: enables SVG icon support (only affect static
66  builds where the required Qt plugin will be built-in if this variable is
67  enabled)
68 * `WEBVIEW_PROVIDER=auto/webkit/webengine/none`: specifies the Qt module to use
69  for the web view
70 * `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use
71  for the JavaScript engine
72 * `QT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED`: specifies whether to use static
73  or shared version of Qt (only works with Qt packages provided in the AUR)
74 * `ADDITIONAL_QT_MODULES=Network;Concurrent;...`: specifies additional Qt
75  modules to link against (only use for modules which can not be added
76  automatically)
77 
78 
79 ## Variables to be set in project file
80 The following variables are read by the CMake modules provided by c++utilities
81 and qtutilities.
82 
83 ### Meta data
84 * `META_PROJECT_NAME=name`: specifies the project name which is used as the
85  application/library name, mustn't contain spaces
86 * `META_APP_NAME=The Name`: specifies a more readible version of the project
87  name used for instance in about dialog and desktop file
88 * `META_APP_AUTHOR`: specifies the author shown in for instance in about
89  dialog
90 * `META_APP_DESCRIPTION`: specifies a description shown for instance in about
91  dialog and desktop file
92 * `META_GENERIC_NAME`: specifies a generic name for the desktop file
93 * `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library
94  version, default is 0
95 * `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether
96  to build an application, a library or a plugin
97 * `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14
98 
99 ### Files
100 * `HEADER_FILES`/`SRC_FILES`: specifies C++ header/source files
101 * `TEST_HEADER_FILES`/`TEST_SRC_FILES`: specifies C++ header/source files of the
102  tests
103 * `TS_FILES`: specifies Qt translations
104 * `RES_FILES`: specifies Qt resource files
105 * `DBUS_FILES`: specifies files for Qt DBus
106 * `WIDGETS_HEADER_FILES`/`WIDGETS_SRC_FILES`: specifies C++ header/source files
107  only required for Qt Widgets GUI
108 * `QML_HEADER_FILES`/`QML_SRC_FILES`/`QML_RES_FILES`: specifies C++
109  header/source files and Qt resouce files only required for Qt Quick GUI
110 * `DOC_FILES`: additional markdown files to be inlcuded in the documentation
111  created via Doxygen; the first file is used as the main page
112 * `DOC_ONLY_FILES`: specifies documentation-only files
113 * `REQUIRED_ICONS`: names of the icons required by the application and the
114  used libraries (can be generated with `qtutilities/scripts/required_icons.sh`)
115 * `CMAKE_MODULE_FILES`/`CMAKE_TEMPLATE_FILES`: specifies CMake modules/templates
116  provides by the project; those files are installed so they can be used by
117  other projects
118 
119 ### Additional build variables
120 * `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile
121  definitions
122 * `LIBRARIES`: specifies libraries to link against
123 * `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library
124  interface
125 
126 ## Provided modules
127 Most important modules:
128 * `BaseConfig`: does basic configuration, reads most of the `META`-variables
129 * `LibraryTarget`: does further configuration for building dynamic and static
130  libraries and plugins; `META_PROJECT_TYPE` must be set accordingly
131 * `AppTarget`: does further configuration for building an application;
132  `META_PROJECT_TYPE` must be set accordingly
133 * `ShellCompletion`: enables shell completion; only works when using the
134  argument parser provided by the ApplicationUtilities::ArgumentParser class
135  of course
136 * `TestTarget`: adds the test target `check` which is *not* required by target
137  `all`; uses files specified in `TEST_HEADER_FILES`/`TEST_SRC_FILES` variables
138 * `Doxygen`: adds a target to generate documentation using Doxygen
139 * `WindowsResources`: handles creation of windows resources to set application
140  meta data and icon
141 * `ConfigHeader`: generates `resources/config.h`, must be included as the last
142  module (when all configuration is done)
143 
144 The inclusion order of the modules matters.
145 For an example, checkout the project file of c++utilities itself. The project
146 files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should
147 cover everything (library, plugin, application, tests, desktop file, Qt
148 resources and translations, ...).