ubuntu-dev-tools/doc/pbuilder-dist.1

.TH PBUILDER\-DIST 1 "January 10, 2008" "ubuntu-dev-tools"

.SH NAME
pbuilder\-dist, cowbuilder\-dist \- multi-distribution pbuilder/cowbuilder wrapper

.SH SYNOPSIS
\fBpbuilder\-dist\fP \fIdistribution\fR [\fIarchitecture\fR] \fIoperation\fR
[\fBoptions\fP] [\fI...\fR]

\fBcowbuilder\-dist\fP \fIdistribution\fR [\fIarchitecture\fR] \fIoperation\fR
[\fBoptions\fP] [\fI...\fR]

.SH DESCRIPTION
\fBpbuilder\-dist\fP is a wrapper that makes it easy to use pbuilder with many different
versions of Ubuntu and/or Debian.
.PP
It is common to symlink this script in order to give it many names in the form of
\fBpbuilder\-\fIdistribution\fP\fR or \fBpbuilder\-\fIdistribution\fR\-\fIarchitecture\fP\fR,
like for example \fBpbuilder\-feisty\fP, \fBpbuilder\-sid\fP, \fBpbuilder\-gutsy\-i386\fP, etc.
.PP
The same applies to \fBcowbuilder\-dist\fP, which uses cowbuilder. The main
difference between both is that pbuilder compresses the created chroot as a
a tarball, thus using less disc space but needing to uncompress (and possibly
compress) its contents again on each run, and cowbuilder doesn't do this.

.SH USAGE
There are many arguments listed on the synopsis; each of them, if used, has to be used exactly in
the same order as it appears there.
In case you renamed the script to \fBpbuilder\-\fIdistribution\fP\fR, do not
use the \fBdistribution\fP parameter; same with \fBi386\fP / \fBamd64\fP if
the name also contains \-\fIarchitecture\fR.
.TP
\fBdistribution\fP
Replace this with the codename of the version of Ubuntu or Debian you want to use.
.TP
\fBarchitecture\fP
This optional parameter will attempt to construct a chroot in a foreign
architecture.
For some architecture pairs (e.g. i386 on an amd64 install), the chroot
will be created natively.
For others (e.g. arm64 on an amd64 install), qemu\-user\-static will be
used.
Note that some combinations (e.g. amd64 on an i386 install) require
special separate kernel handling, and may break in unexpected ways.
.TP
\fBoperation\fP
Replace this with the action you want \fBpbuilder\fP to do (create, update,
build, clean, login or execute).
If you don't specify any action, but the next argument is a .dsc file, it
will assume that it should build.
Check its manpage for more details.
.TP
\fB[...]\fP
.br
Replace this with other parameters, if needed.
For example, if \fBbuild\fP is the option, you will need to also specify
a .dsc file. As a special feature, if you specify a .dsc file you can
skip the \fBbuild\fP option and this script will automatically assume that
building is the action you want to do.

.SH OPTIONS
.TP
\fB\-\-main\-only\fP (deprecated: \fBmainonly\fP)
If you specify this option, only packages from the \fImain\fP (in Debian) or
\fImain\fP and \fIrestricted\fP (in Ubuntu) components will be used. By
default, all official components are enabled. This only has effect when
creating a new environment.
.TP
\fB\-\-debug\-echo\fP
The generated \fBpbuilder\fP/\fBcowbuilder\fP command will be printed to the
standard output instead of being executed. This is useful for debugging.
.TP
\fB\-\-buildresult\fP \fBDIRECTORY\fP (pbuilder\-dist only)
If this option is specified, the resultant files of the \fBpbuilder\fP build
are placed in \fBDIRECTORY\fP.
.TP
\fB\-\-release\-only\fP
Only use the release pocket.
Default for development releases.
.TP
\fB\-\-security\-only\fP
Only use the release and security pockets.
Suitable environment for preparing security updates.
.TP
\fB\-\-updates\-only\fP
Only use the release, security, and updates pocket.
Not the proposed\-updates pocket.
.TP
\fB\-\-backports\fP
Also use the backports archive..

.SH EXAMPLES
.TP
pbuilder\-dist gutsy create
Creates a \fBpbuilder\fP environment for Ubuntu Gutsy, with all components enabled.
.TP
pbuilder\-sid \-\-main\-only create
Creates a \fBpbuilder\fP environment for Debian Sid, with only the main component.
.TP
pbuilder\-feisty build ./sample_1.0\-0ubuntu1.dsc
Builds the specified package on an already existing Ubuntu Feisty environment.
.TP
pbuilder\-dist feisty withlog build ./sample_1.0\-0ubuntu1.dsc
Same as above, but stores \fBpbuilder\fP's output on a file.
.TP
pbuilder\-etch i386 update
Updates an existing i386-architecture Debian Etch environment on an amd64 system.
.TP
cowbuilder-experimental create
Creates a \fBcowbuilder\fP environment for Debian Experimental.

.SH FILES AND ENVIRONMENT VARIABLES
By default, \fBpbuilder\-dist\fP will store all the files it generates in
\fB~/pbuilder/\fP. This can be changed by setting the \fBPBUILDFOLDER\fP
environment variable. If the directory doesn't exist, it will be created on
the run.
.PP
A file with the log of the last operation, called last_operation.log, will be
saved in the results subdirectory of each build environment.
.PP
The default authentication method is \fBsudo\fP. You can change this by
setting the \fBPBUILDAUTH\fP variable.
.PP
By default, \fBpbuilder\-dist\fP use the master Debian and Ubuntu mirrors.
The pbuilder \fBMIRRORSITE\fP and \fBOTHERMIRROR\fP variables are
supported, as are the standard ubuntu\-dev\-tools variables:
\fBUBUNTUTOOLS_DEBIAN_MIRROR\fP, \fBPBUILDER_DIST_DEBIAN_MIRROR\fP,
\fBUBUNTUTOOLS_DEBSEC_MIRROR\fP, \fBPBUILDER_DIST_DEBSEC_MIRROR\fP,
\fBUBUNTUTOOLS_UBUNTU_MIRROR\fP, \fBPBUILDER_DIST_UBUNTU\fP,
\fBUBUNTUTOOLS_UBUNTU_PORTS_MIRROR\fP, and
\fBPBUILDER_DIST_UBUNTU_PORTS_MIRROR\fP.
See \fBubuntu\-dev\-tools\fP (5) for details.
.PP
You may also want to know that \fBpbuilder\-dist\fP exports \fBDIST\fP and
\fBARCH\fP environment variables to the invoked process, containing the name
of the distribution and the architecture targeted by the current build. You
can make use of them, for example, in \fBpbuilderrc\fP.

.SH BUGS
If you experience any problem with this script contact me on rainct@ubuntu.com
or file a bug at https://bugs.launchpad.net/ubuntu/+source/ubuntu\-dev\-tools.
.PP
Please ensure first that the problem is really this script and not an issue
with \fBpbuilder\fP or \fBcowbuilder\fP themselves.

.SH SEE ALSO
.BR pbuilder (1),
.BR pbuilderrc (5),
.BR cowbuilder (1),
.BR ubuntu\-dev\-tools (5).

.SH AUTHORS
\fBpbuilder\-dist\fP and this manual page were written by Siegfried-A. Gevatter
<rainct@ubuntu.com>, with contributions from Iain Lane
<iain@orangesquash.org.uk>, Emmet Hikory <persia@ubuntu.com> and others.

\fBpbuilder\-dist\fP is released under the GNU General Public License, version
2 or later.