Update documentation about the build system
This commit is contained in:
parent
b45fe7eaeb
commit
a40d6cad61
49
README.md
49
README.md
|
@ -24,10 +24,8 @@ The library utilizes:
|
||||||
### Requirements
|
### Requirements
|
||||||
#### Build-only dependencies
|
#### Build-only dependencies
|
||||||
* C++ compiler supporting C++14, tested with
|
* 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)
|
* CMake (at least 3.3.0)
|
||||||
* cppunit for unit tests (optional)
|
* cppunit for unit tests (optional)
|
||||||
* Doxygen for API documentation (optional)
|
* Doxygen for API documentation (optional)
|
||||||
|
@ -37,24 +35,28 @@ The library utilizes:
|
||||||
|
|
||||||
#### Runtime dependencies
|
#### Runtime dependencies
|
||||||
* The c++utilities library itself only needs
|
* 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.
|
* For dependencies of my other projects check the README.md of these projects.
|
||||||
|
|
||||||
### How to build
|
### How to build
|
||||||
Just run:
|
Just run:
|
||||||
```
|
```
|
||||||
cd "path/to/build/directory"
|
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
|
||||||
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 apidoc # build API documentation (optional)
|
||||||
make DESTDIR="/temporary/install/location" install
|
make DESTDIR="/temporary/install/location" install
|
||||||
```
|
```
|
||||||
|
|
||||||
#### General notes
|
#### General notes
|
||||||
* Building with qmake is not supported anymore.
|
|
||||||
* The make option ```-j``` can be used for concurrent compilation.
|
* The make option ```-j``` can be used for concurrent compilation.
|
||||||
* ```LIB_SUFFIX```, ```LIB_SUFFIX_32``` and ```LIB_SUFFIX_64``` can be set to
|
* ```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.
|
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`.
|
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`.
|
* 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`.
|
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
|
||||||
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.
|
* 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.
|
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
|
#### 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.
|
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
|
The repository [PKGBUILDs](https://github.com/Martchus/PKGBUILDs) contains files
|
||||||
for building Arch Linux packages.
|
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 packages
|
||||||
RPM \*.spec files can be found at [openSUSE Build Servide](https://build.opensuse.org/project/show/home:mkittler).
|
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
|
### General notes
|
||||||
* There is a workaround for [GCC Bug 66145](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145) provided
|
* There is a workaround for [GCC Bug 66145](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145) provided
|
||||||
in io/catchiofailure.h.
|
in io/catchiofailure.h.
|
||||||
|
|
||||||
## TODO
|
|
||||||
- remove unused features
|
|
||||||
|
|
|
@ -12,6 +12,7 @@
|
||||||
build
|
build
|
||||||
* `CMAKE_SKIP_BUILD_RPATH=OFF`: ensures the rpath is set in the build tree
|
* `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_INSTALL_RPATH=rpath`: sets the rpath used when installing
|
||||||
|
* `CMAKE_CXX_FLAGS`: sets flags to be passed to the C++ compiler
|
||||||
|
|
||||||
### Custom variables
|
### Custom variables
|
||||||
The following variables are read by the CMake modules provided by c++utilities
|
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*
|
* `STATIC_LIBRARY_LINKAGE=ON/OFF`: enables linking dynamic libraries *preferably*
|
||||||
against static libraries
|
against static libraries
|
||||||
* by default linking against dynamic libraries is preferred
|
* 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
|
* `SHELL_COMPLETION_ENABLED=ON/OFF`: enables shell completion in general
|
||||||
(enabled by default)
|
(enabled by default)
|
||||||
* `BASH_COMPLETION_ENABLED=ON/OFF`: enables Bash completion (enabled by
|
* `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)
|
(enabled by default)
|
||||||
* `APPEND_GIT_REVISION=ON/OFF`: whether the build script should attempt to
|
* `APPEND_GIT_REVISION=ON/OFF`: whether the build script should attempt to
|
||||||
append the Git revision and the latest commit ID to the version
|
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
|
* enabled by default but has no effect when the source directory is
|
||||||
no Git checkout or Git is not installed
|
no Git checkout or Git is not installed
|
||||||
* `CLANG_FORMAT_ENABLED=ON/OFF`: enables tidy target for code formatting via
|
* `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
|
* `ENABLE_INSTALL_TARGETS=ON/OFF`: enables creation of install targets (enabled
|
||||||
by default)
|
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
|
#### Windows specific
|
||||||
* `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
|
* `USE_NATIVE_FILE_BUFFER=ON/OFF`: use native function to open file streams
|
||||||
to pass unicode file names correctly, changing this alters ABI
|
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
|
* `WINDOWS_RESOURCES_ENABLED=ON/OFF`: enables creating resources for
|
||||||
application meta data and icon (enabled by default)
|
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
|
#### Qt specific
|
||||||
* `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
|
* `WIDGETS_GUI=ON/OFF`: enables Qt Widgets GUI for projects where it is
|
||||||
available and optional
|
available and optional
|
||||||
|
|
Loading…
Reference in New Issue