NAME

bs-update — Update packages in a Build Service from upstream

sources.

SYNOPSIS

bs-update -h bs-update [-A BSAPI] [-B BUILDARGS]... [-C] [-P PROJECT] [-b] [-d URL] [-m COMMITMSG] [-n] [-p PACKAGE] [-s SPECFILE]... [-t TARBALL] TAG [VERSION]

DESCRIPTION

bs-update makes it easier to keep packages in a Build Service up-to-date with respect to their upstream sources.

Given a Build Service API URL, project and package names, a tarball URL, and a version number, bs-update will

1. figure out the target version from operands and the optional bsu_version_hook,
2. check out the package from the Build Service into a temporary directory,
3. fetch the tarball from the URL,
4. update the tarball source with the downloaded tarball, after possible modification by the optional bsu_tarball_hook,
5. update package descriptions (specfile, PKGBUILD, etc) from their templates extracted from the tarball or provided by the optional bsu_specfile_hook,
6. (optionally) build the package locally,
7. (optionally) commit the changes.

bs-update aborts on failure in any step.

Options

All options beside -h have their configuration variable counterparts. See the FILES section for more information.

-h Display a usage description.

-A BSAPI

Use Build Service at BSAPI (URL or alias). Passed to osc(1).

-B BUILDARGS

Use BUILDARGS (after field splitting) as arguments to osc build (see -b). May be given more than once, each instance yields a separate osc build.

-C Skip the osc commit step.

-P PROJECT

Update Build Service package of PROJECT.

-b Run osc build before osc commit. If the build fails,

bs-update aborts. See $bsu_osc_build.

-d URL

Retrieve the source tarball from URL. If URL is ".", bs-update uses git-archive(1) or hg-archive(1) in $PWD as appropriate. Otherwise, bs-update uses wget(1).

-m COMMITMSG

Use COMMITMSG for the commit in Build Service. Defaults to "Update to version VERSION".

-n Report values derived from configuration files and command line

arguments, then exit.

-p PACKAGE

Update Build Service PACKAGE.

-s SPECFILE

Use SPECFILE.in from TARBALL, commit SPECFILE into the Build Service. All occurrences of __VERSION__ in SPECFILE are replaced with VERSION. SPECFILE can be a real .spec file (RPM) or a PKGBUILD file (ArchLinux). May be given more than once, all files are processed.

-t TARBALL

Use TARBALL for the name of the downloaded file.

Operands

TAG

Update the package from TAG. Substituted for $bsu_tag in values derived from command line options and configuration files.

VERSION

Update the package to VERSION. If VERSION is not given, it is generated using bsu_version_hook() if it exists, otherwise from TAG by stripping the initial "v" if any. Substituted for $bsu_version in values derived from command line options and configuration files.

Hooks

bs-update allows tailoring the update process through shell functions, see the FILES section for more information.

ENVIRONMENT

bs-update itself does not use any environment variables. It is, however, implemented in terms of third-party commands which do use them. This means bs-update may be influenced by environment variables used by git(1), hg(1), osc(1), tar(1), wget(1), zsh(1), possibly others.

FILES

bs-update recognizes two optional configuration files, .bs-update-hooks and .bs-update. They are read, in order, from the current directory before command line arguments are processed. Either file may define any of hooks and/or configuration variables, last definition wins.

Each configuration variable has a corresponding command line option. Command line options and arguments take precedence over configuration files. Resulting values are subject to shell parameter expansion.

Syntactically, the configuration files are limited shell scripts recognizing two kinds of statements: parameter assignments, and function definitions.

Shell Functions (Hooks)

bsu_specfile_hook()

If this function exists, it is responsible for providing a $s.in file for each $s in $bsu_specfiles. bs-update will invoke it with arguments consisting of $bsu_version, $bsu_tag, $bsu_tarball and $bsu_specfiles.

bsu_tarball_hook()

The tarball may need finalization before it is checked into the Build Service, eg. autoconf, git submodules or npm. If this function exists it is executed in the root of the checked out package, with the tarball name in the first argument.

bsu_version_hook()

If the VERSION argument is not given and this function exists it is executed with the TAG argument, and its output is used as the final version string.

Variables

bsu_bs_apiurl (-A) bsu_bs_commit (-C) bsu_bs_commitmsg (-m) bsu_bs_package (-p) bsu_bs_project (-P) bsu_dloadurl (-d) bsu_dryrun (-n) bsu_specfiles (-s) bsu_tarball (-t) bsu_test_build (-b) bsu_osc_build (-B) Array of strings where each item is used (after field splitting) as arguments to osc build (see -b).

EXAMPLES

Interactive Use by Upstream Maintainer

This is a real-world example showing common .bs-update setup and the use of bs-update to test changes in the package and finally produce a new package version. It assumes the user maintains both the upstream software and its package in the Build Service.

We need a working copy to hack on:

git clone git@github.com:roman-neuhauser/bs-update.git cd bs-update

Since we're going to use bs-update repeatedly, it makes sense to employ a configuration file, .bs-update. Everything can still be overridden using options on the command line:

cat > .bs-update usr=roman-neuhauser pkg=bs-update bsu_bs_apiurl=https://api.opensuse.org bsu_bs_package='$pkg' bsu_bs_project='home:$usr' bsu_dloadurl='https://github.com/$usr/$pkg/tarball/$bsu_tag' bsu_osc_build=( 'ArchLinux x86_64 PKGBUILD' 'SLE_12 x86_64 $pkg.spec' 'openSUSE_Tumbleweed x86_64 $pkg.spec' ) ^D

Commit some changes:

vim bs-update.in make check git commit bs-update.in

Build the package locally, using the currently checked out revision. Does not commit into the Build Service:

bs-update -Cbd . HEAD

If it was ok we can tag it and publish the tag:

git tag -a v42.69 git push origin master v42.69

Commit the new release into the Build Service:

bs-update v42.69

Snapshot-generating Cronjob

This example demonstrates using bsu_tarball_hook to generate snapshot tarballs of a Git branch. A new version of the package is created, based on a tarball of the upstream master branch.

mkdir /snapshots

cat > /snapshots/.bs-update-hooks <<'EOF' bsu_tarball_hook() ( set -e local tarball=./${1?} local dir=${tarball%.tar.gz} mkdir $dir tar -xzf $tarball --strip-components=1 -C $dir tar -czf $tarball -- ${dir#./} rm -rf $dir ) EOF

cat > /etc/cron.weekly/mk-snapshot <<'EOF' #!/bin/sh set -eu ts=$(date +%Y%m%d%H%M%S) cd /snapshots bs-update \ -P home:roman-neuhauser \ -p bs-update-snapshot \ -d https://github.com/roman-neuhauser/bs-update/tarball/master \ -t bs-update-$ts.tar.gz \ master $ts EOF

chmod a+x /etc/cron.weekly/mk-snapshot

DIAGNOSTICS

bs-update exits with 0 on success, and with >0 otherwise.

SEE ALSO

git(1), the openSUSE Build Service ⟨https://build.opensuse.org/⟩, and its wiki ⟨http://en.opensuse.org/Portal:Build_Service⟩.

AUTHORS

bs-update and this manual page are written by ⟨neuhauser@sigpipe.cz⟩.

See ⟨https://github.com/roman-neuhauser/bs-update/⟩.

BUGS

No doubt plentiful. Please report them at ⟨https://github.com/roman-neuhauser/bs-update/issues⟩.