nils/gluon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: user/site: improve feature flag explanation

Browse Source
This commit is contained in:
Matthias Schiffer 2018-07-06 19:32:14 +02:00
parent 655da23520
commit 3540eb96ed
No known key found for this signature in database
GPG Key ID: 16EF3F64CB201D9C
1 changed files with 62 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/user/site.rst
View File

@ -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 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``. same firmware (ath10k-based 5GHz). Defaults to ``11s``.
Features .. _user-site-feature-flags:
^^^^^^^^
Each package starting with "gluon-" can be included as a feature _flag_ by Feature flags
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`) With the addition of more and more features that interact in complex ways, it
and can contain more than one package. Those are defined in the config file has become necessary to split certain packages into multiple parts, so it is
`package/features`. Please read that file for more details. 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.
Site-provided package feeds can define additional feature flags. To use own With the ongoing modularization, e.g. for the purpose of supporting new
package feeds to define your own features, add a file `gluon/features` to your routing protocols, specifying all such split packages in *site.mk* would
site folder. 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: .. _site-config-mode-texts: