From f177baf48d4ebbcc87cf604f4ca7bffb8fb73701 Mon Sep 17 00:00:00 2001 From: "Sascha Kuehndel (InuSasha)" Date: Sat, 21 Apr 2018 11:13:08 +0200 Subject: [PATCH] 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 +} +``` +