From b2436f674bc2fd9676beb5d932a8e559623a60cb Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Sat, 23 Jun 2018 19:44:43 +0200
Subject: [PATCH] docs: add new doc page about package development
Explain the magic of gluon.mk. The feature flag documention is moved into
this new page.
---
docs/dev/feature-flags.rst | 45 ---------------
docs/dev/packages.rst | 114 +++++++++++++++++++++++++++++++++++++
docs/index.rst | 2 +-
3 files changed, 115 insertions(+), 46 deletions(-)
delete mode 100644 docs/dev/feature-flags.rst
create mode 100644 docs/dev/packages.rst
diff --git a/docs/dev/feature-flags.rst b/docs/dev/feature-flags.rst
deleted file mode 100644
index 25c443175..000000000
--- a/docs/dev/feature-flags.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-Feature flags
-=============
-
-Feature flags provide a convenient way to define package selections without
-making it necessary to list each package explicitly.
-
-The main feature flag definition file is ``package/features``, but each package
-feed can provide additional defintions in a file called ``features`` at the root
-of the feed repository.
-
-Each flag *$flag* without any explicit definition will simply include the package
-with the name *gluon-$flag* by default. The feature definition file can modify
-the package selection in two ways:
-
-* The *nodefault* function suppresses default of including the *gluon-$flag*
- package
-* The *packages* function adds a list of packages (or removes, when package
- names are prepended with minus signs) when a given logical expression
- is satisfied
-
-Example::
-
- nodefault 'web-wizard'
-
- packages 'web-wizard' \
- 'gluon-config-mode-hostname' \
- 'gluon-config-mode-geo-location' \
- 'gluon-config-mode-contact-info'
-
- packages 'web-wizard & (mesh-vpn-fastd | mesh-vpn-tunneldigger)' \
- 'gluon-config-mode-mesh-vpn'
-
-This will
-
-* Disable the inclusion of a (non-existent) package called *gluon-web-wizard*
-* Enable three config mode packages when the *web-wizard* feature is enabled
-* Enable *gluon-config-mode-mesh-vpn* when both *web-wizard* and one
- of *mesh-vpn-fastd* and *mesh-vpn-tunneldigger* are enabled
-
-Supported syntax elements of logical expressions are:
-
-* \& (and)
-* \| (or)
-* \! (not)
-* parentheses
diff --git a/docs/dev/packages.rst b/docs/dev/packages.rst
new file mode 100644
index 000000000..f89e83d43
--- /dev/null
+++ b/docs/dev/packages.rst
@@ -0,0 +1,114 @@
+Package development
+###################
+
+Gluon packages are OpenWrt packages and follow the same rules described at https://openwrt.org/docs/guide-developer/packages.
+
+
+Gluon package makefiles
+=======================
+
+As many packages share the same or a similar structure, Gluon provides a ``package/gluon.mk`` that
+can be included for common definitions. This file replaces OpenWrt's ``$(INCLUDE_DIR)/package.mk``;
+it is usually included as ``include ../gluon.mk`` from Gluon core packages, or as
+``include $(TOPDIR)../package/gluon.mk`` from feeds.
+
+Provided macros
+***************
+
+* *GluonBuildI18N* (arguments: *<source directory>*)
+
+ Converts the *.po* files for all enabled languages from the given source directory to
+ the binary *.lmo* format and stores them in ``$(PKG_BUILD_DIR)/i18n``.
+
+* *GluonInstallI18N*
+
+ Install *.lmo* files from ``$(PKG_BUILD_DIR)/i18n`` to ``/lib/gluon/web/i18n`` in the
+ package install directory.
+
+* *GluonSrcDiet* (arguments: *<source directory>*, *<destination directory>*)
+
+ Copies a directory tree, processing all files in it using *LuaSrcDiet*. The directory
+ tree should only contain Lua files.
+
+* *GluonCheckSite* (arguments: *<source file>*)
+
+ Intended to be used in a package postinst script. It will use the passed Lua
+ snippet to verify package-specific site configuration.
+
+* *BuildPackageGluon* (replaces *BuildPackage*)
+
+ Extends the *Package/<name>* definition with common defaults, sets the package
+ install script to the common *Gluon/Build/Install*, and automatically creates
+ a postinst script using *GluonCheckSite* if a ``check_site.lua`` is found in the
+ package directory.
+
+Default build steps
+*******************
+
+These defaults greatly reduce the boilerplate in each package, but they can also
+be confusing because of the many implicit behaviors depending on files in the
+package directory. If any part of *Gluon/Build/Compile* or *Gluon/Build/Install*
+does not work as intended for a package, the compile and install steps can
+always be replaced or extended.
+
+*Build/Compile* is set to *Gluon/Build/Compile* by default, which will
+
+* run OpenWrt standard default commands (*Build/Compile/Default*) if a ``src/Makefile``
+ or ``src/CMakeLists.txt`` is found
+* run *GluonSrcDiet* on all files in the ``luasrc`` directory
+* run *GluonBuildI18N* if a ``i18n`` directory is found
+
+*Package/<name>* defaults to *Gluon/Build/Install* for packages defined using
+*BuildPackageGluon*, which will
+
+* copy all files from ``$(PKG_INSTALL_DIR)`` into the package if ``$(PKG_INSTALL)`` is 1
+* copy all files from ``files`` into the package
+* copy all Lua files built from ``luasrc`` into the package
+* installs ``$(PKG_BUILD_DIR)/respondd.so`` to ``/usr/lib/respondd/$(PKG_NAME).so`` if ``src/respondd.c`` exists
+* installs compiled i18n *.lmo* files
+
+Feature flags
+=============
+
+Feature flags provide a convenient way to define package selections without
+making it necessary to list each package explicitly.
+
+The main feature flag definition file is ``package/features``, but each package
+feed can provide additional defintions in a file called ``features`` at the root
+of the feed repository.
+
+Each flag *$flag* without any explicit definition will simply include the package
+with the name *gluon-$flag* by default. The feature definition file can modify
+the package selection in two ways:
+
+* The *nodefault* function suppresses default of including the *gluon-$flag*
+ package
+* The *packages* function adds a list of packages (or removes, when package
+ names are prepended with minus signs) when a given logical expression
+ is satisfied
+
+Example::
+
+ nodefault 'web-wizard'
+
+ packages 'web-wizard' \
+ 'gluon-config-mode-hostname' \
+ 'gluon-config-mode-geo-location' \
+ 'gluon-config-mode-contact-info'
+
+ packages 'web-wizard & (mesh-vpn-fastd | mesh-vpn-tunneldigger)' \
+ 'gluon-config-mode-mesh-vpn'
+
+This will
+
+* disable the inclusion of a (non-existent) package called *gluon-web-wizard*
+* enable three config mode packages when the *web-wizard* feature is enabled
+* enable *gluon-config-mode-mesh-vpn* when both *web-wizard* and one
+ of *mesh-vpn-fastd* and *mesh-vpn-tunneldigger* are enabled
+
+Supported syntax elements of logical expressions are:
+
+* \& (and)
+* \| (or)
+* \! (not)
+* parentheses
diff --git a/docs/index.rst b/docs/index.rst
index b71fa3324..d5bd928dc 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,8 +35,8 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
:maxdepth: 2
dev/basics
- dev/feature-flags
dev/hardware
+ dev/packages
dev/upgrade
dev/wan
dev/mac_addresses
--
GitLab