C++ Utilities
4.9.2
Common C++ classes and routines used by my applications such as argument parser, IO and conversion utilities
|
Documents variables to control the build system and provided CMake modules
CMAKE_INSTALL_PREFIX=path
: specifies the final install prefix (temporary install prefix is set via make
argument DESTDIR=path
)CMAKE_BUILD_TYPE=Release/Debug
: specifies whether to do a debug or a release buildCMAKE_SKIP_BUILD_RPATH=OFF
: ensures the rpath is set in the build treeCMAKE_INSTALL_RPATH=rpath
: sets the rpath used when installingCMAKE_CXX_FLAGS
: sets flags to be passed to the C++ compilerThe following variables are read by the CMake modules provided by c++utilities and qtutilities.
None of these are enabled or set by default, unless stated otherwise.
LIB_SUFFIX=suffix
: suffix for library install directoryLIB_SUFFIX_32=suffix
: suffix for library install directoryLIB_SUFFIX
when building for 32-bit platformsLIB_SUFFIX_64=suffix
: suffix for library install directoryLIB_SUFFIX
when building for 64-bit platformsENABLE_STATIC_LIBS=ON/OFF
: enables building static libsDISABLE_SHARED_LIBS=ON/OFF
: disables building shared libsSTATIC_LINKAGE=ON/OFF
: enables linking applications preferably against static librariesSTATIC_LIBRARY_LINKAGE=ON/OFF
: enables linking dynamic libraries preferably against static librariesc++utilities
requires also linking against its dependency iconv
; the static version of iconv
is preferredSTATIC_LIBRARY_LINKAGE
and can currently not be controlledSHELL_COMPLETION_ENABLED=ON/OFF
: enables shell completion in general (enabled by default)BASH_COMPLETION_ENABLED=ON/OFF
: enables Bash completion (enabled by default)LOGGING_ENABLED=ON/OFF
: enables further loggin in some applicationsFORCE_OLD_ABI=ON/OFF
: forces use of old C++ ABI_GLIBCXX_USE_CXX11_ABI=0
EXCLUDE_TESTS_FROM_ALL=ON/OFF
: excludes tests from the all target (enabled by default)APPEND_GIT_REVISION=ON/OFF
: whether the build script should attempt to append the Git revision and the latest commit ID to the version--help
CLANG_FORMAT_ENABLED=ON/OFF
: enables tidy target for code formatting via clang-format
META_NO_TIDY
in the project filecheck
targetCLANG_SOURCE_BASED_COVERAGE_ENABLED=ON/OFF
: enables coverage
target to determine source-based test coverage using Clang/llvmENABLE_INSTALL_TARGETS=ON/OFF
: enables creation of install targets (enabled by default)The build script tries to find the required dependencies at standard loctions using the CMake functions find_library
and find_package
. The behaviour of those functions can be controlled by setting some variables, eg. using a toolchain file. Checkout the CMake documentation for this.
If the detection does not work as expected or a library from a non-standard location should be used, the following variables can be used to specify the location of libraries and include directories directly:
dependency_DYNAMIC_LIB
: specifies the locations of the dynamic libraries for dependencydependency_STATIC_LIB
: specifies the locations of the static libraries for dependencydependency_DYNAMIC_INCLUDE_DIR
: specifies the locations of the additional include directories required for using the dynamic version of the dependencydependency_STATIC_INCLUDE_DIR
: specifies the locations of the additional include directories required for using the static version of the dependencyExample of passing location of dynamic iconv
and zlib
to CMake:
Note about Qt: Qt modules must be located via find_package
. So using the variables described above to specify a custom location does not work. Instead, the variable CMAKE_PREFIX_PATH
can be used to specify the install prefix of the Qt build to use. Set QT_LINKAGE
to STATIC
if it is a static build of Qt.
USE_NATIVE_FILE_BUFFER=ON/OFF
: use native function to open file streams to pass unicode file names correctlyc++utilities
and libraries using that feature (eg. tagparser
).c++utilities
, so the option must be specified when building c++utilities
. Specifying it only when building eg. tagparser
has no effect.FORCE_UTF8_CODEPAGE=ON/OFF
: forces use of UTF-8 codepage in terminalWINDOWS_RESOURCES_ENABLED=ON/OFF
: enables creating resources for application meta data and icon (enabled by default)BUNDLE_INSTALL_DESTINATION=/some/path
: specifies the install destination for application bundles; if not specified, the default bin directory is usedWIDGETS_GUI=ON/OFF
: enables Qt Widgets GUI for projects where it is available and optionalQUICK_GUI=ON/OFF
: enables Qt Quick GUI for projects where it is available and optionalBUILTIN_TRANSLATIONS=ON/OFF
: enables built-in translations in applicationsBUILTIN_ICON_THEMES=breeze;breeze-dark;...
: specifies icon themes to built-inBUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...
: same as above but also affects librariesSVG_SUPPORT=ON/OFF
: enables SVG support if not enabled anyways by the projectSVG_ICON_SUPPORT=ON/OFF
: enables SVG icon support (only affect static builds where the required Qt plugin will be built-in if this variable is enabled)WEBVIEW_PROVIDER=auto/webkit/webengine/none
: specifies the Qt module to use for the web viewJS_PROVIDER=auto/script/qml/none
: specifies the Qt module to use for the JavaScript engineQT_LINKAGE=AUTO_LINKAGE/STATIC/SHARED
: specifies whether to use static or shared version of Qt (only works with Qt packages provided in the AUR)ADDITIONAL_QT_MODULES=Network;Concurrent;...
: specifies additional Qt modules to link against (only use for modules which can not be added automatically)The following variables are read by the CMake modules provided by c++utilities and qtutilities.
META_PROJECT_NAME=name
: specifies the project name which is used as the application/library name, mustn't contain spacesMETA_APP_NAME=The Name
: specifies a more readible version of the project name used for instance in about dialog and desktop fileMETA_APP_AUTHOR
: specifies the author shown in for instance in about dialogMETA_APP_DESCRIPTION
: specifies a description shown for instance in about dialog and desktop fileMETA_GENERIC_NAME
: specifies a generic name for the desktop fileMETA_VERSION_MAJOR/MINOR/PATCH=number
: specifies the application/library version, default is 0META_PROJECT_TYPE=application/library/plugin/qtplugin
: specifies whether to build an application, a library or a pluginMETA_CXX_STANDARD=11/14/..
: specifies the C++ version, default is 14META_NO_TIDY
: disables availability of enabling formatting via CLANG_FORMAT_ENABLED
for this projectMETA_NO_INSTALL_TARGETS
: the project is not meant to be installed, eg. private test helper; prevents creation of install targetsHEADER_FILES
/SRC_FILES
: specifies C++ header/source filesTEST_HEADER_FILES
/TEST_SRC_FILES
: specifies C++ header/source files of the testsTS_FILES
: specifies Qt translationsRES_FILES
: specifies Qt resource filesDBUS_FILES
: specifies files for Qt DBusWIDGETS_HEADER_FILES
/WIDGETS_SRC_FILES
: specifies C++ header/source files only required for Qt Widgets GUIQML_HEADER_FILES
/QML_SRC_FILES
/QML_RES_FILES
: specifies C++ header/source files and Qt resouce files only required for Qt Quick GUIDOC_FILES
: additional markdown files to be inlcuded in the documentation created via Doxygen; the first file is used as the main pageDOC_ONLY_FILES
: specifies documentation-only filesREQUIRED_ICONS
: names of the icons required by the application and the used libraries (can be generated with qtutilities/scripts/required_icons.sh
)CMAKE_MODULE_FILES
/CMAKE_TEMPLATE_FILES
: specifies CMake modules/templates provides by the project; those files are installed so they can be used by other projectsMETA_PRIVATE/PUBLIC_COMPILE_DEFINITIONS
: specifies private/public compile definitionsLIBRARIES
: specifies libraries to link againstMETA_PUBLIC_QT_MODULES
: specifies Qt modules used in the public library interfacec++utilities and qtutilities provide CMake modules to reduce boilerplate code in the CMake files of my projects. Those modules implement the functionality controlled by the variables documented above. Most important modules are:
BaseConfig
: does basic configuration, reads most of the META
-variablesQtConfig
: does basic Qt-related configuration, reads most of the Qt-specific variables documented aboveQtGuiConfig
: does Qt-related configuration for building a Qt Widgets or Qt Quick based GUI application/libraryQtConfig
WebViewProviderConfig
: configures the webview providerLibraryTarget
: does further configuration for building dynamic and static libraries and plugins; META_PROJECT_TYPE
can be left empty or set explicitely to library
AppTarget
: does further configuration for building an application; META_PROJECT_TYPE
must be set to application
ShellCompletion
: enables shell completionApplicationUtilities::ArgumentParser
class of courseTestTarget
: adds the test target check
check
target is not required by target all
TEST_HEADER_FILES
/TEST_SRC_FILES
variablescppunit
which is the test framework used by all my projects; set META_NO_CPP_UNIT=OFF
in the project file to prevent thisDoxygen
: adds a target to generate documentation using DoxygenWindowsResources
: handles creation of Windows resources to set application meta data and icon, ignored on other platformsConfigHeader
: generates resources/config.h
, must be included as the last module (when all configuration is done)Since those modules make use of the variables explained above, the modules must be included after setting those variables. The inclusion order of the modules matters as well.
For an example, checkout the project file of c++utilities itself. The project files of Syncthing Tray should cover everything (library, plugin, application, tests, desktop file, Qt resources and translations, ...).