Debian Codegraph @

docs/debspawn-build.1.xml

raw
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>