Update documentation about the build system

README.md

@@ -24,10 +24,8 @@ The library utilizes:
 ### Requirements
 #### Build-only dependencies
 * C++ compiler supporting C++14, tested with
-    - Clang
+    - clang++ to compile for GNU/Linux and MacOS X
-    - regular GNU g++
+    - g++ to compile for GNU/Linux and Windows
-    - mingw-w64 g++
-    - Cygwin g++
 * 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
+    * C++ standard library supporting C++14, tested with
- - libiconv (might be part of glibc or provided as extra library)
+        - 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"
+cmake -DCMAKE_BUILD_TYPE=Release \
-make tidy # format source files (optional)
+      -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
+* Building for Windows with GCC as cross compiler and mingw-w64 can be simplified by using a small
-[cmake wrapper from Fedora](https://aur.archlinux.org/cgit/aur.git/tree/mingw-cmake.sh?h=mingw-w64-cmake):
+  [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
+  ${_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

doc/buildvariables.md

@@ -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