From a40d6cad61310d68bb0c096c041a77f5255d02b6 Mon Sep 17 00:00:00 2001 From: Martchus Date: Fri, 11 Aug 2017 21:05:04 +0200 Subject: [PATCH] Update documentation about the build system --- README.md | 49 +++++++++++++++++++++++------------------ doc/buildvariables.md | 51 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 77 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 186a9ec..0993637 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/buildvariables.md b/doc/buildvariables.md index a34b6b0..2e33dd7 100644 --- a/doc/buildvariables.md +++ b/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