From f177baf48d4ebbcc87cf604f4ca7bffb8fb73701 Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Sat, 21 Apr 2018 11:13:08 +0200 Subject: [PATCH 1/5] documentation: package.mk --- packages/addons/README.md | 45 ------ packages/packages.mk.addon_template | 54 +++++++ packages/packages.mk.template | 42 +++++ packages/readme.md | 233 ++++++++++++++++++++++++++++ 4 files changed, 329 insertions(+), 45 deletions(-) delete mode 100644 packages/addons/README.md create mode 100644 packages/packages.mk.addon_template create mode 100644 packages/packages.mk.template create mode 100644 packages/readme.md diff --git a/packages/addons/README.md b/packages/addons/README.md deleted file mode 100644 index 15515f3a0f..0000000000 --- a/packages/addons/README.md +++ /dev/null @@ -1,45 +0,0 @@ -#add-on package.mk skeleton -This file shows a skeleton example of an add-on package.mk with content notes. Except for the license header, any lines prefixed with `#` are optional and may be omitted if not required. - -```shell -################################################################################ -# This file is part of LibreELEC - https://LibreELEC.tv -# Copyright (C) 2016 Team LibreELEC -# -# LibreELEC is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 2 of the License, or -# (at your option) any later version. -# -# LibreELEC is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with LibreELEC. If not, see . -################################################################################ - -PKG_NAME="myprogram" # same as the folder name -PKG_VERSION="1.0.1" # version or 7 digit-hash -PKG_REV="100" # currently we start at 100 to solve OE update problems -PKG_ARCH="any" # for available architectures, see LE/config/arch.* files -# PKG_ADDON_PROJECTS="any !RPi1 !Amlogic" # for available projects or devices, see projects subdirectory (note: Use RPi for RPi project, and RPi1 for RPi device) -PKG_LICENSE="GPL" # program licenses, see licenses subdirectory for a list -PKG_SITE="http://www.site.org" -PKG_URL="http://www.site.org/$PKG_VERSION.tar.xz" # for github see the other packages, prefer tar.xz over .gz -# PKG_SOURCE_DIR="somename-${PKG_VERSION}*" # if the folder inside the zip is different to the pkg name -PKG_DEPENDS_TARGET="toolchain curl" # dependencies that are needed that the addon builds -PKG_SECTION="service" # service, tools, virtual, driver, driver.remote ... -PKG_SHORTDESC="Addon name: sort description" # Addon: is a program that does this and that -PKG_LONGDESC="Addon name ($PKG_VERSION): detailed description" -PKG_TOOLCHAIN="auto" # auto, meson, cmake, cmake-make, configure, make, ninja, autotools, manual - -PKG_IS_ADDON="yes" -PKG_ADDON_NAME="Addon name" # proper name of the addon that is shown at the repo -PKG_ADDON_TYPE="xbmc.service" # see LE/config/addon/ for other possibilities -# PKG_ADDON_PROVIDES="executable" # http://kodi.wiki/view/addon.xml#.3Cprovides.3E_element -PKG_ADDON_REPOVERSION="8.0" # for what main version it should be compatible -# PKG_ADDON_REQUIRES="some.addon:0.0.0" # http://kodi.wiki/view/addon.xml#.3Crequires.3E -# PKG_MAINTAINER="John Doe (email)" # if you want to be know as maintainer for a addon -``` diff --git a/packages/packages.mk.addon_template b/packages/packages.mk.addon_template new file mode 100644 index 0000000000..7604271110 --- /dev/null +++ b/packages/packages.mk.addon_template @@ -0,0 +1,54 @@ +################################################################################ +# This file is part of LibreELEC - https://libreelec.tv +# Copyright (C) 2018-present Team LibreELEC +# +# LibreELEC is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 2 of the License, or +# (at your option) any later version. +# +# LibreELEC is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with LibreELEC. If not, see . +################################################################################ + +PKG_NAME="[package name]" +PKG_VERSION="[package upstream version]" +PKG_REV="100" +PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" +PKG_ARCH="any" +PKG_LICENSE="[license of the upstream project]" +PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" +PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" +# PKG_MAINTAINER="John Doe (email)" # if you want to be know as maintainer for a addon +PKG_DEPENDS_TARGET="[needed packages for build, e.g. toolchain zlib openssl]" +PKG_SECTION="[location under packages, e.g. database]" +PKG_SHORTDESC="[short description (mostly find at the upstrem project), e.g. libexample: library to calculate examples]" +PKG_LONGDESC="[long description (mostly find at the upstrem project), e.g. libexample: this project is created for case x and y, to do it, in a best way...]" +# PKG_TOOLCHAIN="auto" or one of meson, cmake, cmake-make, configure, make, ninja, autotools, manual + +PKG_IS_ADDON="yes" +PKG_ADDON_NAME="[proper name of the addon that is shown at the repo]" +PKG_ADDON_TYPE="[type]" +# PKG_ADDON_PROJECTS="[project, only set when not any]" +# PKG_ADDON_PROVIDES="executable" +# PKG_ADDON_REQUIRES="some.addon:0.0.0" + +# build specific variables +#PKG_CMAKE_OPTS_TARGET="-DWITH_EXAMPLE_PATH=/storage/.example +# " + +#pre_configure_target() { +# do something, or drop it +#} + +addon() { + # copy needed files from other packages (which are not in the image) +} + +# see https://github.com/LibreELEC/LibreELEC.tv/blob/master/packages/readme.md for more +# take a look to other packages, for inspiration diff --git a/packages/packages.mk.template b/packages/packages.mk.template new file mode 100644 index 0000000000..a84827abb5 --- /dev/null +++ b/packages/packages.mk.template @@ -0,0 +1,42 @@ +################################################################################ +# This file is part of LibreELEC - https://libreelec.tv +# Copyright (C) 2018-present Team LibreELEC +# +# LibreELEC is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 2 of the License, or +# (at your option) any later version. +# +# LibreELEC is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with LibreELEC. If not, see . +################################################################################ + +PKG_NAME="[package name]" +PKG_VERSION="[package upstream version]" +PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" +PKG_ARCH="any" +PKG_LICENSE="[license of the upstream project]" +PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" +PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" +# PKG_MAINTAINER="John Doe (email)" # if you want to be know as maintainer for a addon +PKG_DEPENDS_TARGET="[needed packages for build, e.g. toolchain zlib openssl]" +PKG_SECTION="[location under packages, e.g. database]" +PKG_SHORTDESC="[short description (mostly find at the upstrem project), e.g. libexample: library to calculate examples]" +PKG_LONGDESC="[long description (mostly find at the upstrem project), e.g. libexample: this project is created for case x and y, to do it, in a best way...]" +# PKG_TOOLCHAIN="auto" + +# build specific variables +#PKG_CMAKE_OPTS_TARGET="-DWITH_EXAMPLE_PATH=/storage/.example +# " + +#pre_configure_target() { +# do something, or drop it +#} + +# see https://github.com/LibreELEC/LibreELEC.tv/blob/master/packages/readme.md for more +# take a look to other packages, for inspiration diff --git a/packages/readme.md b/packages/readme.md new file mode 100644 index 0000000000..f43b8031cd --- /dev/null +++ b/packages/readme.md @@ -0,0 +1,233 @@ +# Structure of package.mk files + +## Introduction + +The package.mk file defines variables and functions to build a package. + +## Variables +All avialible variable, to control the build behavoir of your package. +Please use these in the order, listed here. + +#### Base + +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_NAME | - | yes | Name of the packaged software application. Should be lowercase | +| PKG_VERSION | - | yes | Version of the packaged software application | +| PKG_SHA256 | - | yes | SHA256 hashsum of the application download file | +| PKG_ARCH | any | no | Architectures for which the package builds. `any` or a space separated list of `aarch64`, `arm` or `x86_64` | +| PKG_LICENSE | - | yes | License of the software application. [Reference](https://github.com/LibreELEC/LibreELEC.tv/tree/master/licenses) | +| PKG_SITE | - | yes | Site of the software application | +| PKG_URL | - | yes | Address at which the source of the software application can be retrieved | +| PKG_MAINTAINER | - | no | Your name | +| PKG_DEPENDS_BOOTSTRAP
PKG_DEPENDS_HOST PKG_DEPENDS_INIT PKG_DEPENDS_TARGET | - | no | A space separated list of name of packages required to build the software application | +| PKG_SECTION | - | no | virtual if the package only defines dependencies | +| PKG_SHORTDESC | - | no
yes for addons | Short description of the application software used in various parts of Kodi | +| PKG_LONGDESC | - | yes | Long description of the application software used in various parts of Kodi | + +#### Universal Build Option +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_SOURCE_DIR | - | no | Name of the folder to which the source of the software application unpacks. Should only be specified if the source of the software application unpacks to a folder whose name does not start with `$PKG_NAME` | +| PKG_SOURCE_NAME | - | no | Name of the file of the source of the software application. Should only be specified if the source of the software application is not the basename of PKG_URL | +| PKG_PATCH_DIRS | - | no | Change the path for pachtes, to apply to source. Normally the path `./patches` is used. Is this variable is set, the normal path will extended with the value of this variable as a subdirectory: `./patches/${PKG_PATCH_DIRS}` | +| PKG_NEED_UNPACK | - | no | ??? can anyone explane, i have no idea. | +| PKG_TOOLCHAIN | auto | no | Control which of the build toolchains is used. For detailed information, see the [Reference](#toolchain-options). | +| PKG_BUILD_FLAGS | - | no | A Space seperated list of flags, which control often used build modification. Flags can be enabled or disables with a prefixed `+`/`-`. For detailed information, see the [Reference](#build_flags-options). | +| PKG_PYTHON_VERSION | python2.7 | no | Defines the Python version, which should use. | +| PKG_IS_KERNEL_PKG | - | no | Set it to `yes`, for packages which include linux kernel modules | + +#### Meson Options +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_MESON_SCRIPT | $PKG_BUILD/meson.build | no | Meson build file to use | +| PKG_MESON_OPTS_TARGET | - | no | Options directly passed to meson | + +#### CMAKE Options +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_CMAKE_SCRIPT | $PKG_BUILD/CMakeLists.txt | no | CMake build file to use | +| PKG_CMAKE_OPTS_HOST
PKG_CMAKE_OPTS_TARGET | - | no | Options directly passed to cmake | + +#### Configure Options +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_CONFIGURE_SCRIPT | $PKG_BUILD/configure | no | configure script to use | +| PKG_CONFIGURE_OPTS
PKG_CONFIGURE_OPTS_BOOTSTRAP
PKG_CONFIGURE_OPTS_HOST
PKG_CONFIGURE_OPTS_INIT
PKG_CONFIGURE_OPTS_TARGET | - | no | Options directly passed to configure | + +#### Make Options +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_MAKE_OPTS
PKG_MAKE_OPTS_BOOTSTRP
PKG_MAKE_OPTS_HOST
PKG_MAKE_OPTS_INIT
PKG_MAKE_OPTS_TARGET | - | no | Options directly passed to make in the build step +| PKG_MAKEINSTALL_OPTS_HOST
PKG_MAKEINSTALL_OPTS_TARGET | - | no | Options directly passed to make in the install step + +#### Addons +These options only needed, when the package is build as an addon. +"Required" column is focus addon packages, only. When the package is no addon, none of these options is required. + +| Variable | Default | Required |Description | +|-------------|---------|----------|------------| +| PKG_REV | - | yes | The revision number of the addon. Increase on every version. Currently starts at `100`. Please place this variable under `PKG_VERSION` | +| PKG_IS_ADDON | no | yes | Have to set to `yes` | +| PKG_ADDON_NAME | - | yes | Proper name of the addon that is shown at the repo | +| PKG_ADDON_TYPE | - | yes | See LE/config/addon/ for other possibilities | +| PKG_ADDON_VERSION | - | no | The version of the addon, used in addon.xml | +| PKG_ADDON_PROVIDES | - | no | [Provides](http://kodi.wiki/view/addon.xml#.3Cprovides.3E_element) in addon-xml | +| PKG_ADDON_REQUIRES | - | no | [Requires](http://kodi.wiki/view/addon.xml#.3Crequires.3E) used in addon.xml | +| PKG_ADDON_PROJECTS | @PROJECTS@ | no | for available projects or devices, see projects subdirectory (note: Use RPi for RPi project, and RPi1 for RPi device) | +| PKG_DISCLAIMER | - | no | [Disclaimer](https://kodi.wiki/view/Addon.xml#.3Cdisclaimer.3E) in addon-xml | +| PKG_ADDON_IS_STANDALONE | - | no | Defines if an addon depends on Kodi (on) or is standalone (yes) | +| PKG_ADDON_BROKEN | - | no | Marks an addon as broken for the user | + +#### Detail Infomations for Options + +##### TOOLCHAIN options + +Application/packages needs different toolchains for build. +For instance `cmake` or the classic `./configure` or same very different. + +For the most application/packages, the auto-detection of the toolchain works proper. +But not always. To select a specific toolchain, you only need to set the `PKG_TOOLCHAIN` variable. + +| Toolchain | Description (if needed) | +|----------- |-------------------------| +| meson | [Meson Build System](http://mesonbuild.com/) | +| cmake | [CMake](https://cmake.org/) with Ninja | +| cmake-make | [CMake](https://cmake.org/) with Make | +| autotools | [GNU Build System](https://en.wikipedia.org/wiki/GNU_Build_System) +| configure | preconfigured [GNU Build System](https://en.wikipedia.org/wiki/GNU_Build_System) | +| ninja | [Ninja Build](https://ninja-build.org/) | +| make | [Makefile Based](https://www.gnu.org/software/make/) | +| manual | only runs self writen build steps, see [Functions](#functions) | + +###### Auto-Detection +The auto-detections looks for specific files in the source path. + +1. `meson.build` (PKG_MESON_SCRIPT) => meson toolchain +2. `CMakeLists.txt` (PKG_CMAKE_SCRIPT) => cmake toolchain +3. `configure` (PKG_CONFIGURE_SCRIPT) => configure toolchain +4. `Makefile` => make toolchain + +When none of these was found, the build abort and you have to set the toolchain via `PKG_TOOLCHAIN` + +##### BUILD_FLAGS options + +Build flags implement often used build options. Normally these are activated be default, but single applications/packages has problems to compile/run with these. + +Set the variable `PKG_BUILD_FLAGS` in the `package.mk` to enable/disable the single flags. It is a space seperated list. The flags can enabled with a `+` prefix, and disables with an `-`. + +| flag | default | affected stage | description | +|----------|----------|----------------|-------------| +| pic | disabled | target/init | [Position Independent Code](https://en.wikipedia.org/wiki/Position-independent_code) | +| pic:host | disabled | host/bootstrap | see above | +| lto | depend on `LTO_SUPPORT` | target/init | can only disabled, use of "Link Time Optimisation" of the compiler | +| gold | depend on `GOLD_SUPPORT` | target/init | can only disabled, use of the GOLD-Linker | +| parallel | enabled | all | `make` or `ninja` builds with multiple threads/processes (or not) | + +###### Example +``` +PKG_BUILD_FLAGS="+pic -gold" +PKG_BUILD_FLAGS="-parallel" +``` + +## Functions +All build steps in the LibreELEC build system, a done by shell function. +These functions can overwritten in the `package.mk`. But this raises problems, when the build system ist updated. To reduce the problem, most function was extended by `pre_` and `post_` scripts, to use instead. + +When it is nesseary to replace configure, make and makeinstall, please use `PKG_TOOLCHAIN="manual"`. + +Some of the build steps needs to be run once, like `unpack`. Other steps needs to be run multiple times, to create the toolchain (stage bootstrap & host) or to create the LE image (stage init & target). These stage specific functions have the stage as suffix, like `make_target`. + +Full list of overwrittable functions. + +| function | stages specific | description | +|-------------------------|--------|-------------| +| unpack
pre_unpack
post_unpack | - | Extract the source from the downloaded file | +| pre_patch
post_patch | - | Apply the patches to the source, after extraction. The patch function it self is not allowed to overwritten | +| pre_build_\[stage] | yes | Runs before of the start of the build | +| configure_\[stage]
pre_configure_\[stage]
post_configure_\[stage] | yes | Configure the package for the compile. This is only relevant for toolchain, that supports it (e.g. meson, cmake, configure, manual) | +| make_\[stage]
pre_make_\[stage]
post_make_\[stage] | yes | Build of the package | +| makeinstall_\[stage]
pre_makeinstall_\[stage]
post_makeinstall_\[stage] | yes | Installation of the files in the correct pathes
host: TOOLCHAIN
target: SYSROOT and IMAGE
bootstrap and init: temporar destination +| addon | - | Copy all files together for addon creation. This is requiered for addons | + +###### Example +``` +post_patch() { + # replace hardcoded stuff + sed -i $PKG_BUILD/Makefile 's|hardcoded stuff|variabled stuff|' +} + +pre_configure_target() { + CFLAGS="$CFLAGS -DEXTRA_FLAG=yeah" +} + +post_makeinstall_target() { + # remove unused executable, only library needed + rm $INSTALL/usr/bin/bigexecutable +} +``` + +## Add a new package to the Image +1. Think about, why you needs it in the image. + * new multimedia tool + * add a new network tool + * new kernel driver + * ... +* Find a place in the packages-tree + * look into the package-tree, i think most is self explaind. When 1. was done, this is going fast :) + * do not place it, in an existing package (directory with includes a `package.mk`) + * when you found a place, create a directory with the name of your package (must the same like PKG_NAME!!) +* Create a initial `package.mk` + * you found a template under `packages/package.mk.template`. copy the template into the new directory and call it `package.mk` + * edit your new `package.mk` +* Find a place in the dependency tree. When 1. was done, this is going fast, again :) + * when it extend an existing package, add it there to the `PKG_DEPENDS_TARGET` + * take a look into the path `packages/virtual`, there you should find a virtual packages, that match your new package (misc-packages should the last option) +* now you can build your image + * when ist was build, under build-[...]/ should apear a directory with your package-name and -version. + +## Example +``` +################################################################################ +# This file is part of LibreELEC - https://libreelec.tv +# Copyright (C) 2018-present Team LibreELEC +# +# LibreELEC is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 2 of the License, or +# (at your option) any later version. +# +# LibreELEC is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with LibreELEC. If not, see . +################################################################################ + +PKG_NAME="mariadb-connector-c" +PKG_VERSION="3.0.2" +PKG_SHA256="f44f436fc35e081db3a56516de9e3bb11ae96838e75d58910be28ddd2bc56d88" +PKG_ARCH="any" +PKG_LICENSE="LGPL" +PKG_SITE="https://mariadb.org/" +PKG_URL="https://github.com/MariaDB/mariadb-connector-c/archive/v$PKG_VERSION.tar.gz" +PKG_DEPENDS_TARGET="toolchain zlib openssl" +PKG_SECTION="database" +PKG_SHORTDESC="mariadb-connector: library to conntect to mariadb/mysql database server" +PKG_LONGDESC="mariadb-connector: library to conntect to mariadb/mysql database server" + +PKG_CMAKE_OPTS_TARGET="-DWITH_EXTERNAL_ZLIB=ON + -DAUTH_CLEARTEXT=STATIC + -DAUTH_DIALOG=STATIC + -DAUTH_OLDPASSWORD=STATIC + -DREMOTEIO=OFF + " + +post_makeinstall_target() { + # drop all unneeded + rm -rf $INSTALL/usr +} +``` + From d152261f09e5a822347782eb94a95a84a5175d05 Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Sat, 26 May 2018 10:38:41 +0200 Subject: [PATCH 2/5] documentation: spelling fixes from @chewitt & @MilhouseVH --- packages/packages.mk.addon_template | 10 ++++----- packages/packages.mk.template | 10 ++++----- packages/readme.md | 32 ++++++++++++++--------------- 3 files changed, 25 insertions(+), 27 deletions(-) diff --git a/packages/packages.mk.addon_template b/packages/packages.mk.addon_template index 7604271110..1d52e7fca3 100644 --- a/packages/packages.mk.addon_template +++ b/packages/packages.mk.addon_template @@ -17,18 +17,18 @@ ################################################################################ PKG_NAME="[package name]" -PKG_VERSION="[package upstream version]" +PKG_VERSION="[package version identifier or unique githash]" PKG_REV="100" PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" PKG_ARCH="any" PKG_LICENSE="[license of the upstream project]" PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" -# PKG_MAINTAINER="John Doe (email)" # if you want to be know as maintainer for a addon -PKG_DEPENDS_TARGET="[needed packages for build, e.g. toolchain zlib openssl]" +# PKG_MAINTAINER="John Doe" # Full name or forum/GitHub nickname, if you want to be identified as the addon maintainer +PKG_DEPENDS_TARGET="[build system dependencies, e.g. toolchain zlib openssl]" PKG_SECTION="[location under packages, e.g. database]" -PKG_SHORTDESC="[short description (mostly find at the upstrem project), e.g. libexample: library to calculate examples]" -PKG_LONGDESC="[long description (mostly find at the upstrem project), e.g. libexample: this project is created for case x and y, to do it, in a best way...]" +PKG_SHORTDESC="[short description of the package, e.g. libexample: library to calculate examples]" +PKG_LONGDESC="[long description of the package, often taken from the package/project website, e.g. libexample: this project is created to calculate examples for x and y, with maximum efficiency and fewer errors]" # PKG_TOOLCHAIN="auto" or one of meson, cmake, cmake-make, configure, make, ninja, autotools, manual PKG_IS_ADDON="yes" diff --git a/packages/packages.mk.template b/packages/packages.mk.template index a84827abb5..4a65da137c 100644 --- a/packages/packages.mk.template +++ b/packages/packages.mk.template @@ -17,17 +17,17 @@ ################################################################################ PKG_NAME="[package name]" -PKG_VERSION="[package upstream version]" +PKG_VERSION="[package version identifier or unique githash]" PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" PKG_ARCH="any" PKG_LICENSE="[license of the upstream project]" PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" -# PKG_MAINTAINER="John Doe (email)" # if you want to be know as maintainer for a addon -PKG_DEPENDS_TARGET="[needed packages for build, e.g. toolchain zlib openssl]" +# PKG_MAINTAINER="John Doe" # Full name or forum/GitHub nickname, if you want to be identified as the addon maintainer +PKG_DEPENDS_TARGET="[build system dependencies, e.g. toolchain zlib openssl]" PKG_SECTION="[location under packages, e.g. database]" -PKG_SHORTDESC="[short description (mostly find at the upstrem project), e.g. libexample: library to calculate examples]" -PKG_LONGDESC="[long description (mostly find at the upstrem project), e.g. libexample: this project is created for case x and y, to do it, in a best way...]" +PKG_SHORTDESC="[short description of the package, e.g. libexample: library to calculate examples]" +PKG_LONGDESC="[long description of the package, often taken from the package/project website, e.g. libexample: this project is created to calculate examples for x and y, with maximum efficiency and fewer errors]" # PKG_TOOLCHAIN="auto" # build specific variables diff --git a/packages/readme.md b/packages/readme.md index f43b8031cd..650a06b202 100644 --- a/packages/readme.md +++ b/packages/readme.md @@ -5,8 +5,7 @@ The package.mk file defines variables and functions to build a package. ## Variables -All avialible variable, to control the build behavoir of your package. -Please use these in the order, listed here. +To control the build behaviour of your package, use variables in the top-down order listed here. #### Base @@ -22,20 +21,20 @@ Please use these in the order, listed here. | PKG_MAINTAINER | - | no | Your name | | PKG_DEPENDS_BOOTSTRAP
PKG_DEPENDS_HOST PKG_DEPENDS_INIT PKG_DEPENDS_TARGET | - | no | A space separated list of name of packages required to build the software application | | PKG_SECTION | - | no | virtual if the package only defines dependencies | -| PKG_SHORTDESC | - | no
yes for addons | Short description of the application software used in various parts of Kodi | -| PKG_LONGDESC | - | yes | Long description of the application software used in various parts of Kodi | +| PKG_SHORTDESC | - | no
yes for addons | Short description of the software package | +| PKG_LONGDESC | - | yes | Long description of the package including purpose or function within LibreELEC or Kodi | #### Universal Build Option | Variable | Default | Required |Description | |-------------|---------|----------|------------| -| PKG_SOURCE_DIR | - | no | Name of the folder to which the source of the software application unpacks. Should only be specified if the source of the software application unpacks to a folder whose name does not start with `$PKG_NAME` | -| PKG_SOURCE_NAME | - | no | Name of the file of the source of the software application. Should only be specified if the source of the software application is not the basename of PKG_URL | -| PKG_PATCH_DIRS | - | no | Change the path for pachtes, to apply to source. Normally the path `./patches` is used. Is this variable is set, the normal path will extended with the value of this variable as a subdirectory: `./patches/${PKG_PATCH_DIRS}` | -| PKG_NEED_UNPACK | - | no | ??? can anyone explane, i have no idea. | -| PKG_TOOLCHAIN | auto | no | Control which of the build toolchains is used. For detailed information, see the [Reference](#toolchain-options). | -| PKG_BUILD_FLAGS | - | no | A Space seperated list of flags, which control often used build modification. Flags can be enabled or disables with a prefixed `+`/`-`. For detailed information, see the [Reference](#build_flags-options). | -| PKG_PYTHON_VERSION | python2.7 | no | Defines the Python version, which should use. | -| PKG_IS_KERNEL_PKG | - | no | Set it to `yes`, for packages which include linux kernel modules | +| PKG_SOURCE_DIR | - | no | Force the folder name that application sources are unpacked to. Used when sources do not automatically unpack to a folder with the `PKG_NAME-PKG_VERSION` naming convention. | +| PKG_SOURCE_NAME | - | no | Force the filename of the application sources. Used when the filename is not the basename of `PKG_URL` | +| PKG_PATCH_DIRS | - | no | Patches in `./patches` are automatically applied after package unpack. Use this option to include patches from an additional folder, e.g. `./patches/$PKG_PATCH_DIRS` | +| PKG_NEED_UNPACK | - | no | Space separated list of files or folders to include in package stamp calculation. If the stamp is invalidated through changes to package files or dependent files/folders the package is cleaned and rebuilt. e.g. `PKG_NEED_UNPACK="$(get_pkg_directory linux)"` will trigger clean/rebuild of a Linux kernel driver package when a change to the `linux` kernel package is detected. | +| PKG_TOOLCHAIN | auto | no | Control which build toolchain is used. For detailed information, see [reference](#toolchain-options). | +| PKG_BUILD_FLAGS | - | no | A space separated list of flags with which to fine-tune the build process. Flags can be enabled or disabled with a `+` or `-` prefix. For detailed information, see the [Reference](#build_flags-options). | +| PKG_PYTHON_VERSION | python2.7 | no | Define the Python version to be used. | +| PKG_IS_KERNEL_PKG | - | no | Set to `yes` for packages that include Linux kernel modules | #### Meson Options | Variable | Default | Required |Description | @@ -62,13 +61,12 @@ Please use these in the order, listed here. | PKG_MAKEINSTALL_OPTS_HOST
PKG_MAKEINSTALL_OPTS_TARGET | - | no | Options directly passed to make in the install step #### Addons -These options only needed, when the package is build as an addon. -"Required" column is focus addon packages, only. When the package is no addon, none of these options is required. +Additional options used when the package builds an addon. | Variable | Default | Required |Description | |-------------|---------|----------|------------| -| PKG_REV | - | yes | The revision number of the addon. Increase on every version. Currently starts at `100`. Please place this variable under `PKG_VERSION` | -| PKG_IS_ADDON | no | yes | Have to set to `yes` | +| PKG_REV | - | yes | The revision number of the addon (starts at 100). Must be placed after `PKG_VERSION`. Must be incremented for each new version else Kodi clients will not detect version change and download the updated addon. | +| PKG_IS_ADDON | no | yes | Must be set to `yes` | | PKG_ADDON_NAME | - | yes | Proper name of the addon that is shown at the repo | | PKG_ADDON_TYPE | - | yes | See LE/config/addon/ for other possibilities | | PKG_ADDON_VERSION | - | no | The version of the addon, used in addon.xml | @@ -114,7 +112,7 @@ When none of these was found, the build abort and you have to set the toolchain Build flags implement often used build options. Normally these are activated be default, but single applications/packages has problems to compile/run with these. -Set the variable `PKG_BUILD_FLAGS` in the `package.mk` to enable/disable the single flags. It is a space seperated list. The flags can enabled with a `+` prefix, and disables with an `-`. +Set the variable `PKG_BUILD_FLAGS` in the `package.mk` to enable/disable the single flags. It is a space separated list. The flags can enabled with a `+` prefix, and disables with an `-`. | flag | default | affected stage | description | |----------|----------|----------------|-------------| From 9c868de0ec3277642878fc44f57b90a322a6d3df Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Sat, 26 May 2018 10:56:21 +0200 Subject: [PATCH 3/5] documentation: more spelling fixes --- packages/readme.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/readme.md b/packages/readme.md index 650a06b202..109dc27014 100644 --- a/packages/readme.md +++ b/packages/readme.md @@ -112,7 +112,7 @@ When none of these was found, the build abort and you have to set the toolchain Build flags implement often used build options. Normally these are activated be default, but single applications/packages has problems to compile/run with these. -Set the variable `PKG_BUILD_FLAGS` in the `package.mk` to enable/disable the single flags. It is a space separated list. The flags can enabled with a `+` prefix, and disables with an `-`. +Set the variable `PKG_BUILD_FLAGS` in the `package.mk` to enable/disable the single flags. It is a space separated list. The flags can enabled with a `+` prefix, and disabled with a `-`. | flag | default | affected stage | description | |----------|----------|----------------|-------------| @@ -130,7 +130,7 @@ PKG_BUILD_FLAGS="-parallel" ## Functions All build steps in the LibreELEC build system, a done by shell function. -These functions can overwritten in the `package.mk`. But this raises problems, when the build system ist updated. To reduce the problem, most function was extended by `pre_` and `post_` scripts, to use instead. +These functions can overwritten in the `package.mk`. But this raises problems, when the build system is updated. To reduce the problem, most function was extended by `pre_` and `post_` scripts, to use instead. When it is nesseary to replace configure, make and makeinstall, please use `PKG_TOOLCHAIN="manual"`. @@ -145,7 +145,7 @@ Full list of overwrittable functions. | pre_build_\[stage] | yes | Runs before of the start of the build | | configure_\[stage]
pre_configure_\[stage]
post_configure_\[stage] | yes | Configure the package for the compile. This is only relevant for toolchain, that supports it (e.g. meson, cmake, configure, manual) | | make_\[stage]
pre_make_\[stage]
post_make_\[stage] | yes | Build of the package | -| makeinstall_\[stage]
pre_makeinstall_\[stage]
post_makeinstall_\[stage] | yes | Installation of the files in the correct pathes
host: TOOLCHAIN
target: SYSROOT and IMAGE
bootstrap and init: temporar destination +| makeinstall_\[stage]
pre_makeinstall_\[stage]
post_makeinstall_\[stage] | yes | Installation of the files in the correct pathes
host: TOOLCHAIN
target: SYSROOT and IMAGE
bootstrap and init: temporary destination | addon | - | Copy all files together for addon creation. This is requiered for addons | ###### Example @@ -171,18 +171,18 @@ post_makeinstall_target() { * add a new network tool * new kernel driver * ... -* Find a place in the packages-tree +2. Find a place in the packages-tree * look into the package-tree, i think most is self explaind. When 1. was done, this is going fast :) * do not place it, in an existing package (directory with includes a `package.mk`) - * when you found a place, create a directory with the name of your package (must the same like PKG_NAME!!) -* Create a initial `package.mk` - * you found a template under `packages/package.mk.template`. copy the template into the new directory and call it `package.mk` + * when you found a place, create a directory with the name of your package (must the same like `PKG_NAME`!!) +3. Create a initial `package.mk` + * you found a template under `packages/package.mk.template`. Copy the template into the new directory and call it `package.mk` * edit your new `package.mk` -* Find a place in the dependency tree. When 1. was done, this is going fast, again :) +4. Find a place in the dependency tree. When 1. was done, this is going fast, again :) * when it extend an existing package, add it there to the `PKG_DEPENDS_TARGET` * take a look into the path `packages/virtual`, there you should find a virtual packages, that match your new package (misc-packages should the last option) -* now you can build your image - * when ist was build, under build-[...]/ should apear a directory with your package-name and -version. +5. now you can build your image + * after the build, under build-[...]/ should apear a directory with your package-name and -version. ## Example ``` From e859aa061cf07c4db0544a840f289ebb21bdb2db Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Mon, 28 May 2018 10:15:56 +0200 Subject: [PATCH 4/5] documentation: typo --- packages/packages.mk.addon_template | 2 +- packages/packages.mk.template | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/packages.mk.addon_template b/packages/packages.mk.addon_template index 1d52e7fca3..867000ba67 100644 --- a/packages/packages.mk.addon_template +++ b/packages/packages.mk.addon_template @@ -22,7 +22,7 @@ PKG_REV="100" PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" PKG_ARCH="any" PKG_LICENSE="[license of the upstream project]" -PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" +PKG_SITE="[url to the upstream project, e.g. http://example.com/libexample" PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" # PKG_MAINTAINER="John Doe" # Full name or forum/GitHub nickname, if you want to be identified as the addon maintainer PKG_DEPENDS_TARGET="[build system dependencies, e.g. toolchain zlib openssl]" diff --git a/packages/packages.mk.template b/packages/packages.mk.template index 4a65da137c..cb3653ded2 100644 --- a/packages/packages.mk.template +++ b/packages/packages.mk.template @@ -21,7 +21,7 @@ PKG_VERSION="[package version identifier or unique githash]" PKG_SHA256="[sha256 hash of the source file, downloaded from PKG_URL]" PKG_ARCH="any" PKG_LICENSE="[license of the upstream project]" -PKG_SITE="[url to the upstream project, e.g. http://exmaple.com/libexample" +PKG_SITE="[url to the upstream project, e.g. http://example.com/libexample" PKG_URL="[download url, e.g. https://github.com/example/libexample/archive/$PKG_VERSION.tar.gz]" # PKG_MAINTAINER="John Doe" # Full name or forum/GitHub nickname, if you want to be identified as the addon maintainer PKG_DEPENDS_TARGET="[build system dependencies, e.g. toolchain zlib openssl]" From 0f61380d28b382bae306c189ec0cc6a3602b96ec Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Mon, 28 May 2018 10:39:29 +0200 Subject: [PATCH 5/5] documentation: remove unneeded comment --- packages/packages.mk.addon_template | 1 - packages/packages.mk.template | 1 - 2 files changed, 2 deletions(-) diff --git a/packages/packages.mk.addon_template b/packages/packages.mk.addon_template index 867000ba67..f03e3818ed 100644 --- a/packages/packages.mk.addon_template +++ b/packages/packages.mk.addon_template @@ -38,7 +38,6 @@ PKG_ADDON_TYPE="[type]" # PKG_ADDON_PROVIDES="executable" # PKG_ADDON_REQUIRES="some.addon:0.0.0" -# build specific variables #PKG_CMAKE_OPTS_TARGET="-DWITH_EXAMPLE_PATH=/storage/.example # " diff --git a/packages/packages.mk.template b/packages/packages.mk.template index cb3653ded2..05d0f59092 100644 --- a/packages/packages.mk.template +++ b/packages/packages.mk.template @@ -30,7 +30,6 @@ PKG_SHORTDESC="[short description of the package, e.g. libexample: library to ca PKG_LONGDESC="[long description of the package, often taken from the package/project website, e.g. libexample: this project is created to calculate examples for x and y, with maximum efficiency and fewer errors]" # PKG_TOOLCHAIN="auto" -# build specific variables #PKG_CMAKE_OPTS_TARGET="-DWITH_EXAMPLE_PATH=/storage/.example # "