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