From 8cdf8dec703d882b46ca50a769fabb95ffc48e2c Mon Sep 17 00:00:00 2001
From: manuel <manuel@mausz.at>
Date: Thu, 24 Nov 2016 21:27:41 +0100
Subject: sync with upstream

---
 project/cmake/README.md | 175 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 154 insertions(+), 21 deletions(-)

(limited to 'project/cmake/README.md')

diff --git a/project/cmake/README.md b/project/cmake/README.md
index 28af525..f3d727e 100644
--- a/project/cmake/README.md
+++ b/project/cmake/README.md
@@ -3,14 +3,14 @@
 This files describes Kodi's CMake based buildsystem. CMake is a cross-platform
 tool for generating makefiles as well as project files used by IDEs.
 
-The current version of the buildsystem is capable of building the main Kodi
-executable (but no packaging or dependency management yet) for the following
-platforms:
+The current version of the buildsystem is capable of building and packaging
+Kodi for the following platforms:
 
-- Linux (GNU Makefiles)
-- Windows (NMake Makefiles, Visual Studio 14 (2015))
-- OSX (GNU Makefiles, Xcode)
+- Linux (GNU Makefiles, Ninja)
+- Windows (NMake Makefiles, Visual Studio 14 (2015), Ninja)
+- macOS and iOS (GNU Makefiles, Xcode, Ninja)
 - Android (GNU Makefiles)
+- FreeBSD (GNU Makefiles)
 
 Before building Kodi with CMake, please ensure that you have the platform
 specific dependencies installed.
@@ -44,12 +44,12 @@ are downloaded using `DownloadBuildDeps.bat` and `DownloadMingwBuildEnv.bat`
 and that the mingw libs (ffmpeg, libdvd and others) are built using
 `make-mingwlibs.bat`.
 
-### OSX
+### macOS
 
