docs: update autoupdater documentation

This commit is contained in:
Matthias Schiffer 2020-07-04 12:38:01 +02:00
parent e6d3d1584c
commit b12acc5b03
No known key found for this signature in database
GPG Key ID: 16EF3F64CB201D9C
4 changed files with 24 additions and 13 deletions

View File

@ -7,8 +7,11 @@ Building Images
--------------- ---------------
By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
during development), but it can be enabled by setting the variable GLUON_BRANCH when building during development), but it can be enabled by setting the variable ``GLUON_AUTOUPDATER_ENABLED`` to ``1`` when building.
to override the default branch set in the site configuration. It is also possible to override the default branch during build using the variable ``GLUON_AUTOUPDATER_BRANCH``.
If a default branch is set neither in *site.conf* nor via ``GLUON_AUTOUPDATER_BRANCH``, the default branch is
implementation-defined. Currently, the branch with the first name in alphabetical order is chosen.
A manifest file for the updater can be generated with `make manifest`. A signing script (using A manifest file for the updater can be generated with `make manifest`. A signing script (using
``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the ``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the
@ -32,15 +35,16 @@ Automated nightly builds
A fully automated nightly build could use the following commands: A fully automated nightly build could use the following commands:
:: .. code-block:: sh
git pull git pull
(git -C site pull) # git -C site pull
make update make update
make clean GLUON_TARGET=ar71xx-generic make clean GLUON_TARGET=ar71xx-generic
NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1) NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_RELEASE=$GLUON_RELEASE \
make manifest GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE GLUON_AUTOUPDATER_BRANCH=experimental GLUON_AUTOUPDATER_ENABLED=1
make manifest GLUON_RELEASE=$GLUON_RELEASE GLUON_AUTOUPDATER_BRANCH=experimental
contrib/sign.sh $SECRETKEY output/images/sysupgrade/experimental.manifest contrib/sign.sh $SECRETKEY output/images/sysupgrade/experimental.manifest
rm -rf /where/to/put/this/experimental rm -rf /where/to/put/this/experimental

View File

@ -164,7 +164,8 @@
}, },
autoupdater = { autoupdater = {
-- Default branch. Don't forget to set GLUON_BRANCH when building! -- Default branch (optional), can be overridden by setting GLUON_AUTOUPDATER_BRANCH when building.
-- Set GLUON_AUTOUPDATER_ENABLED to enable the autoupdater by default for newly installed nodes.
branch = 'stable', branch = 'stable',
-- List of branches. You may define multiple branches. -- List of branches. You may define multiple branches.

View File

@ -171,10 +171,12 @@ usually be set on the command line or in ``site.mk``.
Common variables Common variables
................ ................
GLUON_BRANCH GLUON_AUTOUPDATER_BRANCH
Sets the default branch of the autoupdater. If unset, the autoupdater is disabled Overrides the default branch of the autoupdater set in ``site.conf``. For the ``make manifest`` command,
by default. For the ``make manifest`` command, GLUON_BRANCH defines the branch to ``GLUON_AUTOUPDATER_BRANCH`` defines the branch to generate a manifest for.
generate a manifest for.
GLUON_AUTOUPDATER_ENABLED
Set to ``1`` to enable the autoupdater by default for newly installed nodes.
GLUON_DEPRECATED GLUON_DEPRECATED
Controls whether images for deprecated devices should be built. The following Controls whether images for deprecated devices should be built. The following
@ -225,7 +227,7 @@ GLUON_DEBUG
similar tools. Requires a device or target with at least 16 MB of flash space, e.g. `x86-64`. Unset by default. similar tools. Requires a device or target with at least 16 MB of flash space, e.g. `x86-64`. Unset by default.
GLUON_MINIFY GLUON_MINIFY
Setting ``GLUON_MINIFY=0`` will omit the minification of scripts during the build process. By Setting ``GLUON_MINIFY=0`` will omit the minification of scripts during the build process. By
default the flag is set to ``1``. Disabling the flag is handy if human readable scripts on the default the flag is set to ``1``. Disabling the flag is handy if human readable scripts on the
devices are desired for development purposes. Be aware that this will increase the size of the devices are desired for development purposes. Be aware that this will increase the size of the
resulting images and is therefore not suitable for devices with small flash chips. resulting images and is therefore not suitable for devices with small flash chips.

View File

@ -418,12 +418,16 @@ poe_passthrough \: optional
autoupdater \: package autoupdater \: package
Configuration for the autoupdater feature of Gluon. Configuration for the autoupdater feature of Gluon.
Specifying a default branch in *site.conf* is optional. See
:doc:`../features/autoupdater` for information how to change the behaviour
of the autoupdater during image build.
The mirrors are checked in random order until the manifest could be downloaded The mirrors are checked in random order until the manifest could be downloaded
successfully or all mirrors have been tried. successfully or all mirrors have been tried.
:: ::
autoupdater = { autoupdater = {
branch = 'stable', branch = 'stable', -- optional
branches = { branches = {
stable = { stable = {
name = 'stable', name = 'stable',