From 78869da195290571aadc123fe1f664a6db1342ed Mon Sep 17 00:00:00 2001 From: Martchus Date: Sun, 12 Mar 2017 20:23:21 +0100 Subject: [PATCH] Extend documentation --- CMakeLists.txt | 2 + doc/buildvariables.md | 133 +++++++++++++++++++++++++++++++++++++++++ doc/testapplication.md | 18 ++++++ 3 files changed, 153 insertions(+) create mode 100644 doc/buildvariables.md create mode 100644 doc/testapplication.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 0d95905..184dfa3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -105,6 +105,8 @@ endif() set(DOC_FILES README.md + doc/buildvariables.md + doc/testapplication.md ) # required to include CMake modules from own project directory diff --git a/doc/buildvariables.md b/doc/buildvariables.md new file mode 100644 index 0000000..60075c9 --- /dev/null +++ b/doc/buildvariables.md @@ -0,0 +1,133 @@ +# Build system + +\brief Variables to control the build system and provided CMake modules + +## Variables passable as CMake arguments + +### Useful variables provided by CMake itself +* `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 + build +* `CMAKE_SKIP_BUILD_RPATH=OFF`: ensures the rpath is set in the build tree +* `CMAKE_INSTALL_RPATH=rpath`: sets the rpath used when installing + +### Custom variables +The 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 directory +* `LIB_SUFFIX_32=suffix`: suffix for library install directory, used when + building for 32-bit platforms +* `LIB_SUFFIX_64=suffix`: suffix for library install directory, used when + building for 64-bit platforms +* `ENABLE_STATIC_LIBS=ON/OFF`: enables building static libs +* `DISABLE_SHARED_LIBS=ON/OFF`: disables building shared libs +* `STATIC_LINKAGE=ON/OFF`: enables linking applications against static libraries +* `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries against + static libraries +* `SHELL_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 applications +* `FORCE_OLD_ABI=ON/OFF`: forces use of old C++ ABI + (sets `_GLIBCXX_USE_CXX11_ABI=0`) + +#### Windows specific +* `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams + to pass unicode file names correctly, changing this alters ABI +* `FORCE_UTF8_CODEPAGE=ON/OFF`: forces use of UTF-8 codepage in terminal +* `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for + application meta data and icon (enabled by default) + +#### Qt specific +* `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is + available and optional +* `QUICK_GUI=ON/OFF`: enables Qt Quick GUI for projects where it is available + and optional +* `BUILTIN_TRANSLATIONS=ON/OFF`: enables built-in translations in applications +* `BUILTIN_ICON_THEMES=breeze;breeze-dark;...`: specifies icon themes to + built-in +* `BUILTIN_ICON_THEMES_IN_LIBRARIES=breeze;breeze-dark;...`: same as above but + also affects libraries +* `SVG_SUPPORT=ON/OFF`: enables SVG support if not enabled anyways by the + project +* `SVG_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 view +* `JS_PROVIDER=auto/script/qml/none`: specifies the Qt module to use + for the JavaScript engine +* `QT_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) + + +## Variables to be set in project file +The following variables are read by the CMake modules provided by c++utilities +and qtutilities. + +### Meta data +* `META_PROJECT_NAME=name`: specifies the project name which is used as the + application/library name, mustn't contain spaces +* `META_APP_NAME=The Name`: specifies a more readible version of the project + name used for instance in about dialog and desktop file +* `META_APP_AUTHOR`: specifies the author shown in for instance in about + dialog +* `META_APP_DESCRIPTION`: specifies a description shown for instance in about + dialog and desktop file +* `META_GENERIC_NAME`: specifies a generic name for the desktop file +* `META_VERSION_MAJOR/MINOR/PATCH=number`: specifies the application/library + version, default is 0 +* `META_PROJECT_TYPE=application/library/plugin/qtplugin`: specifies whether + to build an application, a library or a plugin +* `META_CXX_STANDARD=11/14/..`: specifies the C++ version, default is 14 + +### Files +* `HEADER_FILES/SRC_FILES`: specifies C++ header/source files +* `TS_FILES`: specifies Qt translations +* `RES_FILES`: specifies Qt resource files +* `DBUS_FILES`: specifies files for Qt DBus +* `WIDGETS_HEADER_FILES/WIDGETS_SRC_FILES`: specifies C++ header/source files + only required for Qt Widgets GUI +* `QML_HEADER_FILES/QML_SRC_FILES/QML_RES_FILES`: specifies C++ header/source + files and Qt resouce files only required for Qt Quick GUI +* `DOC_FILES`: additional markdown files to be inlcuded in the documentation + created via Doxygen; the first file is used as the main page +* `DOC_ONLY_FILES`: specifies documentation-only files +* `REQUIRED_ICONS`: names of the icons required by the application and the + used libraries (can be generated with `qtutilities/scripts/required_icons.sh`) + +### Additional build variables +* `META_PRIVATE/PUBLIC_COMPILE_DEFINITIONS`: specifies private/public compile + definitions +* `LIBRARIES`: specifies libraries to link against +* `META_PUBLIC_QT_MODULES`: specifies Qt modules used in the public library + interface + +## Use of the provided modules +Most important modules: +* `BaseConfig`: does basic configuration, reads most of the `META`-variables +* `LibraryTarget`: does further configuration for building dynamic and static + libraries and plugins, `META_PROJECT_TYPE` must be set accordingly +* `AppTarget`: does further configuration for building an application, + `META_PROJECT_TYPE` must be set accordingly +* `ShellCompletion`: enables shell completion (only works when using the + argument parser provided by the library of course) +* `TestTarget`: adds a test target +* `Doxygen`: adds a target to generate documentation using Doxygen +* `WindowsResources`: handles creation of windows resources to set application + meta data and icon +* `ConfigHeader`: generates `resources/config.h`, must be included as the last + module (when all configuration is done) + +The inclusion order of the modules matters. +For an example, checkout the project file of c++utilities itself. The project +files of [Syncthing Tray](https://github.com/Martchus/syncthingtray) should +cover everything. diff --git a/doc/testapplication.md b/doc/testapplication.md new file mode 100644 index 0000000..dd718ef --- /dev/null +++ b/doc/testapplication.md @@ -0,0 +1,18 @@ +# Test applications + +\brief Arguments supported by test applications created with `TestTarget` CMake + module and the `TestUtilities::TestApplication` class + +``` +--test-files-path, -p [path] + specifies the path of the directory with test files + +--app-path, -a [path] + specifies the path of the application to be tested + +--working-dir, -w [path] + specifies the directory to store working copies of test files + +--units, -u [unit1] [unit2] [unit3] ... + specifies the units to test; omit to test all units +```