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⟩.