bs-update.1

.\" This document is in the public domain.
.\" vim: fdm=marker
.
.\" FRONT MATTER {{{
.Dd Jul 16, 2012
.Os
.Dt BS-UPDATE 1
.
.Sh NAME
.Nm bs-update
.Nd Update packages in a Build Service from upstream sources.
.\" FRONT MATTER }}}
.
.\" SYNOPSIS {{{
.Sh SYNOPSIS
.Nm
.Fl h
.Nm
.Op Fl A Ar BSAPI
.Oo Fl B Ar BUILDARGS Oc Ns ...
.Op Fl C
.Op Fl P Ar PROJECT
.Op Fl b
.Op Fl d Ar URL
.Op Fl m Ar COMMITMSG
.Op Fl n
.Op Fl p Ar PACKAGE
.Oo Fl s Ar SPECFILE Oc Ns ...
.Op Fl t Ar TARBALL
.Ar TAG
.Op Ar VERSION
.\" SYNOPSIS }}}
.
.\" DESCRIPTION {{{
.Sh DESCRIPTION
.Nm
makes it easier to keep packages in a Build Service
up-to-date with respect to their upstream sources.
.
.Pp
.
Given a Build Service API URL, project and package names, a tarball
URL, and a version number,
.Nm
will
.
.Pp
.
.Bl -enum -compact
.It
figure out the target version from operands and the optional
.Fn bsu_version_hook ,
.It
check out the package from the Build Service into a temporary directory,
.It
fetch the tarball from the URL,
.It
update the tarball source with the downloaded tarball,
after possible modification by the optional
.Fn bsu_tarball_hook ,
.It
update package descriptions (specfile, PKGBUILD, etc) from their
templates extracted from the tarball or provided by the optional
.Fn bsu_specfile_hook ,
.It
.Pq optionally
build the package locally,
.It
.Pq optionally
commit the changes.
.El
.
.Pp
.
.Nm
aborts on failure in any step.
.
.Ss Options
All options beside
.Fl h
have their configuration variable counterparts.
See the
.Sx FILES
section for more information.
.
.Bl -tag -width "xx"
.It Fl h
Display a usage description.
.
.It Fl A Ar BSAPI
Use Build Service at
.Ar BSAPI
(URL or alias).
Passed to
.Xr osc 1 .
.
.It Fl B Ar BUILDARGS
Use
.Ar BUILDARGS
.Pq after field splitting
as arguments to
.Nm osc Cm build
.Pq see Fl b .
May be given more than once,
each instance yields a separate
.Nm osc Cm build .
.
.It Fl C
Skip the
.Nm osc Cm commit
step.
.
.It Fl P Ar PROJECT
Update Build Service package of
.Ar PROJECT .
.
.It Fl b
Run
.Nm osc Cm build
before
.Nm osc Cm commit .
If the build fails,
.Nm
aborts.
See
.Va $bsu_osc_build .
.
.It Fl d Ar URL
Retrieve the source tarball from
.Ar URL .
If
.Ar URL
is
.Dq \&. ,
.Nm
uses
.Xr git-archive 1
or
.Xr hg-archive 1
in
.Ev PWD
as appropriate.
Otherwise,
.Nm
uses
.Xr wget 1 .
.
.It Fl m Ar COMMITMSG
Use
.Ar COMMITMSG
for the commit in Build Service.
Defaults to
.Dq Update to version Ar VERSION .
.
.It Fl n
Report values derived from
configuration files and command line arguments, then exit.
.
.It Fl p Ar PACKAGE
Update Build Service
.Ar PACKAGE .
.
.It Fl s Ar SPECFILE
Use
.Ar SPECFILE Ns Li .in
from
.Ar TARBALL ,
commit
.Ar SPECFILE
into the Build Service.
All occurrences of
.Li __VERSION__
in
.Ar SPECFILE
are replaced with
.Ar VERSION .
.Ar SPECFILE
can be a real
.Li .spec
file (RPM) or a
.Pa PKGBUILD
file (ArchLinux).
May be given more than once, all files are processed.
.
.It Fl t Ar TARBALL
Use
.Ar TARBALL
for the name of the downloaded file.
.El
.
.Ss Operands
.
.Bl -tag -width "xx"
.
.It Ar TAG
Update the package from
.Ar TAG .
Substituted for
.Ev $bsu_tag
in values derived from command line
options and configuration files.
.
.It Ar VERSION
Update the package to
.Ar VERSION .
.
If
.Ar VERSION
is not given, it is generated using
.Fn bsu_version_hook
if it exists, otherwise
from
.Ar TAG
by stripping the initial
.Dq Li v
if any.
Substituted for
.Ev $bsu_version
in values derived from command line
options and configuration files.
.El
.
.Ss Hooks
.
.Nm
allows tailoring the update process through shell functions,
see the
.Sx FILES
section for more information.
.
.\" DESCRIPTION }}}
.\" .Sh IMPLEMENTATION NOTES
.\" ENVIRONMENT {{{
.Sh ENVIRONMENT
.Nm
itself does not use any environment variables.
It is, however, implemented in terms of third-party commands
which
.Em do
use them.
This means
.Nm
may be influenced by environment variables used by
.Xr git 1 ,
.Xr hg 1 ,
.Xr osc 1 ,
.Xr tar 1 ,
.Xr wget 1 ,
.Xr zsh 1 ,
possibly others.
.\" ENVIRONMENT }}}
.\" FILES {{{
.Sh FILES
.Nm
recognizes two optional configuration files,
.Pa .bs-update-hooks
and
.Pa .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.
.
.Pp
.
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.
.
.Pp
.
Syntactically, the configuration files are limited shell scripts
recognizing two kinds of statements: parameter assignments, and
function definitions.
.
.Ss Shell Functions (Hooks)
. Bl -ohang
. It Fn bsu_specfile_hook
If this function exists, it is responsible for providing a
. Va $s Ns .in
file for each
. Va $s
in
. Va $bsu_specfiles .
.Nm
will invoke it with arguments consisting of
.Va $bsu_version ,
.Va $bsu_tag ,
.Va $bsu_tarball
and
.Va $bsu_specfiles .
.
. It Fn bsu_tarball_hook
The tarball may need finalization before it is checked into
the Build Service, eg.
.Nm autoconf ,
.Nm git
submodules
or
.Nm npm .
If this function exists it is executed in the root of the checked out
package, with the tarball name in the first argument.
.
. It Fn bsu_version_hook
If the
.Ar VERSION
argument is not given and this function exists it is executed with
.Ar $1
set to the value of the
.Ar TAG
argument, and its output is used as the final version string.
. El
.Ss Variables
. Bl -tag -compact -width "x"
. It Va bsu_bs_apiurl       Pq Fl A
. It Va bsu_bs_commit       Pq Fl C
. It Va bsu_bs_commitmsg    Pq Fl m
. It Va bsu_bs_package      Pq Fl p
. It Va bsu_bs_project      Pq Fl P
. It Va bsu_dloadurl        Pq Fl d
. It Va bsu_dryrun          Pq Fl n
. It Va bsu_specfiles       Pq Fl s
. It Va bsu_tarball         Pq Fl t
. It Va bsu_test_build      Pq Fl b
. It Va bsu_osc_build       Pq Fl B
Array of strings where each item is used
.Pq after field splitting
as arguments to
.Nm osc Cm build
.Pq see Fl b .
. El
.\" FILES }}}
.\" EXAMPLES {{{
.Sh EXAMPLES
.
.Ss Interactive Use by Upstream Maintainer
.
This is a real-world example showing common
.Pa .bs-update
setup and the use of
.Nm
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.
.Pp
We need a working copy to hack on:
.
.Bd -literal -offset 2n
git clone git@github.com:roman-neuhauser/bs-update.git
cd bs-update
.Ed
.
.Pp
Since we're going to use
.Nm
repeatedly, it makes sense to employ a configuration file,
.Pa .bs-update .
Everything can still be overridden using options on the command line:
.
.Bd -literal -offset 2n
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
.Ed
.
.Pp
Commit some changes:
.
.Bd -literal -offset 2n
vim bs-update.in
make check
git commit bs-update.in
.Ed
.
.Pp
Build the package locally, using the currently checked out revision.
Does not commit into the Build Service:
.
.Bd -literal -offset 2n
bs-update -Cbd . HEAD
.Ed
.
.Pp
If it was ok we can tag it and publish the tag:
.
.Bd -literal -offset 2n
git tag -a v42.69
git push origin master v42.69
.Ed
.
.Pp
Commit the new release into the Build Service:
.
.Bd -literal -offset 2n
bs-update v42.69
.Ed
.
.Ss Snapshot-generating Cronjob
.
This example demonstrates using
.Fn 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.
.
.Bd -literal -offset 2n
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
.Ed
.\" EXAMPLES }}}
.\" DIAGNOSTICS {{{
.Sh DIAGNOSTICS
.Nm
exits with
.Li 0
on success, and with
.Li >0
otherwise.
.\" DIAGNOSTICS }}}
.\" .Sh COMPATIBILITY
.\" SEE ALSO {{{
.Sh SEE ALSO
.Xr git 1 ,
the openSUSE Build Service
.Aq https://build.opensuse.org/ ,
and its wiki
.Aq http://en.opensuse.org/Portal:Build_Service .
.\" SEE ALSO }}}
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" AUTHORS {{{
.Sh AUTHORS
.
.Nm
and this manual page are written by
.An Roman Neuhauser Aq Mt neuhauser@sigpipe.cz .
.Pp
See
.Lk https://github.com/roman-neuhauser/bs-update/ .
.\" AUTHORS }}}
.\" BUGS {{{
.Sh BUGS
No doubt plentiful.
Please report them at
.Lk https://github.com/roman-neuhauser/bs-update/issues .
.\" BUGS }}}