.TH "cowbuilder" 8 "2007 Jun 17" "cowdancer" "cowdancer"
.SH "NAME"
cowbuilder \- a pbuilder wrapper for cowdancer.
.SH SYNOPSIS
.BI "cowbuilder [" "commands" "] [" "options" "]"
.SH DESCRIPTION
.B cowbuilder
Executes the specified pbuilder operation with
.B cowdancer

.SH "COMMANDS"

Most commands invoke pbuilder with the specified commands, see
pbuilder manual for details.

.TP
.B "\-\-create"

Create the base.cow image.
The directory for base.cow should be empty, or this command will fail.

.TP
.B "\-\-update"

Update the base.cow image.

.TP
.BI "\-\-build " ".dsc-file"

Build a package given a .dsc file

.TP
.B "\-\-login"

Start a session within the base.cow.

.TP
.B "\-\-execute"

Execute a command within the base.cow.

.TP
.B "--dumpconfig"

dump configuration information.

.SH "OPTIONS"

Most options are the same as pbuilder, except for the following which are handled specially

.TP
.B "\-\-buildplace"

The place where COW operation takes place.

.TP
.B "\-\-basepath" 
has a very different meaning to 
.B basetgz
option of pbuilder, since there is no tgz.  This option specifies the
directory in which the COW master data is stored, the default being 
.B "/var/cache/pbuilder/base.cow"

.TP
.BI "\-\-configfile [" "configuration file to load" "]"
Additional configuration file to read after all other
configuration files have been read.

.TP
.BI "\-\-no\-cowdancer\-update"

Do not use cowdancer on cowbuilder --update. Please use this option
when cowdancer is interfering with upgrade process, or cowdancer
itself is being upgraded within chroot.

.TP
.BI "\-\-debian\-etch\-workaround"

Work around on Debian etch compatibility. cow-shell will search for
all files in chroot, but will work.

.SH "CONFIGURATION FILES"

cowbuilder reads the following configuration files per default.

.TP
.B "/usr/share/pbuilder/pbuilderrc"
Application default, not to be changed.

.TP
.B "/etc/pbuilderrc"
System-wide default.

.TP
.B "~/.pbuilderrc"
User default

.TP
.I "anything specified with \-\-configfile option"
Additional configuration at runtime.

.SH "CONFIGURATION FILE OPTIONS"

The possible configuration options are as follows.  Others are
ignored.

.TP
.BI "DISTRIBUTION=" "distribution"

.TP
.BI "BUILDRESULT=" "directory"

.TP
.BI "BUILDPLACE=" "directory"

.TP
.BI "BASEPATH=" "path"

.TP
.BI "MIRRORSITE=" "http://mirror"

.TP
.BI "NO_COWDANCER_UPDATE=" "1"

See
.B "--no-cowdancer-update"

.TP
.BI "DEBIAN_ETCH_WORKAROUND=" "1"

See
.B "--debian-etch-workaround"

.SH "EXAMPLES"

.TP
.B "cowbuilder --create"
Create a base.cow image.

.nf
# cowbuilder --create --hookdir /usr/share/doc/pbuilder/examples/workaround/ --distribution etch --debootstrap debootstrap --basepath /var/cache/pbuilder/base-test.cow
bash: /root/.pbuilderrc: No such file or directory
W: /home/dancer/.pbuilderrc does not exist
 -> Running in no-targz mode
Distribution is etch.
Building the build environment
 -> running debootstrap
/usr/sbin/debootstrap
I: Retrieving Release
	.
	.
.hy

.TP 
.B "cowbuilder --update"
Update the base.cow image.

.nf
# cowbuilder --update
bash: /root/.pbuilderrc: No such file or directory
 -> Copying COW directory
 -> Invoking pbuilder
W: /home/dancer/.pbuilderrc does not exist
 -> Running in no-targz mode
 -> copying local configuration
 -> mounting /proc filesystem
 -> mounting /dev/pts filesystem
 -> policy-rc.d already exists
Refreshing the base.tgz
 -> upgrading packages
	.
	.
.hy

.TP
.B "cowbuilder --build test_0.1.dsc"
Build the package specified in dsc file, with the base.cow image.

.TP
.B "pdebuild --pbuilder cowbuilder"
Run
.B "cowbuilder --build"
against the current directory.
The current directory should be an extracted Debian source package directory.

Edit
.B "/etc/pbuilderrc"
to have
.B "PDEBUILD_PBUILDER=cowbuilder"
to make this the default behavior for 
.B pdebuild.

.TP
.B "cowbuilder --login --bindmounts /home/dancer"
Start a cow-shell session inside base.cow, with 
.I "/home/dancer"
 being bind-mounted to within chroot.

Note that cowbuilder will not cow-protect what is inside
.B /home/

.nf
# cowbuilder --login --bindmount ${HOME}
bash: /root/.pbuilderrc: No such file or directory
 -> Copying COW directory
 -> Invoking pbuilder
W: /home/dancer/.pbuilderrc does not exist
 -> Running in no-targz mode
 -> copying local configuration
 -> mounting /proc filesystem
 -> mounting /dev/pts filesystem
-> Mounting /home/dancer
 -> policy-rc.d already exists
 -> entering the shell
#
man .hy

.TP
.B "cowbuilder --create --distribution sid --basepath /var/cache/pbuilder/base-test.cow"
Create a base.cow image with the path 
.B "/var/cache/pbuilder/base-test.cow"
and distribution sid.

.SH "AUTHOR"
Junichi Uekawa (dancer@debian.org)

.SH "SEE ALSO"
.BR "/usr/share/doc/pbuilder/pbuilder-doc.html, "
.BR "pbuilder (" 8 "), "
.BR "pdebuild (" 1 ") "