'\" t
.\" Title: debspawn-build
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 18 August, 2018
.\" Manual: debspawn build
.\" Source: Debspawn
.\" Language: English
.\"
.TH "DEBSPAWN\-BUILD" "1" "" "Debspawn" "debspawn build"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
debspawn-build \- Build Debian packages in a container
.SH "SYNOPSIS"
.HP \w'\fBdebspawn\ build\fR\ 'u
\fBdebspawn build\fR [\-h|\-\-help] [\-\-variant] [\-a|\-\-arch] [\-\-suite] [\-\-sign] [\-\-only] [\-\-include\-orig] [\-\-buildflags] [\-\-results\-dir] [\-\-maintainer] [\-\-clean\-source] [\-\-lintian] [\-\-no\-buildlog] [\-i|\-\-interact] [\-e|\-\-setenv] {SUITE} [DIR|DSC_FILE]
.SH "DESCRIPTION"
.PP
Build a Debian package from a directory or source package
*\&.dsc
file\&.
\fBdebspawn\fR
will create a new container for the respective build using the base image specified, build the package and return build artifacts in the default output directory
/var/lib/debspawn/results/
unless a different location was specified via the
\fB\-\-results\-dir\fR
flag\&.
.PP
Downloaded packages that are build dependencies are cached and will be reused on subsequent builds if possible\&.
.PP
You can inject packages into the build environment that are not available in the preconfigured APT repositories by placing them in
/var/lib/debspawn/injected\-pkgs/${container\-name}, or in
/var/lib/debspawn/injected\-pkgs/
to make a package available in all environments\&. Internally,
\fBdebspawn\fR
will build a transient package repository with the respective packages and add it as a package source for APT\&.
.PP
If you want to debug the package build process, you can pass the
\fB\-\-interact\fR
flag to
\fBdebspawn\fR\&. This will open an interactive root shell in the build environment post\-build, no matter whether the build failed or succeeded\&. After investigating the issue / building the package manually, the shell can be exited and the user is asked whether
\fBdebspawn\fR
should copy back the changes made in the packages\*(Aq
debian/
directory to the host to make them permanent\&. Please keep in mind that while interactive mode is enabled, no build log can be created\&.
.SH "EXAMPLES"
.PP
You can build a package from its source directory, or just by passing a plain
\&.dsc
file to
\fBdebspawn build\fR\&. If the result should be automatically signed, the
\fB\-\-sign\fR
flag needs to be passed too:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBcd\fR ~/packages/hello
$ \fBdebspawn build\fR sid \-\-sign
$ \fBdebspawn build\fR \-\-arch=i386 cosmic \&./hello_2\&.10\-1\&.dsc
.fi
.if n \{\
.RE
.\}
.PP
You can also build packages using
\fBgit\-buildpackage\fR
and
\fBdebspawn\fR\&. In this case the
\fB\-\-lintian\fR
flag is also used to perform a Lintian static analysis check in the container after build:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBgbp buildpackage\fR \-\-git\-builder=\*(Aqdebspawn b sid \-\-lintian \-\-sign\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
To debug a build issue interactively, the
\fB\-\-interact\fR
flag can be used:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \fBdebspawn build\fR sid \-\-interact
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.PP
\-h|\-\-help
.RS 4
Print brief help information about available commands\&.
.RE
.PP
\-\-variant
.RS 4
Set the variant of the selected image, that was used for bootstrapping\&.
.RE
.PP
\-a|\-\-arch
.RS 4
The architecture of the base image that should be selected\&.
.RE
.PP
\-\-suite
.RS 4
Explicitly set a suite name (instead of having it derived from the container name)\&.
.RE
.PP
\-\-sign
.RS 4
Sign the resulting package\&.
.RE
.PP
\-\-only
.RS 4
Select only a specific set of packages to be built\&. Choices are:
\fBbinary\fR: Build only binary packages, no source files are to be built and/or distributed\&.
\fBarch\fR: Build only architecture\-specific binary packages\&.
\fBindep\fR: Build only architecture\-independent (arch:all) binary packages\&.
\fBsource\fR: Do a source\-only build, no binary packages are made\&.
.RE
.PP
\-\-include\-orig
.RS 4
Forces the inclusion of the original source\&.
.RE
.PP
\-\-buildflags
.RS 4
Set flags passed through to dpkg\-buildpackage as semicolon\-separated list\&.
.RE
.PP
\-\-results\-dir
.RS 4
Override the configured results directory and return artifacts at a custom location\&.
.RE
.PP
\-\-maintainer
.RS 4
Set the name and email address of the maintainer for this package and upload, rather than using the information from the source tree\*(Aqs control file or changelog\&.
.RE
.PP
\-\-clean\-source
.RS 4
Run the d/rules clean target outside of the container\&. This means the package build dependencies need to be installed on the host system when building from a source directory\&.
.RE
.PP
\-\-lintian
.RS 4
Run the Lintian static analysis tool for Debian packages after the package is built\&.
.RE
.PP
\-\-no\-buildlog
.RS 4
Do not write a build log\&.
.RE
.PP
\-i|\-\-interact
.RS 4
Run an interactive shell in the build environment after build\&. This implies `\-\-no\-buildlog` and disables the log\&.
.RE
.PP
\-e|\-\-setenv
.RS 4
Set an environment variable for the build process\&. Takes a `key=value` pair any may be defined multiple times to set different environment variables\&.
.RE
.SH "DIFFERENCES TO SBUILD"
.PP
On Debian,
\fBsbuild\fR
is the primary tool used for package building, which uses different technology\&. So naturally, the question is whether the sbuild build environments and the
\fBdebspawn\fR
build environments are be identical or at least compatible\&.
.PP
Due to the different technology used, there may be subtle differences between
\fBsbuild\fR
chroots and
\fBdebspawn\fR
containers\&. The differences should not have any impact on package builds, and any such occurrence is highly likely a bug in the package\*(Aqs build process\&. If you think it is not, please file a bug against Debspawn\&. We try to be as close to sbuild\*(Aqs default environment as possible, but unfortunately can not make any guarantees\&.
.PP
One way the build environment of
\fBdebspawn\fR
differs from Debian\*(Aqs default
\fBsbuild\fR
setup intentionally is in its consistent use of unicode\&. By default,
\fBdebspawn\fR
will ensure that unicode is always available and enabled\&. If you do not want this behavior, you can pass the
\fB\-\-no\-unicode\fR
flag to
\fBdebspawn build\fR
to disable unicode in the tool itself and in the build environment\&.
.SH "SEE ALSO"
.PP
debspawn\-update(1), debspawn\-create(1), dpkg\-buildpackage(1)\&.
.SH "AUTHOR"
.PP
This manual page was written by Matthias Klumpp
\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2018-2022 Matthias Klumpp
.br