From 3540eb96ed30164c3dc1fd437d1b6c40a0861ec4 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer <mschiffer@universe-factory.net> Date: Fri, 6 Jul 2018 19:32:14 +0200 Subject: [PATCH] docs: user/site: improve feature flag explanation --- docs/user/site.rst | 81 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 15 deletions(-) diff --git a/docs/user/site.rst b/docs/user/site.rst index c098b193c..142ec919b 100644 --- a/docs/user/site.rst +++ b/docs/user/site.rst @@ -475,21 +475,72 @@ GLUON_WLAN_MESH support both meshing modes, either at all (e.g. ralink and mediatek don't support AP+IBSS) or in the same firmware (ath10k-based 5GHz). Defaults to ``11s``. -Features -^^^^^^^^ - -Each package starting with "gluon-" can be included as a feature _flag_ by -omitting the prefix "gluon-"; for example, the flag *mesh-batman-adv-15* will -include only the package *gluon-mesh-batman-adv-15*. - -Some flags are specially treated (for example `web-wizard` and `web-advanced`) -and can contain more than one package. Those are defined in the config file -`package/features`. Please read that file for more details. - -Site-provided package feeds can define additional feature flags. To use own -package feeds to define your own features, add a file `gluon/features` to your -site folder. - +.. _user-site-feature-flags: + +Feature flags +^^^^^^^^^^^^^ + +With the addition of more and more features that interact in complex ways, it +has become necessary to split certain packages into multiple parts, so it is +possible to install just what is needed for a specific usecase. One example +is the package *gluon-status-page-mesh-batman-adv*: There are batman-adv-specific +status page components; they should only be installed when both batman-adv and +the status page are enabled, making the addition of a specific package for this +combination necessary. + +With the ongoing modularization, e.g. for the purpose of supporting new +routing protocols, specifying all such split packages in *site.mk* would +soon become very cumbersome: In the future, further components like +respondd support or languages might be split off as separate packages, +leading to entangled package names like *gluon-mesh-vpn-fastd-respondd* or +*gluon-status-page-mesh-batman-adv-i18n-de*. + +For this reason, we have introduced *feature flags*, which can be specified +in the *GLUON_FEATURES* variable. These flags allow to specify a set of features +on a higher level than individual package names. + +Most Gluon packages can simply be specified as feature flags by removing the ``gluon-`` +prefix: The feature flag corresponding to the package *gluon-mesh-batman-adv-15* is +*mesh-batman-adv-15*. + +The file ``package/features`` in the Gluon repository (or +``features`` in site feeds) can specify additional rules for deriving package lists +from feature flags, e.g. specifying both *status-page* and either *mesh-batman-adv-14* +or *mesh-batman-adv-15* will automatically select the additional package +*gluon-status-page-mesh-batman-adv*. In the future, selecting the flags +*mesh-vpn-fastd* and *respondd* might automatically enable the additional +package *gluon-mesh-vpn-fastd-respondd*, and enabling *status-page* and +*mesh-batman-adv-15* (or *-14*) with ``de`` in *GLUON_LANGS* could +add the package *gluon-status-page-mesh-batman-adv-i18n-de*. + +In short, it is not necessary anymore to list all the individual packages that are +relevant for a firmware; instead, the package list is derived from a list of feature +flags using a flexible ruleset defined in the Gluon repo or site package feeds. +To some extent, it will even allow us to further modularize existing Gluon packages, +without necessitating changes to existing site configurations. + +It is still possible to override such automatic rules using *GLUON_SITE_PACKAGES* +(e.g., ``-gluon-status-page-mesh-batman-adv`` to remove the automatically added +package *gluon-status-page-mesh-batman-adv*). + +For convenience, there are two feature flags that do not directly correspond to a Gluon +package: + +* web-wizard + + Includes the *gluon-config-mode-...* base packages (hostname, geolocation and contact info), + as well as the *gluon-config-mode-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*), + and *gluon-config-mode-mesh-vpn* (when *mesh-vpn-fastd* or *mesh-vpn-tunneldigger* are in + *GLUON_FEATURES*) + +* web-advanced + + Includes the *gluon-web-...* base packages (admin, network, WiFi config), + as well as the *gluon-web-autoupdater* (when *autoupdater* is in *GLUON_FEATURES*) + +We recommend to use *GLUON_SITE_PACKAGES* for non-Gluon OpenWrt packages only and +completely rely on *GLUON_FEATURES* for Gluon packages, as it is shown in the +example *site.mk*. .. _site-config-mode-texts: -- GitLab