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 → docs/dev/packages.rst

+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
 =============
 
@@ -32,9 +101,9 @@ Example::
 
 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
+* 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:

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