| 1 |
<?xml version='1.0' encoding='ISO-8859-1'?> |
| 2 |
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| 4 |
|
| 5 |
<!ENTITY date "<date>18 August, 2018</date>"> |
| 6 |
|
| 7 |
<!ENTITY pagename "debspawn-build"> |
| 8 |
<!ENTITY command "debspawn build"> |
| 9 |
]> |
| 10 |
|
| 11 |
<refentry> |
| 12 |
<refentryinfo> |
| 13 |
<title>&command;</title> |
| 14 |
<copyright> |
| 15 |
<year>2018-2022</year> |
| 16 |
<holder>Matthias Klumpp</holder> |
| 17 |
</copyright> |
| 18 |
<productname>Debspawn</productname> |
| 19 |
&date; |
| 20 |
</refentryinfo> |
| 21 |
|
| 22 |
<refmeta> |
| 23 |
<refentrytitle>&pagename;</refentrytitle> |
| 24 |
<manvolnum>1</manvolnum> |
| 25 |
</refmeta> |
| 26 |
<refnamediv> |
| 27 |
<refname>&pagename;</refname> |
| 28 |
<refpurpose>Build Debian packages in a container</refpurpose> |
| 29 |
</refnamediv> |
| 30 |
|
| 31 |
<refsynopsisdiv> |
| 32 |
<cmdsynopsis> |
| 33 |
<command>&command;</command> |
| 34 |
@BUILD_FLAGS_SYNOPSIS@ |
| 35 |
<arg choice="req">SUITE</arg> |
| 36 |
<arg>DIR|DSC_FILE</arg> |
| 37 |
</cmdsynopsis> |
| 38 |
</refsynopsisdiv> |
| 39 |
|
| 40 |
<refsect1> |
| 41 |
<title>Description</title> |
| 42 |
<para> |
| 43 |
Build a Debian package from a directory or source package <filename>*.dsc</filename> file. |
| 44 |
<command>debspawn</command> will create a new container for the respective build using the base image specified, |
| 45 |
build the package and return build artifacts in the default output directory <filename>/var/lib/debspawn/results/</filename> unless |
| 46 |
a different location was specified via the <option>--results-dir</option> flag. |
| 47 |
</para> |
| 48 |
<para> |
| 49 |
Downloaded packages that are build dependencies are cached and will be reused on subsequent builds if possible. |
| 50 |
</para> |
| 51 |
<para> |
| 52 |
You can inject packages into the build environment that are not available in the preconfigured APT repositories by |
| 53 |
placing them in <filename>/var/lib/debspawn/injected-pkgs/${container-name}</filename>, or in |
| 54 |
<filename>/var/lib/debspawn/injected-pkgs/</filename> to make a package available in all environments. |
| 55 |
Internally, <command>debspawn</command> will build a transient package repository with the respective packages and |
| 56 |
add it as a package source for APT. |
| 57 |
</para> |
| 58 |
<para> |
| 59 |
If you want to debug the package build process, you can pass the <option>--interact</option> flag to <command>debspawn</command>. This |
| 60 |
will open an interactive root shell in the build environment post-build, no matter whether the build failed or succeeded. |
| 61 |
After investigating the issue / building the package manually, the shell can be exited and the user is asked whether <command>debspawn</command> |
| 62 |
should copy back the changes made in the packages' <filename>debian/</filename> directory to the host to make them permanent. |
| 63 |
Please keep in mind that while interactive mode is enabled, no build log can be created. |
| 64 |
</para> |
| 65 |
<para> |
| 66 |
By default, network access is disabled during the untrusted package build step. |
| 67 |
You can explicitly opt into network access with <option>--allow-network</option> if your build workflow requires it. |
| 68 |
</para> |
| 69 |
</refsect1> |
| 70 |
|
| 71 |
<refsect1> |
| 72 |
<title>Examples</title> |
| 73 |
<para> |
| 74 |
You can build a package from its source directory, or just by passing a plain <filename>.dsc</filename> file to <command>&command;</command>. |
| 75 |
If the result should be automatically signed, the <option>--sign</option> flag needs to be passed too: |
| 76 |
</para> |
| 77 |
<screen> |
| 78 |
<prompt>$</prompt> <command>cd</command> ~/packages/hello |
| 79 |
<prompt>$</prompt> <command>&command;</command> sid --sign |
| 80 |
|
| 81 |
<prompt>$</prompt> <command>&command;</command> --arch=i386 cosmic ./hello_2.10-1.dsc |
| 82 |
</screen> |
| 83 |
<para> |
| 84 |
You can also build packages using <command>git-buildpackage</command> and <command>debspawn</command>. In this case the <option>--lintian</option> |
| 85 |
flag is also used to perform a Lintian static analysis check in the container after build: |
| 86 |
</para> |
| 87 |
<screen> |
| 88 |
<prompt>$</prompt> <command>gbp buildpackage</command> --git-builder='debspawn b sid --lintian --sign' |
| 89 |
</screen> |
| 90 |
<para> |
| 91 |
To debug a build issue interactively, the <option>--interact</option> flag can be used: |
| 92 |
</para> |
| 93 |
<screen> |
| 94 |
<prompt>$</prompt> <command>&command;</command> sid --interact |
| 95 |
</screen> |
| 96 |
</refsect1> |
| 97 |
|
| 98 |
<refsect1> |
| 99 |
<title>Options</title> |
| 100 |
|
| 101 |
<variablelist> |
| 102 |
@BUILD_FLAGS_ENTRIES@ |
| 103 |
</variablelist> |
| 104 |
</refsect1> |
| 105 |
|
| 106 |
<refsect1> |
| 107 |
<title>Differences to sbuild</title> |
| 108 |
<para> |
| 109 |
On Debian, <command>sbuild</command> is the primary tool used for package building, which uses different technology. |
| 110 |
So naturally, the question is whether the sbuild build environments and the <command>debspawn</command> build environments |
| 111 |
are be identical or at least compatible. |
| 112 |
</para> |
| 113 |
<para> |
| 114 |
Due to the different technology used, there may be subtle differences between <command>sbuild</command> chroots and |
| 115 |
<command>debspawn</command> containers. The differences should not have any impact on package builds, and any such occurrence is |
| 116 |
highly likely a bug in the package's build process. |
| 117 |
If you think it is not, please file a bug against Debspawn. We try to be as close to sbuild's default environment as possible, but |
| 118 |
unfortunately can not make any guarantees. |
| 119 |
</para> |
| 120 |
<para> |
| 121 |
One way the build environment of <command>debspawn</command> differs from Debian's default <command>sbuild</command> setup intentionally is |
| 122 |
in its consistent use of unicode. By default, <command>debspawn</command> will ensure that unicode is always available and enabled. |
| 123 |
If you do not want this behavior, you can pass the <option>--no-unicode</option> flag to <command>&command;</command> to disable unicode in |
| 124 |
the tool itself and in the build environment. |
| 125 |
</para> |
| 126 |
</refsect1> |
| 127 |
|
| 128 |
<refsect1> |
| 129 |
<title>See Also</title> |
| 130 |
<para>debspawn-update(1), debspawn-create(1), dpkg-buildpackage(1).</para> |
| 131 |
</refsect1> |
| 132 |
<refsect1> |
| 133 |
<title>AUTHOR</title> |
| 134 |
<para> |
| 135 |
This manual page was written by Matthias Klumpp <email>[email protected]</email>. |
| 136 |
</para> |
| 137 |
</refsect1> |
| 138 |
</refentry> |