.\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.pso bs-config --format=man
.TH BS 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
bs \- build software
.br
.ne 5
.SH SYNOPSIS
.B bs
\*[ade_standard_synopsis_component]
[
.B \-f
.I file
|
.B \-\-config=\fIfile\fR
]
[
.B \-k
|
.B \-\-no\-desandboxing
]
[
.B \-\-no\-sequencing
]
.I step
.I module
.br
.ne 5
.SH DESCRIPTION
.B Bs
is a tool to perform the steps of the development cycles of programs and Debian packages.
.PP
It takes two arguments; 
.I 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
.I module
to specify the name of the program or Debian package. The steps and their meanings are
listed below.
.PP
Familiarity with the development and release cycles for programs and Debian packages is useful;
see 
.B \%https://www.pasta.freemyip.com/computing/articles/program-and-debian-package-development-cycles/
for an overview.
.br
.ne 5
.SH STEPS
The steps of the program development cycle are these, listed in the order in
which they are to be called:
.TP
.B prologue\-sources\fR,\fB ps
Run the user-written script specified by the
.B SITE_PROLOGUE_SOURCES_CMD
configuration variable. This script should perform all the actions necessary to bring
.I module 
to a state where the program developer can enter the normal program development cycle (starting with the
.B schedule\-sources
step). It is expected that this script should: create the 
.I module
directory, populate it with a minimal set 
of source files, archive it in a Subversion repository (see
.B svn\fR(1))
and immediately retrieve a copy of the program sources from the repository.
.TP
.B schedule\-sources\fR,\fB ss
Schedule a new release.
.TP
.B test\-sources\fR,\fB 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 
.I module\fR's
regression test suite and attempt to make the tarball. 
.TP
.B release\-sources\fR,\fB rs
Release the sources. This means: repeat the 
.B test\-sources
step but tolerate no errors or warnings,
finalise the ChangeLog (see
.B adech\fR(1))
and, in the Subversion repository, copy 
.I module\fB/trunk
to
.I module\fB/tags/\fIrelease\-id\fR.
.TP
.B make\-tarball\fR,\fB mt
Make the tarball and upload it.
.TP
.B epilogue\-sources\fR,\fB es
Run the user-written script specified by the
.B SITE_EPILOGUE_SOURCES_CMD
configuration variable. 
.PP
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
.B schedule\-sources
step.
.PP
The steps of the Debian package development cycle are these, listed in the order in
which they are to be called:
.TP
.B prologue\-pkgctrl\fR,\fB pp
Run the user-written script specified by the
.B SITE_PROLOGUE_PKGCTRL_CMD
configuration variable. This script should perform all the actions necessary to bring
.I module\fB.debian\fR
module to a state where the Debian package developer can enter the normal program development cycle (starting with the
.B schedule\-pkgctrl
step). It is expected that this script should: create the 
.I module\fB.debian\fR
directory, populate it with a minimal set 
of Debian package control files, archive it in a Subversion repository
and immediately retrieve a copy of the 
Debian package control files from the repository.
.TP
.B schedule\-pkgctrl\fR,\fB sp
Schedule a new release.
.TP
.B test\-pkgctrl\fR,\fB 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
.I module\fR's
regression test suite) and make the Debian package.
.TP
.B release\-pkgctrl\fR,\fB rp
Release the Debian package control files. This means: repeat the 
.B test\-pkgctrl
step but tolerate no errors or warnings,
finalise the changelog (see
.B dch\fR(1))
and, in the Subversion repository, copy 
.I module\fB.debian/trunk
to
.I module\fB.debian/tags/\fIrelease\-id\fR.
.TP
.B make\-package\fR,\fB mp
Make the Debian package and upload it.
.TP
.B epilogue\-pkgctrl\fR,\fB ep
Run the user-written script specified by the
.B SITE_EPILOGUE_PKGCTRL_CMD
configuration variable. It is expected that this script insert the Debian package into a Debian package
repository (perhaps using
.B paa\fR(1)).
.PP
After running the above steps, the Debian package developer should normally 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
.B schedule\-pkgctrl
step.
.PP
In addition, there are the following steps available:
.TP
.B status
Report the last successfully completed program source and Debian package development steps.
.TP
.B sync
Inspect the repository and working copies to determine the status of the sources and package 
control files. 
.br
.ne 5
.SH CONFIGURATION
Many variables need to be set in the configuration file. See the comments in 
.B \*[bs_doc_prefix]/examples/bs.conf
for details.
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-f \fIfile\fR, \fB\-\-config=\fIfile\fR
Set the configuration file. If this option is not used then the file specified by the 
.B BS_CONFIG
environment variable is used and, if that is not set, a hard-coded default is used (see
.B ENVIRONMENT
and
.B FILES
below).
.TP
.B \-k\fR, \fB\-\-no\-desandboxing
Do not delete the sandbox after use; this might be useful in diagnosing problems with the build.
.TP
.B \-\-no\-sequencing
Do not enforce step sequencing restrictions.
.br
.ne 5
.SH EXIT STATUS
On success
.B bs
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.B \*[bs_etc_prefix]/bs.conf
Default configuration file
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
BS_CONFIG
Specifies the configuration file.
.br
.ne 5
.SH EXAMPLES
In this example session, we create a new program \(oqfoo\(cq and package it. 
.PP
We base the configuration on the example configuration file included with
.B bs\fR, 
but use a new local Subversion repository and keep our working copies in ~/dev:
.IP
.nf
.fam C
user$ \fBcp \*[bs_doc_prefix]/examples/bs.conf ~/etc/\fR
user$ \fBexport BS_CONFIG=~/etc/bs.conf\fR
user$ \fBsvnadmin create ~/var/svnrepo\fR
user$ \fBecho SOURCES_SVNREPO_URL_PREFIX=file://~/var/svnrepo \[rs]
\ \ \ \ \[char62]\[char62] ~/etc/bs.conf\fR
user$ \fBecho PKGCTRL_SVNREPO_URL_PREFIX=file://~/var/svnrepo \[rs]
\ \ \ \ \[char62]\[char62] ~/etc/bs.conf\fR
user$ \fBecho SOURCES_SVNWC_DIR_PREFIX=~/dev \[char62]\[char62] ~/etc/bs.conf\fR
user$ \fBecho PKGCTRL_SVNWC_DIR_PREFIX=~/dev \[char62]\[char62] ~/etc/bs.conf\fR
.fam T
.fi
.PP 
We create the \(oqfoo\(cq program sources using the example
.B prologue\-sources
script included with 
.B bs\fR
(this particular example script uses
.B adegmt\fR(1) 
to generate the module, complete with man pages and a basic regression test suite. 
.B Adegmt\fR(1)
needs to be told the name of a template module, so the script prompts for this information):
.IP
.nf
.fam C
user$ \fBbs ps foo\fR
template: \fBlxshell\fR
.fam T
.fi
.PP
At this point we have a fully functional \(oqfoo\(cq program source tree in the Subversion 
repository and in ~/dev.
.PP
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 \(oqFOO#001\(cq.
.PP
We announce our intent to fix this bug by scheduling a new release:
.IP
.nf
.fam C
user$ \fBbs ss foo\fR
bug ID []: \fBFOO#001\fR
bump type (b)ug, (f)eature or (r)ewrite [b]: 
.fam T
.fi
.PP
We test the program sources:
.IP
.nf
.fam C
user$ \fBbs ts foo\fR
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
\&...
.fam T
.fi
.PP
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
.B svn pset svn:keywords 
and
.B svn pset svn:ignore
and then committing all changes back to the repository:
.IP
.nf
.fam C
user$ \fBsvn commit -qm \(dq  * first proper version\(dq foo\fR
.fam T
.fi
.PP
If we repeat the tests then no errors are shown:
.IP
.nf
.fam C
user$ \fBbs ts foo\fR
.fam T
.fi
.PP
Now we are free to release the sources and make the tarball:
.IP
.nf
.fam C
user$ \fBbs rs foo\fR
user$ \fBbs mt foo\fR
user$ \fBls -l /pub/computing/software/local/sources/localpublic\fR
-rw-r--r-- 1 alexis alexis    11964 Jan 16 11:25 foo-0.tar.gz
.fam T
.fi
.PP
(Note that the initial release number is 0; see
.B adech\fR(1)
for an explanation.)
.PP
Now that the sources have been released, we take off our program developer hat
and put on our package developer hat.
.PP
We create the \(oqfoo\(cq Debian package control files using the example
.B prologue\-pkgctrl
script included with 
.B bs\fR:
.IP
.nf
.fam C
user$ \fBbs pp foo\fR
.fam T
.fi
.PP
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 \(oqFOOPKG#001\(cq.
.PP
We announce our intent to fix this bug by scheduling a new release of the package:
.IP
.nf
.fam C
user$ \fBbs sp foo\fR
schedule-pkgctrl: WARNING: don't forget to update the changelog 
\ \ \ \ (it's got dummy text in)
.fam T
.fi
.PP
We test the program sources:
.IP
.nf
.fam C
user$ \fBbs tp foo\fR
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>
\&...
.fam T
.fi
.PP
The error messages above relate to missing Subversion properties,
the automated modification of the ChangeLog made by the previous step and
.B lintian\fR(1)
errors; these are fixed by using
.B svn pset svn:keywords 
and
.B svn pset svn:ignore\fR,
fixing the lintian errors (the nature and description of which is outside the scope
of this document) and then committing all changes back to the repository:
.IP
.nf
.fam C
user$ \fBsvn commit -qm \(dq  * correct svn keywords\(dq foo.debian\fR
.fam T
.fi
.PP
If we repeat the tests then no errors are shown:
.IP
.nf
.fam C
user$ \fBbs tp foo\fR
.fam T
.fi
.PP
Now we are free to release the Debian package control files and make the package:
.IP
.nf
.fam C
user$ \fBbs rp foo\fR
user$ \fBbs mp foo\fR
user$ \fBls -l /pub/computing/software/local/debian/localpublic.queue/\fR
-rw-r--r-- 1 alexis alexis 5384 Jan 16 11:43 foo_0-2_all.deb
.fam T
.fi
.PP
The
.B 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 
.B epilogue\-package 
file does that:
.IP
.nf
.fam C
root# \fBbs -f ~user/etc/bs.conf ep foo\fR
.fam T
.fi
.PP
(Note that, in this example, this step is run as root, necessitating the use of
the 
.B \-f
option or the temporary setting of the
.B BS_CONFIG
environment variable.)
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B bs\fR.
.br
.ne 5
.SH SEE ALSO
adech(1), adegmt(1), bs-config(1), cp(1), dch(1), echo(1), lintian(1), paa(1), svn(1), svnadmin(1),
.br
\%https://www.pasta.freemyip.com/computing/software/bs/,
.br
\%https://www.pasta.freemyip.com/computing/articles/program-and-debian-package-development-cycles/
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2011-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]