API.md

Function index

Generated by make docs from the comment above each function -- do not edit this file by hand.

This is an index. Arguments, return values and side effects are documented in the source comments, which each row links to.

Installer functions are not listed here: they are internal to a generated install script and are covered by INSTALLERS.md.

function	summary
date_iso8601	returns a ISO 8601 UTC formatted date
echoerr	write message to stderr
git_clone_or_update	clone a repo, or update it if it exists locally
github_api	make an API request to api.github.com, with auth token if set
github_release	validates tag exists or returns latest tagged release
hash_md5	produce md5 hash in hex digits for a file or stdin
hash_sha256	compute SHA256 of $1 or stdin
hash_sha256_verify	validates a binary against a checksum.txt file
hash_sha512	compute SHA512 of $1 or stdin
hash_sha512_verify	validates a binary against a checksum.txt file
http_copy	copies contents of a URL to stdout, or fails
http_download	download a URL to a local file, using whichever downloader exists
http_download_curl	download a URL to a local file using curl
http_download_fetch	download a URL to a local file using FreeBSD fetch(1)
http_download_ftp	download a URL to a local file using BSD ftp(1)
http_download_node	download a URL to a local file using node
http_download_python	download a URL to a local file using python3
http_download_wget	download a URL to a local file using wget
http_last_modified	returns the last modified timestamp from a HTTP URL
install_exe	copy a file into place and make it executable
is_command	returns true if command exists
log_crit	log at critical priority (2), for platform problems
log_debug	log at debug priority (7)
log_err	log at error priority (3)
log_info	log at info priority (6)
log_prefix	function to prefix each log output
log_priority	if no args, return the priority
log_set_priority	set the log priority
log_tag	map a syslog priority number to its name
mktmpdir	create a fresh, private temporary directory and echo its path
uname_arch	convert uname -m into shlib's canonical architecture name
uname_arch_check	self-check that uname_arch produced a recognized architecture name
uname_os	convert uname -s into shlib's canonical OS name
uname_os_check	self-check that uname_os produced a recognized OS name
untar	unpack $1 into the current directory

35 functions.

Platforms

uname_os and uname_arch translate what uname reports into shlib's canonical platform names -- the spellings release artifacts are almost always named after. That set is the one Go uses for GOOS and GOARCH, which is where the convention came from and why it is worth staying compatible with, but it is shlib's set and it deviates where reality does: see How a name gets added.

The lists below are extracted from uname_os_check.sh and uname_arch_check.sh.

Recognised operating systems

aix android darwin dragonfly freebsd illumos ios js linux midnightbsd nacl netbsd openbsd plan9 solaris wasip1 windows 

Most values come straight from a lowercased uname -s. These do not:

uname -s reports	mapped to	why
MSYS_NT-*, MINGW*, CYGWIN_NT-*, Windows_NT	windows	the Unix-ish environments on Windows each report their own name
SunOS with uname -o = illumos	illumos	illumos and Solaris both still report the ancient SunOS
SunOS otherwise	solaris	Oracle Solaris; its uname has no -o, so the check is silent about it

sunos itself is deliberately never returned -- no project names an artifact for it.

Recognised architectures

386 amd64 amd64p32 arm64 armv5 armv6 armv7 loong64 mips mips64 mips64le mipsle ppc64 ppc64le riscv64 s390x 

Mapped from uname -m:

uname -m reports	mapped to
x86_64	amd64
i86pc	amd64
x86	386
i686	386
i386	386
aarch64	arm64
armv5*	armv5
armv6*	armv6
armv7*	armv7
loongarch64	loong64

How a name gets added

A name is recognised when both of these hold:

1. some real system's uname maps to it, and
2. it is the spelling projects use when naming release artifacts for that platform.

Nothing is admitted because Go added it, and nothing is dropped because Go removed it. That rule is why the set is not identical to go tool dist list:

name	how it differs from Go
midnightbsd	never a GOOS; MidnightBSD reports it and names artifacts for it (PR #33)
armv5 armv6 armv7	Go spells all three arm and puts the version in GOARM; artifacts do not
nacl amd64p32	dropped from Go in 1.14; kept so existing callers do not start failing

sunos is the reverse case: it satisfies (1) but not (2), so uname_os resolves it to solaris or illumos and never returns it.

Projects whose assets use the raw kernel spellings -- x86_64 rather than amd64, aarch64 rather than arm64 -- map back with the installer's adjust_os / adjust_arch hooks, documented in INSTALLERS.md.