-For OSX the required dependencies can be found in
+For macOS the required dependencies can be found in
 [docs/README.osx](https://github.com/xbmc/xbmc/tree/master/docs/README.osx).
 
-On OSX it is necessary to build the dependencies in `tools/depends` using
+On macOS it is necessary to build the dependencies in `tools/depends` using
 `./bootstrap && ./configure --host=<PLATFORM> && make`. The other steps such
 as `make -C tools/depends/target/xbmc` and `make xcode_depends` are not needed
 as these steps are covered already by the CMake project.
@@ -57,7 +57,7 @@ as these steps are covered already by the CMake project.
 ### Android
 
 The dependencies needed to compile for Android can be found in
-[docs/README.osx](https://github.com/xbmc/xbmc/tree/master/docs/README.android)
+[docs/README.android](https://github.com/xbmc/xbmc/tree/master/docs/README.android)
 . All described steps have to be executed (except 5.2 which is replaced by the
 respective CMake command below).
 
@@ -89,6 +89,22 @@ cmake --build . -- VERBOSE=1 -j$(nproc)  # or: make VERBOSE=1 -j$(nproc)
 
 `CMAKE_BUILD_TYPE` defaults to `Release`.
 
+#### Debian package generation
+The buildsystem is capable of generating Debian packages using CPack. To generate them, `CPACK_GENERATOR` has to be set to *DEB*, i.e. executing CMake's configure step with `-DCPACK_GENERATOR=DEB`.
+You should use CMake/CPack 3.6.0 or higher. Lower versions can generate the packages but package names will be mangled.
+
+The following optional variables (which can be passed to buildsystem when executing cmake with the -D`<variable-name>=<value>` format) can be used to manipulate package type, name and version:
+
+- `DEBIAN_PACKAGE_TYPE` controls the name and version of generated packages. Accepted values are `stable`, `unstable` and `nightly` (default is `nightly`).
+- `DEBIAN_PACKAGE_EPOCH` controls package epoch (default is `2`)
+- `DEBIAN_PACKAGE_VERSION` controls package version (default is `0`)
+- `DEBIAN_PACKAGE_REVISION` controls package revision (no default is set)
+
+Packages metadata can be changed simply by editing files present in the `cpack/deb` folder
+A lot more variables are available (see cpack/CPackDebian.cmake file) but you shouldn't mess with them unless you know what you're doing.
+
+Generated packages can be found in <BUILD_DIR>/packages.
+
 ### Raspberry Pi with GNU Makefiles
 
 ```
@@ -96,23 +112,28 @@ cmake -DCMAKE_TOOLCHAIN_FILE=<KODI_SRC>/tools/depends/target/Toolchain.cmake <KO
 cmake --build . -- VERBOSE=1 -j$(nproc)  # or: make VERBOSE=1 -j$(nproc)
 ```
 
-### Windows with NMake Makefiles
+### Windows with Visual Studio project files
 
 ```
-cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release <KODI_SRC>/project/cmake/
-cmake --build .  # or: nmake
-kodi.exe
+cmake -G "Visual Studio 14" <KODI_SRC>/project/cmake/
+cmake --build . --config "Debug"  # or: Build solution with Visual Studio
+Debug\kodi.exe
 ```
 
-### Windows with Visual Studio project files
+#### Windows installer generation
+
+The script [project/Win32BuildSetup](https://github.com/xbmc/xbmc/blob/master/project/Win32BuildSetup/BuildSetup.bat)
+builds an installable package for Windows.
+
+### Windows with NMake Makefiles
 
 ```
-cmake -G "Visual Studio 14" <KODI_SRC>/project/cmake/
-cmake --build . --config "Debug"  # or: Build solution with Visual Studio
-set KODI_HOME="%CD%" && Debug\kodi.exe
+cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release <KODI_SRC>/project/cmake/
+cmake --build .  # or: nmake
+kodi.exe
 ```
 
-### OSX with GNU Makefiles
+### macOS with GNU Makefiles
 
 ```
 cmake -DCMAKE_TOOLCHAIN_FILE=<KODI_SRC>/tools/depends/target/Toolchain.cmake <KODI_SRC>/project/cmake/
@@ -120,12 +141,28 @@ cmake --build . -- VERBOSE=1 -j$(sysctl -n hw.ncpu)  # or: make VERBOSE=1 -j$(sy
 ./kodi.bin
 ```
 
-### OSX with Xcode project files
+### macOS with Xcode project files
 
 ```
 cmake -DCMAKE_TOOLCHAIN_FILE=<KODI_SRC>/tools/depends/target/Toolchain.cmake -G "Xcode" <KODI_SRC>/project/cmake/
 cmake --build . --config "Release" -- -verbose -jobs $(sysctl -n hw.ncpu)  # or: Build solution with Xcode
-KODI_HOME=$(pwd) ./Release/kodi.bin
+./Release/kodi.bin
+```
+
+#### macOS installer generation
+
+Afterwards an installable DMG for macOS can be built with the following command:
+
+```
+cmake --build . --config "Release" --target "dmg"  # or: make dmg
+```
+
+#### iOS package generation
+
+Consequently an installable DEB for iOS can be built with the following command:
+
+```
+make deb
 ```
 
 ### Android with GNU Makefiles
@@ -135,11 +172,107 @@ cmake -DCMAKE_TOOLCHAIN_FILE=<KODI_SRC>/tools/depends/target/Toolchain.cmake <KO
 cmake --build . -- VERBOSE=1 -j$(nproc)  # or: make VERBOSE=1 -j$(nproc)
 ```
 
+#### Android package generation
+
+An installable APK for Android can be built with the following command:
+
+```
+make apk
+```
+
+## Options
+
+Kodi supports a number of build options that can enable or disable certain
+functionality.i These options must be set when running CMake with
+`-DENABLE_<OPTION>=<ON|OFF|AUTO`. The default is `AUTO` which enables
+the option if a certain dependency is found. For example CEC support is
+enabled if libCEC is available. `ON` forcefully enables the dependency
+and the CMake run will fail if the related dependency is not available.
+This is mostly useful for packagers. `OFF` will disable the feature.
+
+Example for forcefully enabling VAAPI and disabling VDPAU:
+
+```
+cmake ... -DENABLE_VAAPI=ON -DENABLE_VDPAU=OFF ...
+```
+
+Example for building with external FFMPEG:
+
+```
+cmake ... -DFFMPEG_PATH=/opt/ffmpeg -DENABLE_INTERNAL_FFMPEG=OFF ...
+```
+
+For more information and an updated list of option, please check the
+main [project/cmake/CMakeLists.txt](https://github.com/xbmc/xbmc/tree/master/project/cmake/CMakeLists.txt).
+
+## Tests
+
+Kodi uses Google Test as its testing framework. Each test file is scanned for tests and these
+are added to CTest, which is the native test driver for CMake.
+
+This scanning happens at configuration time. If tests depend on generated support files which
+should not be scanned, then those support files should be added to the SUPPORT_SOURCES
+variable as opposed to SOURCES before calling core_add_test. You might want to do this where
+the generated support files would not exist at configure time, or if they are so large that
+scanning them would take up an unreasonable amount of configure time.
+
 ## Extra targets
 
 When using the makefile builds a few extra targets are defined:
 
 - `make check` builds and executes the test suite.
+- `make check-valgrind` builds and executes the test suite with valgrind memcheck.
+- `make doc` builds the Doxygen documentation.
+
+Code coverage (with Gcov, LCOV and Gcovr) can be built on Linux:
+
+- CMake has to be executed with `-DCMAKE_BUILD_TYPE=Coverage`
+- `make coverage` generates an HTML code coverage report.
+- `make coverage_xml` generates an XML code coverage report.
+
+## Building binary addons
+
+The CMake build system integrates with the addon build system if the GNU
+Makefile generator is used. This offers an easy way to build addons for
+packagers or Kodi developers who don't work on addons.
+
+```
+make binary-addons
+```
+
+Specific addons can be built with:
+
+```
+make binary-addons ADDONS="visualization.spectrum pvr.demo"
+```
+
+Addon developers can build single addons into the Kodi build directory
+so that the addon can be tested with self-compiled specific versions of Kodi.
+
+```
+mkdir pvr.demo-build && cd pvr.demo-build
+cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH=<KODI_BUILD_DIR>/build -DKODI_BUILD_DIR=<KODI_BUILD_DIR> <pvr.demo-SRC>
+make
+```
+
+It is recommended to specify the directories as absolute paths. If relative
+paths are used, they are considered relative to the build directory in which
+`cmake` was executed (aka the current working working directory).
+
+Both methods work only for already existing addons. See this
+[forum thread](http://forum.kodi.tv/showthread.php?tid=219166&pid=1934922#pid1934922)
+and [addons/README.md](https://github.com/xbmc/xbmc/blob/master/project/cmake/addons/README.md)
+for addon development and detailed documentation about the addon build system.
+
+## Sanitizers
+
+Clang and GCC support different kinds of Sanitizers. To enable a Sanitizer call CMake with the
+option `-DECM_ENABLE_SANITIZERS=’san1;san2;...'`. For more information about enabling the
+Sanitizers read the documentation in 
+[modules/extra/ECMEnableSanitizers.cmake](https://github.com/xbmc/xbmc/tree/master/project/cmake/modules/extra/ECMEnableSanitizers.cmake).
+
+It is also recommended to read the sections about the Sanitizers in the [Clang 
+documentation](http://clang.llvm.org/docs/).
 
 ## Debugging the build
 
-- 
cgit v1.2.3