nils/gluon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
5c325cc1c9
gluon/docs/dev/packages.rst

133 lines
5.2 KiB
ReStructuredText
Raw Normal View History

docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
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
doc/dev/package: Fix path to gluon.mk (#1774) $(TOPDIR) does not contain a trailing slash. Thus the 'gluon.mk'-include must include the trailing slash. (Just like the link to $(INCLUDE_DIR)/package.mk does.) Signed-off-by: Chris Fiege <chris@tinyhost.de>
2019-06-29 21:41:07 +00:00
``include $(TOPDIR)/../package/gluon.mk`` from feeds.
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
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
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
making it necessary to list each package explicitly. The list of features to
enable for a Gluon build is set by the *GLUON_FEATURES* variable in *site.mk*.
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
The main feature flag definition file is ``package/features``, but each package
docs: fix typos and common misspellings (#1668)
2019-03-10 19:15:25 +00:00
feed can provide additional definitions in a file called ``features`` at the root
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
of the feed repository.
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
Each flag *$flag* will include the package the name *gluon-$flag* by default.
The feature definition file can modify the package selection by adding or removing
packages when certain combinations of flags are set.
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
Feature definitions use Lua syntax. Two basic functions are defined:
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
* *feature(name, pkgs)*: Defines a new feature. *feature()* expects a feature
(flag) name and a list of packages to add or remove when the feature is
enabled.
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
* Defining a feature using *feature* replaces the default definition of
just including *gluon-$flag*.
* A package is removed when the package name is prefixed with a ``-`` (after
the opening quotation mark).
* *when(expr, pkgs)*: Adds or removes packages when a given logical expression
of feature flags is satisfied.
* *expr* is a logical expression composed of feature flag names (each prefixed
with an underscore before the opening quotation mark), logical operators
(*and*, *or*, *not*) and parentheses.
* Referencing a feature flag in *expr* has no effect on the default handling
of the flag. When no *feature()* entry for a flag exists, it will still
add *gluon-$flag* by default.
* *pkgs* is handled as for *feature()*.
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
Example::
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
feature('web-wizard', {
'gluon-config-mode-hostname',
'gluon-config-mode-geo-location',
'gluon-config-mode-contact-info',
'gluon-config-mode-outdoor',
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
})
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
when(_'web-wizard' and (_'mesh-vpn-fastd' or _'mesh-vpn-tunneldigger'), {
'gluon-config-mode-mesh-vpn',
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
})
features: fix handling of logical expressions The rewrite of the feature handling introduced multiple major bugs. One of them was caused by the way Lua's logical operators work: An expression of the form _'autoupdater' and _'web-advanced' would return 'web-advanced' rather than the boolean true when _ returned both strings unchanged (because the features are enabled). As entries with more than a single feature name in their expressions did not set no_default, Gluon would then attempt to add gluon-web-advanced to the package selection, as web-advanced is a "pure" feature. To fix this, and get rid of the annoying nodefault, separate handling of "pure" feature and handling of logical expressions into two separate functions, called feature() and when(). To simplify the feature definitions, the package list is now passed directly to these functions rather than in a table with a single field 'packages'. Fixes: ee5ec5afe5ea ("build: rewrite features.sh in Lua")
2020-08-28 20:04:06 +00:00
feature('no-radvd', {
'-gluon-radvd',
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
})
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
This will
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
* disable the inclusion of the (non-existent) packages *gluon-web-wizard* and *gluon-no-radvd* when their
corresponding feature flags appear in *GLUON_FEATURES*
* enable four additional config mode packages when the *web-wizard* feature is enabled
docs: add new doc page about package development Explain the magic of gluon.mk. The feature flag documention is moved into this new page.
2018-06-23 17:44:43 +00:00
* enable *gluon-config-mode-mesh-vpn* when both *web-wizard* and one
of *mesh-vpn-fastd* and *mesh-vpn-tunneldigger* are enabled
build: rewrite features.sh in Lua The `features` file is converted to a Lua-based DSL. A helper function `_` is used in the DSL; this will return the original string for enabled features, and nil for disabled features. This allows to use boolean operations on features without making the code too verbose. Besides having more readable and robust code, this also fixes the bug that all files `packages/*/features` were evaluated instead of only using the feature definitions of currently active feeds.
2020-05-31 11:04:10 +00:00
* disable the *gluon-radvd* package when *gluon-no-radvd* is enabled
Reference in New Issue Copy Permalink