nixpkgs/pkgs/build-support/upstream-updater/update-walker.txt

update-walker is an imperative semiautomated update helper.

It runs the X.upstream file to find the freshest version of the package in
the specified upstream source and updates the corresponding X.nix file.



The simplest available commands:

url: set the upstream source list URL equal to $1; the default is
meta.downloadPage with meta.homepage fallback

dl_url_re: set the regular expression used to select download links to $1; the
default is meta.downloadURLRegexp or '[.]tar[.]([^./])+\$' if it is not set

target: specify target expression; default is to replace .upstream extension
with .nix extension

name: specify the derivation name; default is the basename of the dirname
of the .upstream file

attribute_name: specify the attribute name to evaluate for getting the current
version from meta.version; default is to use the derivation name

minimize_overwrite: set config options that mean that only version= and
sha256= have to be replaced; the default is to regenerate a full upstream
description block with url, name, version, hash etc.



A lot of packages can be updated in a pseudo-declarative style using only
the commands from the previous paragraph.

Some packages do not need any non-default settings, in these case just setting
meta.updateWalker to true is enough, you can run update-walker directly on the
.nix file afterwards. In this case minimize_overwrite it implied unless
meta.fullRegenerate is set.



The packages that require more fine-grained control than the described options
allow, you need to take into account the default control flow of the tool.

First, the definitions from update-walker script and additional definitions
from update-walker-service-specific.sh are loaded. Then the config is executed
as a shell script. Some of the commands it can use do remember whether they
have been used. Afterwards the following steps happen: 

attribute_name is set to name unless it has been already set

meta.version is read from the NixPkgs package called attribute_name

download URL regexp is set to default unless it has been already set in the
updater script

the download page URL gets set to default value unless it has been set
previously

if the action of getting the download page and choosing the freshest link by
version has not yet been taken, it happens

if the version has not yet been extracted from the URL, it gets extracted

target nix expression to update gets set to the default value unless it has
been set explicitly

if the URL version is fresher than the packaged version, the new file gets
downloaded and its hash is calculated

do_overwrite function is called; the default calculates a big upstream data
block and puts it after the '# Generated upstream information' marker (the
marker can be changed by the command marker)



If the update needs some special logic, it is put into the updater script and
the corresponding steps are skipped because the needed action has already been
performed. 

For example: 

minimize_overwrite is exactly the same as

do_overwrite() { do_overwrite_just_version; }

redefinition. You can do a more complex do_overwrite redifinition, if needed.
It can probably use ensure_hash to download the source and calculate the hash
and set_var_value.

set_var_value alters the $3-th instance of assigning the $1 name in the
expression to the value $2. $3 defaults to 1. It can modify $4 instead of the
current target, it can put the value without quotes if $5 is 1.



Typical steps include:

ensure_choice: download current URL and find the freshest version link on the
page, it is now the new URL

ensure_hash: download current URL and calculate the source package hash

ensure_version: extract version from the URL

SF_redirect: replace the current URL with a SourceForge.net mirror:// URL

SF_version_dir: assume SourceForge.net layout and choose the freshest
version-named subdirectory in the file catalog; you can optionally specify $1
as a directory name regexp (digits and periods will be required after it)

SF_version_tarball: assume SourceForge.net layout and choose the freshest
tarball download link

version: apply replacement of $1 with $2 (extended regexp format) to extract
the version from URL

version_link: choose the freshest versioned link, $1 is the regexp of
acceptable links