Update documentation about the build system

Martchus 6 years ago
parent b45fe7eaeb
commit a40d6cad61

@ -24,10 +24,8 @@ The library utilizes:
### Requirements
#### Build-only dependencies
* C++ compiler supporting C++14, tested with
- Clang
- regular GNU g++
- mingw-w64 g++
- Cygwin g++
- clang++ to compile for GNU/Linux and MacOS X
- g++ to compile for GNU/Linux and Windows
* CMake (at least 3.3.0)
* cppunit for unit tests (optional)
* Doxygen for API documentation (optional)
@ -37,24 +35,28 @@ The library utilizes:
#### Runtime dependencies
* The c++utilities library itself only needs
- C/C++ standard library supporting C++14
- libiconv (might be part of glibc or provided as extra library)
* C++ standard library supporting C++14, tested with
- libstdc++ under GNU/Linux, Windows and MacOS X
- libc++ under GNU/Linux
* iconv (might be part of glibc or provided as extra library)
* For dependencies of my other projects check the README.md of these projects.
### How to build
Just run:
cd "path/to/build/directory"
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="/final/install/location" "path/to/projectdirectory"
make tidy # format source files (optional)
cmake -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="/final/install/location" \
make tidy # format source files (optional, must be enabled via CLANG_FORMAT_ENABLED)
make check # build and run unit tests (optional)
make check # build and run tests (optional)
make coverage # build and run tests measuring test coverage (optional, must be enabled via CLANG_SOURCE_BASED_COVERAGE_ENABLED)
make apidoc # build API documentation (optional)
make DESTDIR="/temporary/install/location" install
#### General notes
* Building with qmake is not supported anymore.
* The make option ```-j``` can be used for concurrent compilation.
* ```LIB_SUFFIX```, ```LIB_SUFFIX_32``` and ```LIB_SUFFIX_64``` can be set to
specify a suffix for the library directory, eg. lib*64* or lib*32*. The 32/64 variants are only used when building for 32/64-bit architecture.
@ -62,18 +64,26 @@ make DESTDIR="/temporary/install/location" install
* By default the build system will prefer *linking against* shared libraries. To force *linking against* static libraries set `STATIC_LINKAGE=ON`.
However, this will only affect applications. To force linking statically when building shared libraries set `STATIC_LIBRARY_LINKAGE=ON`.
* For more detailed documentation, see the documentation about build variables (in directory doc, in Doxygen version accessible via "Related Pages").
* The repository [PKGBUILDs](https://github.com/Martchus/PKGBUILDs) contains build scripts for GNU/Linux, Windows and MacOS X in form
of Arch Linux packages. These scripts can be used example also when building under another platform.
#### Building for Windows
Building for Windows with Mingw-w64 cross compiler can be utilized using a small
[cmake wrapper from Fedora](https://aur.archlinux.org/cgit/aur.git/tree/mingw-cmake.sh?h=mingw-w64-cmake):
${_arch}-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="/final/install/location" "path/to/source/directory"
make DESTDIR="/temporary/install/location" install-mingw-w64-strip
* Building for Windows with GCC as cross compiler and mingw-w64 can be simplified by using a small
[Cmake wrapper and a custom toolchain file](https://aur.archlinux.org/cgit/aur.git/tree/mingw-cmake.sh?h=mingw-w64-cmake):
${_arch}-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="/final/install/location" "path/to/source/directory"
make DESTDIR="/temporary/install/location" install-mingw-w64-strip
* To create the \*.ico file for the application icon ffmpeg/avconv is required.
* The target ```install-mingw-w64-strip``` in the example will only install files
* The target ```install-mingw-w64-strip``` can be used as in the example above to only install files
suitable for creating a cross-compiler package and additionally strip the binaries.
#### Building for MacOS X
* Building for MacOS X is possible using [osxcross](https://github.com/tpoechtrager/osxcross).
#### Development builds
During development I find it useful to build all required projects (for instace c++utilities, qtutilities, tagparser and tageditor) as one big project.
@ -87,7 +97,7 @@ For a debug build, just use ```-DCMAKE_BUILD_TYPE=Debug```.
The repository [PKGBUILDs](https://github.com/Martchus/PKGBUILDs) contains files
for building Arch Linux packages.
PKGBUILD files to build for Windows using the Mingw-w64 compiler are also included.
PKGBUILD files to cross compile for Windows using mingw-w64 and for MacOS X using osxcross are also included.
#### RPM packages
RPM \*.spec files can be found at [openSUSE Build Servide](https://build.opensuse.org/project/show/home:mkittler).
@ -104,6 +114,3 @@ Scripts to build with Cygwin are provided by svnpenn. Checkout his
### General notes
* There is a workaround for [GCC Bug 66145](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145) provided
in io/catchiofailure.h.
- remove unused features

@ -12,6 +12,7 @@
* `CMAKE_SKIP_BUILD_RPATH=OFF`: ensures the rpath is set in the build tree
* `CMAKE_INSTALL_RPATH=rpath`: sets the rpath used when installing
* `CMAKE_CXX_FLAGS`: sets flags to be passed to the C++ compiler
### Custom variables
The following variables are read by the CMake modules provided by c++utilities
@ -35,7 +36,14 @@ None of these are enabled or set by default, unless stated otherwise.
* `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries *preferably*
against static libraries
* by default linking against dynamic libraries is preferred
* only affects building dynamic libraries
* only affects building dynamic libraries (static libraries are just archives
of objects and hence *not linked* against their dependencies when being built)
* note that static libraries are always preferred to provide the dependency
of another static library
* eg. linking against static `c++utilities` requires also linking against
its dependency `iconv`; the static version of `iconv` is preferred
* this behaviour has actually nothing to do with `STATIC_LIBRARY_LINKAGE`
and can currently not be controlled
* `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
(enabled by default)
* `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
@ -48,7 +56,7 @@ None of these are enabled or set by default, unless stated otherwise.
(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
* displayed via --help
* displayed via `--help`
* enabled by default but has no effect when the source directory is
no Git checkout or Git is not installed
* `CLANG_FORMAT_ENABLED=ON/OFF`: enables tidy target for code formatting via
@ -63,6 +71,41 @@ None of these are enabled or set by default, unless stated otherwise.
* `ENABLE_INSTALL_TARGETS=ON/OFF`: enables creation of install targets (enabled
by default)
#### Variables for specifying location of 3rd party dependencies
The build script tries to find the required dependencies at standard loctions
using the CMake functions
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 *dependency*
* `dependency_STATIC_LIB`: specifies the locations of the static libraries
for *dependency*
* `dependency_DYNAMIC_INCLUDE_DIR`: specifies the locations of the additional
include directories required for using the dynamic version of the *dependency*
* `dependency_STATIC_INCLUDE_DIR`: specifies the locations of the additional
include directories required for using the static version of the *dependency*
Example of passing location of dynamic `iconv` to CMake:
/opt/osxcross/bin/x86_64-apple-darwin15-cmake \
-Diconv_DYNAMIC_LIB:FILEPATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/lib/libiconv.2.tbd \
-Diconv_DYNAMIC_INCLUDE_DIR:PATH=/opt/osxcross/SDK/MacOSX10.11.sdk/usr/include \
*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.
#### 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
@ -70,6 +113,10 @@ None of these are enabled or set by default, unless stated otherwise.
* `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
application meta data and icon (enabled by default)
#### MacOS specific
* `BUNDLE_INSTALL_DESTINATION=/some/path`: specifies the install destination for
application bundles; if not specified, the default bin directory is used
#### Qt specific
* `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
available and optional