Update documentation about the build system

This commit is contained in:
Martchus 2017-08-11 21:05:04 +02:00
parent b45fe7eaeb
commit a40d6cad61
2 changed files with 77 additions and 23 deletions

View File

@ -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" \
"path/to/projectdirectory"
make tidy # format source files (optional, must be enabled via CLANG_FORMAT_ENABLED)
make
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
set `DISABLE_SHARED_LIBS=ON`.
* 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.
## TODO
- remove unused features

View File

@ -12,6 +12,7 @@
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
* `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
[`find_library`](https://cmake.org/cmake/help/latest/command/find_library.html)
and
[`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html).
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