1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="empdebuild">
<refentryinfo>
<productname>empdebuild</productname>
<productnumber/>
</refentryinfo>
<refmeta>
<refentrytitle>empdebuild</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
<refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
</refmeta>
<refnamediv id="name">
<refname>empdebuild</refname>
<refpurpose>chroot tool for Emdebian cross compiling</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--testing</arg>
</group>
<group>
<arg>--login-after-fail</arg>
</group>
<group>
<arg>--build</arg>
<arg>build</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--testing</arg>
</group>
<group>
<arg>--create</arg>
<arg>create</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--testing</arg>
</group>
<group>
<arg>--save-after-login</arg>
</group>
<group>
<arg>--login</arg>
<arg>login </arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--testing</arg>
</group>
<group>
<arg>--update</arg>
<arg>update</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--login-after-fail</arg>
</group>
<group>
<arg>--autobuild</arg>
<arg>autobuild</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>empdebuild</command>
<group>
<arg>-a</arg>
<arg>--arch </arg>
<replaceable> ARCHITECTURE</replaceable>
</group>
<group>
<arg>--clean</arg>
<arg>clean</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>DESCRIPTION</title>
<para>Note that <command>empdebuild</command> does not support all the
options available to <command>pbuilder</command>.
</para>
<para><command>empdebuild</command> is an Emdebian version of pdebuild, building
Emdebian packages in a chroot using code from pbuilder. The Emdebian chroot includes the
cross-building toolchain from Emdebian for the requested architecture and includes
support for installing cross versions of package dependencies via
<command>apt-cross</command> with all the advantages of a chroot - identification of
missing dependencies and the ability to build packages without installing the dependencies
on the main system, e.g. to support a buildd.
</para>
<note>
<title>empdebuild is a build chroot</title>
<para><command>empdebuild</command> creates a chroot for the same architecture as
the system running <command>empdebuild</command> and then installs a cross-building
toolchain from Emdebian using the <command>dpkg-cross</command> default
architecture or the specified architecture. This has some important results:
</para>
<orderedlist>
<listitem>
<para>The chroot is a Debian system running <filename>emdebian-tools</filename>
and is equivalent to a typical installation of emdebian-tools
<emphasis>after</emphasis> <command>emsetup</command> has been completed
successfully. This includes installing perl and debconf inside the chroot.
</para>
</listitem>
<listitem>
<para>A suitable Emdebian toolchain will be installed in the chroot.
</para>
</listitem>
<listitem>
<para>The same cache files are needed inside the chroot as would be needed on the
main system - cross-built binaries <emphasis role="bold">cannot</emphasis> be run
within the the chroot. All the normal emdebian patch files will be needed.
</para>
</listitem>
<listitem>
<para>This is a full build system with native and cross compilers, development
packages, autotools and subversion. It is <emphasis role="bold">NOT</emphasis>
suitable for installation on any device. Use <command>emsandbox</command>
instead.
</para>
</listitem>
<listitem>
<para>The chroot disables the installation of recommended packages by
apt using the Install-Recommends "false" option.
</para>
</listitem>
</orderedlist>
</note>
<para>Use <command>emsandbox</command> to create cross chroots (where the
chroot is built for a different architecture to the system running the chroot),
e.g. to prepare a rootfs for installation on an arm device using emdebian-tools
installed on i386, amd64 etc. See <command>emsandbox</command> (1).
</para>
</refsect1>
<refsect1 id="commands">
<title>COMMANDS</title>
<variablelist remap="TP">
<varlistentry>
<term><option>--build</option>|<option>build</option></term>
<listitem>
<para>(to provide) similar functionality to pdebuild for Emdebian -
copies the source into the chroot and runs a build using
<command>emdebuild</command>.
</para>
<para>Use <option>--login-after-fail</option> to debug a failed build.
If <command>emdebuild</command> fails inside the chroot,
<command>empdebuild</command> will then open a shell at the point
of failure, allowing you to debug the build session with the active data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--create</option>|<option>create</option></term>
<listitem>
<para>Runs <command>debootstrap</command> with a modified suite rule
set to create a basic Emdebian environment, including emdebian-tools and
an Emdebian toolchain for the default or specified architecture.
</para>
<para>Checks for an existing chroot and exits if one is found - either use
<option>--update</option> or move the old chroot out of the way.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--login</option>|<option>login</option></term>
<listitem>
<para>Login to the chroot. Unless <option>--save-after-login</option> is used,
changes made within the chroot will be lost.
</para>
<para>When setting up any chroot, debconf is set to use the default values
and this leads to <command>dpkg-cross</command> being set to
<userinput>None</userinput> as the default cross building architecture.
When logged into the chroot, always specify the <option>--arch</option>
option to <command>apt-cross</command> and all
<emphasis>emdebian-tools</emphasis> scripts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--update</option>|<option>update</option></term>
<listitem>
<para>Updates the Emdebian environment, including emdebian-tools and
an Emdebian toolchain for the default or specified architecture. Depending on
the status of gcc-?.? in Debian, there can be problems updating the cross
building toolchain at this stage. If you get reports of broken packages
or toolchain packages that fail to install, allow the update to continue as
normal, then login to the chroot with the <option>--save-after-login</option>
option. If the problem relates to a package named <filename>$PACKAGE-$ARCH-cross</filename>
not <filename>$PACKAGE-$ARCHTYPE</filename> ($ARCHTYPE for arm = arm-linux-gnu), this
package is handled by <command>dpkg-cross</command> and <command>apt-cross</command>.
Use <command>apt-cross -a $ARCH -v -i $PACKAGE</command> (omit the -$ARCH-cross suffix)
to update such packages ahead of the Emdebian repository. Use
<command>apt-get dist-upgrade</command> and <command>emsetup -a $ARCH --yes</command>
to complete the upgrade. Type 'exit' or use 'Ctrl-D' to exit from the chroot and
the updated packages will be saved alongside the updated chroot.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--clean</option>|<option>clean</option></term>
<listitem>
<para>Uses pbuilder functions to clean the chroot build place,
removing any previous build environments. In some situations, a stale
build environment may still contain active mounts for
<computeroutput>proc</computeroutput> or <computeroutput>dev/pts</computeroutput>
and these will result in <emphasis>Device or resource busy</emphasis> errors.
To umount the relevant points, look for your Emdebian working directory being
listed in the output of <computeroutput>mount</computeroutput> and pass that
directory name to:
<programlisting>
$ sudo umount PATH
</programlisting>
Once umounted, either remove the files manually or run <command>sudo empdebuild</command>
<option>--clean</option> again.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="options">
<title>OPTIONS</title>
<variablelist remap="TP">
<varlistentry>
<term><option>-a</option>|<option>--arch</option><replaceable> ARCHITECTURE</replaceable></term>
<listitem>
<para>Override the <command>dpkg-cross</command> default architecture
for this operation on the chroot. The Emdebian toolchain in the chroot
will be upgraded (or installed if the chroot contains a toolchain for a
different architecture).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--testing</option>
</term>
<listitem>
<para>Create, update, login or build a package within a chroot based on
Debian testing, not Debian unstable. This is a fallback option for the times
when Debian unstable transitions make it impossible to install a cross-building
toolchain or update the existing toolchain.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--save-after-login</option>
</term>
<listitem>
<para>Login to the chroot and allow changes made within the chroot to persist
into subsequent sessions. Only supported in conjunction with
<option>login</option>|<option>--login</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--login-after-fail</option>
</term>
<listitem>
<para>Login to the chroot if <command>emdebuild</command> fails
within the chroot, at the point where the build failed. Chroot cross builds
can involve a protracted setup phase which can be hard to replicate
outside the chroot. Use this option to find out why a chroot build failed
when a normal build succeeded. Only supported in conjunction with
<option>build</option>|<option>--build</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>|<option>--help</option></term>
<listitem>
<para>print the usage message and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--version</option>
</term>
<listitem>
<para>print the usage message and exit.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Author</title>
<para><command>empdebuild</command> was written
by Neil Williams <email>codehelp@debian.org</email>.
</para>
<para>This manual page was written by Neil Williams
<email>codehelp@debian.org</email>
</para>
</refsect1>
<refsect1 id="seealso">
<title>SEE ALSO</title>
<para>See also <filename>apt-cross</filename> (1), <filename>em_make</filename> (1),
<filename>dpkg-cross</filename> (1), <emphasis>emdebian-tools</emphasis> (1),
<filename>emsandbox</filename> (1).
</para>
</refsect1>
</refentry>
|
