C++ Utilities
4.17.0
Useful C++ classes and routines 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
targetCMAKE_FORMAT_ENABLED=ON/OFF
: enables tidy target for code formatting via cmake-format
META_NO_TIDY
in the project fileMETA_CMAKE_FORMAT_OPTIONS
in the project fileCLANG_TIDY_ENABLED=ON/OFF
: enables target static-check
for static code analysis with clang-tidy
META_NO_STATIC_ANALYSIS
in the project fileCLANG_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)ENABLE_ESCAPE_CODES_BY_DEAULT
: enables use of escape codes for formatted output by defaultc++utilities
; projects using that build of c++utilities
will then use this defaultUSE_NATIVE_FILE_BUFFER=ON/OFF
: use native functions to open file streamsc++utilities
and other libraries exposing that ABI (eg. tagparser
and passwordfile
).c++utilities
, so the option must be specified when building c++utilities
. Specifying it only when building eg. tagparser
has no effect.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 dependencyNote about Qt: Qt modules are always configured using the CMake packages via find_package
. So using the variables described above to specify a custom location does not work. Instead, the variables CMAKE_FIND_ROOT_PATH
or 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.
Example of passing location of dynamic iconv
and zlib
to CMake:
Here's an example of passing the location of the Android SDK/NDK to compile for Android. This time the iconv
library is located by specifying its install prefix via CMAKE_FIND_ROOT_PATH
. The include directories are not automatically added for that library, so this must still be done manually:
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 linking against the static SVG image format pluginSVG_ICON_SUPPORT=ON/OFF
: enables linking against the static SVG icon engine plugin provided by the Qt Svg moduleIMAGE_FORMAT_SUPPORT
: enables linking against the specified static image format pluginsqtimageformats
repositoryWEBVIEW_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 targetsMETA_ADD_DEFAULT_CPP_UNIT_TEST_APPLICATION
: implicitely add a source file with a main()-entry point to test target for running CppUnit test casesHEADER_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 findicons)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 interfaceMETA_PUBLIC_SHARED_LIB_DEPENDS
: specifies shared libraries used in the public library interfaceMETA_PUBLIC_STATIC_LIB_DEPENDS
: specifies static libraries 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 thisAndroidApk
: adds a target to create an APK package for Android using androiddeployqtDoxygen
: 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, ...).