BS(1) General Commands Manual BS(1)
NAME
bs - build software
SYNOPSIS
bs [ -V | --version ] [ -v | --verbose | -d level | --debug=level ] [
-h | --help ] [ -p | --paths ] [ -n | --simulate ] [ -f file | --con-
fig=file ] [ -k | --no-desandboxing ] [ --no-sequencing ] [ --de-
lay-fail ] step module
DESCRIPTION
Bs is a tool to perform the steps of the development cycles of programs
and Debian packages.
It takes two arguments; step to specify the cycle (program or Debian
package) and the step of that cycle (prologue, schedule release, test,
release, make tarball/package, epilogue) and module to specify the name
of the program or Debian package. The steps and their meanings are
listed below.
Familiarity with the development and release cycles for programs and
Debian packages is useful.
STEPS
The steps of the program development cycle are these, listed in the or-
der in which they are to be called:
prologue-sources, ps
Run the user-written script specified by the SITE_PRO-
LOGUE_SOURCES_CMD configuration variable. This script should
perform all the actions necessary to bring module to a state
where the program developer can enter the normal program devel-
opment cycle (starting with the schedule-sources step). It is
expected that this script should: create the module directory,
populate it with a minimal set of source files, archive it in a
Subversion repository (see svn(1)) and immediately retrieve a
copy of the program sources from the repository.
schedule-sources, ss
Schedule a new release.
test-sources, ts
Test the sources. This means: run some standard tests (e.g.
check the program sources are uptodate with respect to their
Subversion repository), run module's regression test suite and
attempt to make the tarball.
release-sources, rs
Release the sources. This means: repeat the test-sources step
but tolerate no errors or warnings, finalise the ChangeLog and,
in the Subversion repository, copy module/trunk to mod-
ule/tags/release-id.
make-tarball, mt
Make the tarball and upload it.
epilogue-sources, es
Run the user-written script specified by the SITE_EPI-
LOGUE_SOURCES_CMD configuration variable.
After running the above steps, the program developer should normally
wait for an external event (e.g. a bug report or the release of a new
version of a prerequisite library) and then repeat the cycle from the
schedule-sources step.
The steps of the Debian package development cycle are these, listed in
the order in which they are to be called:
prologue-pkgctrl, pp
Run the user-written script specified by the SITE_PROLOGUE_PKGC-
TRL_CMD configuration variable. This script should perform all
the actions necessary to bring module.debian module to a state
where the Debian package developer can enter the normal program
development cycle (starting with the schedule-pkgctrl step). It
is expected that this script should: create the module.debian
directory, populate it with a minimal set of Debian package con-
trol files, archive it in a Subversion repository and immedi-
ately retrieve a copy of the Debian package control files from
the repository.
schedule-pkgctrl, sp
Schedule a new release.
test-pkgctrl, tp
Test the Debian package control files. This means: run some
standard tests (e.g. check the Debian package control files are
uptodate with respect to their Subversion repository), make the
Debian package (and in so doing run module's regression test
suite) and make the Debian package.
release-pkgctrl, rp
Release the Debian package control files. This means: repeat the
test-pkgctrl step but tolerate no errors or warnings, finalise
the changelog (see dch(1)) and, in the Subversion repository,
copy module.debian/trunk to module.debian/tags/release-id.
make-package, mp
Make the Debian package and upload it.
epilogue-pkgctrl, ep
Run the user-written script specified by the SITE_EPILOGUE_PKGC-
TRL_CMD configuration variable. It is expected that this script
insert the Debian package into a Debian package repository (per-
haps using paa(1)).
After running the above steps, the Debian package developer should nor-
mally wait for an external event (e.g. a bug report or the release of a
new version of the program sources) and then repeat the cycle from the
schedule-pkgctrl step.
In addition, there are the following steps available:
status Report the last successfully completed program source and Debian
package development steps.
CONFIGURATION
Many variables need to be set in the configuration file. See the com-
ments in /usr/share/doc/bs/examples/bs.conf for details.
OPTIONS
-d level, --debug=level Determines how verbose this program will be.
The message types displayed for the different
values of level are as follows: 0 displays no
messages; 1 displays only errors, 2 displays
errors and warnings; 3 displays errors, warn-
ings and informational messages; higher values
display errors, warnings, informational mes-
sages and various messages intended for debug-
ging. The default is 2.
-h, --help Displays a brief usage message.
-p, --paths Lists the compiled-in paths of various files
and directories that this program uses. -n,
--simulate Some external commands that this
program runs may be displayed rather than ac-
tually executed. BEWARE: different programs
implement different levels of simulation; so
this option may work perfectly; on the other
hand it may do nothing at all!
-v, --verbose Equivalent to -d 3.
-V, --version Prints the program's version number and exits.
-f file, --config=file Set the configuration file. If this option is
not used then the file specified by the
BS_CONFIG environment variable is used and, if
that is not set, a hard-coded default is used
(see ENVIRONMENT and FILES below).
-k, --no-desandboxing Do not delete the sandbox after use; this
might be useful in diagnosing problems with
the build.
--delay-fail When step is test-sources or test-pkgctrl,
then bs exits at the end of any test phase
that raises an error, i.e. it does not proceed
to the next test phase. This option changes
that behaviour so that bs does proceed to the
next text phase and only raises an error when
all test phases have been executed. This op-
tion is intended to aid debugging errors that
only manifest themselves deep in bs's execu-
tion stack.
--no-sequencing Do not enforce step sequencing restrictions.
EXIT STATUS
On success bs returns zero. On failure it returns non-zero and displays
a diagnostic message.
FILES
/etc/bs/bs.conf Default configuration file
ENVIRONMENT VARIABLES
BS_CONFIG Specifies the configuration file.
EXAMPLES
In this example session, we create a new program 'foo' and package it.
We base the configuration on the example configuration file included
with bs, but use a new local Subversion repository and keep our working
copies in ~/dev:
user$ cp /usr/share/doc/bs/examples/bs.conf ~/etc/
user$ export BS_CONFIG=~/etc/bs.conf
user$ svnadmin create ~/var/svnrepo
user$ echo SOURCES_REPOSITORY_URL_PREFIX=file://~/var/svnrepo \
>> ~/etc/bs.conf
user$ echo PKGCTRL_REPOSITORY_URL_PREFIX=file://~/var/svnrepo \
>> ~/etc/bs.conf
user$ echo SOURCES_WORKINGCOPY_DIR_PREFIX=~/dev >> ~/etc/bs.conf
user$ echo PKGCTRL_WORKINGCOPY_DIR_PREFIX=~/dev >> ~/etc/bs.conf
We create the 'foo' program sources using the example prologue-sources
script included with bs (this particular example script uses adegmt(1)
to generate the module, complete with man pages and a basic regression
test suite. Adegmt(1) needs to be told the name of a template module,
so the script prompts for this information):
user$ bs ps foo
template: lxshell
At this point we have a fully functional 'foo' program source tree in
the Subversion repository and in ~/dev.
Immediately, we submit a bug report stating that the program does not
do what it is supposed to do. It may seem odd to submit a bug report
even before the program sources have been written but it reduces the
amount of effort that is outside of the development cycle and therefore
not subject to the cycle's control, its checks and its logging. Let us
suppose that this bug report is assigned the ID 'FOO#001'.
We announce our intent to fix this bug by scheduling a new release:
user$ bs ss foo
bug ID []: FOO#001
bump type (b)ug, (f)eature or (r)ewrite [b]:
We test the program sources:
user$ bs ts foo
M foo/doc/ChangeLog
foo/doc/Makefile: no keywords property
foo/man/Makefile: no keywords property
foo/man/foo-config.1: no keywords property
...
? foo/bin/foo
? foo/bin/foo-config
? foo/bin/foodevsh
...
The error messages above relate to missing Subversion properties and
the automated modification of the ChangeLog made by the previous step;
these are fixed by using svn pset svn:keywords and svn pset svn:ignore
and then committing all changes back to the repository:
user$ svn commit -qm " * first proper version" foo
If we repeat the tests then no errors are shown:
user$ bs ts foo
Now we are free to release the sources and make the tarball:
user$ bs rs foo
user$ bs mt foo
user$ ls -l /pub/computing/software/local/sources/localpublic
-rw-r--r-- 1 alexis alexis 11964 Jan 16 11:25 foo-0.tar.gz
(Note that the initial release number is 0.)
Now that the sources have been released, we take off our program devel-
oper hat and put on our package developer hat.
We create the 'foo' Debian package control files using the example pro-
logue-pkgctrl script included with bs:
user$ bs pp foo
Immediately, we submit a bug report stating that the package does not
do what it is supposed to do. It may seem odd to submit a bug report
even before the package control files have been written but it reduces
the amount of effort that is outside of the development cycle and
therefore not subject to its control, its checks and its logging. Let
us suppose that this bug report is assigned the ID 'FOOPKG#001'.
We announce our intent to fix this bug by scheduling a new release of
the package:
user$ bs sp foo
schedule-pkgctrl: WARNING: don't forget to update the changelog
(it's got dummy text in)
We test the program sources:
user$ bs tp foo
M /home/alexis/dev/def/foo.debian/changelog
/home/alexis/dev/def/foo.debian/watch: no keywords property
/home/alexis/dev/def/foo.debian/rules: no keywords property
E: foo: description-is-dh_make-template
E: foo: section-is-dh_make-template
W: foo: superfluous-clutter-in-homepage <insert the upstream URL
if relevant>
...
The error messages above relate to missing Subversion properties, the
automated modification of the ChangeLog made by the previous step and
lintian(1) errors; these are fixed by using svn pset svn:keywords and
svn pset svn:ignore, fixing the lintian errors (the nature and descrip-
tion of which is outside the scope of this document) and then commit-
ting all changes back to the repository:
user$ svn commit -qm " * correct svn keywords" foo.debian
If we repeat the tests then no errors are shown:
user$ bs tp foo
Now we are free to release the Debian package control files and make
the package:
user$ bs rp foo
user$ bs mp foo
user$ ls -l /pub/computing/software/local/debian/localpublic.queue/
-rw-r--r-- 1 alexis alexis 5384 Jan 16 11:43 foo_0-2_all.deb
The make-package step puts the package in a directory specified by the
configuration file but it does not regenerate any repository control
files. The example epilogue-package file does that:
root# bs -f ~user/etc/bs.conf ep foo
(Note that, in this example, this step is run as root, necessitating
the use of the -f option or the temporary setting of the BS_CONFIG en-
vironment variable.)
CAVEATS
None.
STANDARDS
This manual page documents version 3.1.4 of bs.
SEE ALSO
adegmt(1), bs-config(1), cp(1), dch(1), echo(1), lintian(1), paa(1),
svn(1), svnadmin(1)
AUTHOR
Alexis Huxley <alexishuxley@gmail.com>
COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2011-2025 Alexis Huxley
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
29 Apr 2025 BS(1)
