Table of Contents

Auto updating

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Auto updating

We have an auto-update system which runs 4 times a day.

Currently, most of the packages hosted on github, gitlab or tracked by repology can be updated automatically by just setting TERMUX_PKG_AUTO_UPDATE=true in build.sh.

Use scripts/bin/check-auto-update script to check and enable automatic updates.

❯ ./scripts/bin/check-auto-update -h

Usage: check-auto-update [-h|--help] [-s|--silent] [--enable] PACKAGE_DIR

Check if packages can be auto-updated and optionally enable if so.

NOTE: You should not trust this script if
        - package uses commit hashes for versioning (eg. 'tsu') or
        - TERMUX_PKG_VERSION is defined by us and not upstream, i.e we use some arbitrary version.
          For eg. when only getting source files based on commit hash.

Options:
-h --help Show this help message.
--enable Enable auto-update for package if check was successful. (writes TERMUX_PKG_AUTO_UPDATE=true to build.sh)
-s --silent Do not print anything to stdout.

Example: check-auto-update x11-packages/xorg-server

In case script returns false, you may want to write your own update steps. See here for more details.

Control fields

S.No.	Variable	Required	Description
1	`TERMUX_PKG_AUTO_UPDATE`	yes	Whether to enable automatic updates for this package. Currently packages hosted on GitHub, Gitlab or tracked by repology can be auto updated. For using your own method see here. After writing build.sh you can check if package can be auto-updated using script at scripts/bin/check-auto-update.
2	`TERMUX_PKG_UPDATE_VERSION_REGEXP`	no	Regex to extract version from the new computed version. • `grep -P` is set, so you can use perl regex. Use case: any api may return new version as `Release_8.9.0`, but we want only `8.9.0`. So, we can extract it using `\d+\.\d+\.\d+`.
3	`TERMUX_PKG_UPDATE_METHOD`	no	Which method to use for auto-update. Can be `github`, `gitlab` or `repology`. By default it is decided on the basis of `TERMUX_PKG_SRCURL`
4	`TERMUX_PKG_UPDATE_TAG_TYPE`	no	Whether to get `latest-release-tag` or `newest-tag` (sorted by commit date) if using `github` or `gitlab` method for auto-update. By default if `TERMUX_PKG_SRCURL` ends in `.git` then `newest-tag` is fetched otherwise `latest-release-tag`.
5	`TERMUX_GITLAB_API_HOST`	no	Which host to use for gitlab api. Default `gitlab.com`

Auto update steps refrence

Following functions are used by update system.

Order specifies function sequence. 0 order specifies utility functions.

Suborder specifies a function triggered by the main function. Functions with different suborders are not executed simultaneously.

Order	Function Name	Overridable	Description	Parameters
0.1	`termux_error_exit`	No	Function to write error message to `stderr` and exit.	Any number of string arguments. You can use heredoc for long messages.
0.2	`termux_github_api_get_tag`	No	Query GitHub API for: • `latest-release-tag`: useful for projects using github's release mechanism. • `newest-tag`(sorted by commit date): useful for projects having tags but no releases.	• PKG_SRCURL - Source url of package. • TAG_TYPE - Optional. Type of tag to query. It is one of the queries mentioned in description. If not given it is decided on the basis of PKG_SRCURL. For urls ending in `.git` `newest-tag` is queried, otherwise `latest-release-tag`.
0.3	`termux_gitlab_api_get_tag`	No	same as above, but for gitlab	same as above, except for optional 3rd argument: • API_HOST - Host for gitlab api. Default `gitlab.com`.
0.4	`termux_repology_api_get_latest_version`	No	Query repology api for latest version.	• PKG_NAME - Name of the package to query for.
1	`termux_pkg_auto_update`	Yes	By default, decide which method (gitlab, github or repology) to use for update, but can be overrided to use custom method (See here).	None
2.1	`termux_github_auto_update`	No	Default update method for packages hosted on github.com. It decides which type of tag to fetch based on `TERMUX_PKG_SRCURL`.	None
2.2	`termux_gitlab_auto_update`	No	Default update method for packages hosted on gitlab.com (or host specified by `TERMUX_GITLAB_API_HOST`). It decides which type of tag to fetch based on `TERMUX_PKG_SRCURL`.	None
3	`termux_pkg_upgrade_version`	No	Write the latest version and updated checksum, check whether updated package builds properly and then push changes to repo.	• LATEST_VERSION - version to write to build.sh. • --skip-version-check - Optional flag. Do not check whether given LATEST_VERSION is greater than current TERMUX_PKG_VERSION.
3.1	`termux_pkg_is_update_needed`	No	Check whether LATEST_VERSION is greater than TERMUX_PKG_VERSION or not. Called if `--skip-version-check` was not passed to `termux_pkg_upgrade_version`. NOTE: You should not call it manually otherwise if `TERMUX_PKG_UPDATE_VERSION_REGEXP` is used, it won't compare versions extracted from it. Version is extracted by `termux_pkg_upgrade_version`.	Not for public use.

Overriding

If default steps doesn't work, you may override termux_pkg_auto_update() function to write your own steps.

For example see neovim-nightly's build.sh.

All functions marked as utility in function refrence, are available within termux_pkg_auto_update() or functions spawned by it.
After extracting latest version, call termux_pkg_upgrade_version with it to write changes to build.sh.

Warning

Bash fail-fast (i.e set -euo pipefail) is set, so consider it during error handling.

Read more about bash fail-fast here.

For example:

Following code won't work as expected:

local curl_response
curl_response=$(curl --silent "https://example.com" --write-out '|%{http_code}')

# XXXX: following code won't execute if curl fails as script will exit immediately there.

local http_code="${curl_response##*|}"
if [[ "${http_code}" != "200" ]]; then
	echo "Error: failed to get latest version."
	exit 1
fi

Instead use something like:

local curl_response
curl_response=$(
	curl --silent "https://example.com" --write-out '|%{http_code}'
) || {
        # This will run as expected.
	local http_code="${curl_response##*|}"
	if [[ "${http_code}" != "200" ]]; then
		echo "Error: failed to get latest version"
		exit 1
	fi
}