[cmake][addons] Modernize README

2 files changed, 61 insertions, 94 deletions

diff --git a/project/cmake/addons/README b/project/cmake/addons/README
deleted file mode 100644
index a0f2c322cf..0000000000
--- a/project/cmake/addons/README
+++ /dev/null
@@ -1,94 +0,0 @@
-KODI ADDONS
-===========
-This directory contains the cmake-based buildsystem for addons. It looks into
-the directory pointed to by the ADDONS_DEFINITION_DIR option (which defaults to
-the "addons" sub-directory) and parses all *.txt files recursively. Each addon
-must have its own <addon-id>.txt file in a separate sub-directory which must
-follow one of the defined format:
-  <addon-id> <git-url> <git-revision>
-  <addon-id> <tarball-url>
-  <addon-id> <file://path>
-where
-  * <addon-id> must be identical to the addon's ID as defined in the addon's
-    addon.xml
-  * <git-url> must be the URL of the git repository containing the addon
-  * <git-revision> must be a valid git tag/branch/commit in the addon's git
-    repository which will be used for the build.
-  * <tarball-url> must be the URL to a .tar.gz tarball containing the addon
-  * <file://path> must be a file:// based path to the directory containing the
-    addon
-
-Reserved filenames (for additional information on how to build an addon)
-are:
-  * platforms.txt: List of platforms to build an addon for (or "all"). It is
-    also supported to specify negated platforms with a leading exclamation mark
-    (i), e.g. "!windows".
-    Available platforms are: linux, windows, osx, ios, android, rbpi, freebsd
-
-ATTENTION: If no addon definitions could be found the buildsystem assumes that
-           the bootstrapping of the addon definition repositories hasn't been
-           performed yet and automatically executes the addon bootstrapping
-           buildsystem located in the "bootstrap" sub-directory with the default
-           settings (i.e. all addons from all pre-defined addon definition
-           repositories are bootstrapped into the directory pointed to by the
-           ADDONS_DEFINITION_DIR option).
-
-The buildsystem uses the following variables (which can be passed into it when
-executing cmake with the -D<variable-name>=<value> option) to e.g. access
-specific paths:
-  * ADDONS_TO_BUILD has two variations, which are tested in order:
-     - a quoted, space delimited list of <addon-id>s that
-       you want to build (default is "all").
-     - a regular expression that every <addon-id> is matched against
-       e.g.: ADDONS_TO_BUILD=pvr.* to build all pvr addons
-  * ADDONS_DEFINITION_DIR points to the directory containing the definitions
-    for the addons to be built.
-  * ADDON_SRC_PREFIX can be used to override the addon repository location.
-    It must point to the locally available parent directory of the addon(s) to build
-    <addon-id> will be appended to this path automatically
-  * CMAKE_BUILD_TYPE specifies the type of the build. This can be either "Debug"
-    or "Release" (default is "Release").
-  * CMAKE_INSTALL_PREFIX points to the directory where the built addons and their
-    additional files (addon.xml, resources ...) will be installed to (defaults
-    to <DEPENDS_PATH>).
-  * CMAKE_TOOLCHAIN_FILE can be used to pass a toolchain file into the add-on
-    builds.
-  * DEPENDS_PATH points to the directory containing the "include" and "lib"
-    directories of the addons' dependencies.
-  * APP_ROOT points to the root directory of the project (default is the
-    absolute representation of ../../.. starting from this directory).
-  * BUILD_DIR points to the directory where the addons and their dependencies
-    will be downloaded and built.
-  * PACKAGE_ZIP=ON means that the add-ons will be 'packaged' into a common folder,
-    rather than being placed in <CMAKE_INSTALL_PREFIX>/lib/kodi/addons and
-    <CMAKE_INSTALL_PREFIX>/share/kodi/addons.
-  * PACKAGE_DIR points to the directory where the ZIP archived addons will be
-    stored after they have been packaged (defaults to <BUILD_DIR>/zips)
-  * ARCH_DEFINES specifies the platform-specific C/C++ preprocessor defines
-    (defaults to empty).
-  * ADDON_TARBALL_CACHING specifies whether downloaded addon source tarballs
-    should be cached or not (defaults to ON).
-
-The buildsystem makes some assumptions about the environment which must be met
-by whoever uses it:
-  * Any dependencies of the addons must already be built and their include and
-    library files must be present in the path pointed to by <CMAKE_PREFIX_PATH> (in
-    "include" and "lib" sub-directories).
-
-To trigger the cmake-based buildsystem the following command must be executed
-with <path> being the path to this directory (absolute or relative, allowing for
-in-source and out-of-source builds).
-
-  cmake <path> -G <generator>
-
-cmake supports multiple generators, see
-http://www.cmake.org/cmake/help/v2.8.8/cmake.html#section_Generators for a list.
-
-In case of additional options the call might look like this
-
-  cmake <path> [-G <generator>] \
-        -DCMAKE_BUILD_TYPE=Release \
-        -DAPP_ROOT="<path-to-app-root>" \
-        -DARCH_DEFINES="-DTARGET_LINUX" \
-        -DDEPENDS_PATH="<path-to-built-depends>" \
-        -DCMAKE_INSTALL_PREFIX="<path-to-install-directory"
diff --git a/project/cmake/addons/README.md b/project/cmake/addons/README.md
new file mode 100644
index 0000000000..c75ead7195
--- /dev/null
+++ b/project/cmake/addons/README.md
@@ -0,0 +1,61 @@
+![Kodi logo](https://raw.githubusercontent.com/xbmc/xbmc-forum/master/xbmc/images/logo-sbs-black.png)
+# Kodi add-ons CMake based buildsystem
+This directory contains the cmake-based buildsystem for Kodi add-ons. It looks into the directory pointed to by the *ADDONS_DEFINITION_DIR* option (which defaults to the *addons* sub-directory) and parses all *.txt files recursively. Each add-on must have its own `<addon-id>.txt` file in a separate sub-directory that must follow one of the defined formats:
+
+  - `<addon-id> <git-url> <git-revision>`
+  - `<addon-id> <tarball-url>`
+  - `<addon-id> <file://path>`
+ 
+where
+- `<addon-id>` must be identical to the add-on's ID as defined in the add-on's addon.xml
+- `<git-url>` must be the URL of the git repository containing the add-on
+- `<git-revision>` must be a valid git tag/branch/commit in the add-on's git repository which will be used for the build
+- `<tarball-url>` must be the URL to a .tar.gz tarball containing the add-on
+- `<file://path>` must be a *file://* based path to the directory containing the add-on
+
+## Reserved filenames
+- **platforms.txt**
+
+List of platforms to build an add-on for (or *all*). Negating platforms is supported using a leading exclamation mark, e.g. *!windows*.
+
+Available platforms are: linux, windows, osx, ios, android, rbpi and freebsd.
+
+#### Attention
+If no add-on definitions could be found, the buildsystem assumes that the bootstrapping of the add-on definition repositories hasn't been performed yet and automatically executes the add-on bootstrapping buildsystem located in the *bootstrap* sub-directory with the default settings (i.e. *all* add-ons from all pre-defined add-on definition repositories are bootstrapped into the directory pointed to by the *ADDONS_DEFINITION_DIR* option).
+
+## Buildsystem variables
+The buildsystem uses the following variables (which can be passed into it when executing cmake with the -D`<variable-name>=<value>` format) to manipulate the build process:
+- `ADDONS_TO_BUILD` has two variations, which are tested in order:
+     - a quoted, space delimited list of `<addon-id>s` that you want to build (default is *all*)
+     - a regular expression that every `<addon-id>` is matched against (e.g. `ADDONS_TO_BUILD="pvr.*"`) to build all pvr add-ons
+- `ADDONS_DEFINITION_DIR` points to the directory containing the definitions for the addons to be built
+- `ADDON_SRC_PREFIX` can be used to override the add-on repository location. It must point to the locally available parent directory of the add-on(s) to build. `<addon-id>` will be appended to this path automatically
+- `CMAKE_BUILD_TYPE` specifies the type of the build. This can be either *Debug* or *Release* (default is *Release*)
+- `CMAKE_INSTALL_PREFIX` points to the directory where the built add-ons and their additional files (addon.xml, resources, ...) will be installed to (defaults to `<DEPENDS_PATH>`)
+- `CMAKE_TOOLCHAIN_FILE` can be used to pass a toolchain file into the add-on builds
+- `DEPENDS_PATH` points to the directory containing the *include* and *lib* directories of the add-ons' dependencies.
+- `APP_ROOT` points to the root directory of the project (default is the absolute representation of ../../.. starting from this directory)
+- `BUILD_DIR` points to the directory where the add-ons and their dependencies will be downloaded and built
+- `PACKAGE_ZIP=ON` means that the add-ons will be 'packaged' into a common folder, rather than being placed in `<CMAKE_INSTALL_PREFIX>/lib/kodi/addons` and `<CMAKE_INSTALL_PREFIX>/share/kodi/addons`
+- `PACKAGE_DIR` points to the directory where the ZIP archived add-ons will be stored after they have been packaged (defaults to `<BUILD_DIR>/zips`)
+- `ARCH_DEFINES` specifies the platform-specific C/C++ preprocessor defines (defaults to empty)
+- `ADDON_TARBALL_CACHING` specifies whether downloaded add-on source tarballs should be cached or not (defaults to *ON*)
+
+## Building
+The buildsystem makes some assumptions about the environment which must be met by whoever uses it:
+- Any dependencies of the add-ons must already be built and their include and library files must be present in the path pointed to by `<CMAKE_PREFIX_PATH>` (in *include* and *lib* sub-directories)
+
+To trigger the cmake-based buildsystem the following command must be executed with `<path>` set to this directory (absolute or relative) allowing for in-source and out-of-source builds
+
+`cmake <path> -G <generator>`
+
+CMake supports multiple generators. See [here] (https://cmake.org/cmake/help/v3.1/manual/cmake-generators.7.html) for a list.
+
+In case of additional options the call might look like this:
+
+cmake `<path>` [-G `<generator>`] \  
+      -DCMAKE_BUILD_TYPE=Release \  
+      -DAPP_ROOT="`<path-to-app-root>`" \  
+      -DARCH_DEFINES="-DTARGET_LINUX" \  
+      -DDEPENDS_PATH=`<path-to-built-depends>` \  
+      -DCMAKE_INSTALL_PREFIX="`<path-to-install-directory`"