~ubuntu-branches/debian/sid/pbuilder/sid : revision 37

1

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>pbuilder User's Manual</title><link rel="stylesheet" type="text/css" href="pbuilder-doc.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="pbuilder User's Manual"><div class="titlepage"><div><div><h1 class="title"><a name="idp52041696"></a>pbuilder User's Manual</h1></div><div><h2 class="subtitle">Usage and operations</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Junichi</span> <span class="surname">Uekawa</span></h3></div></div></div><div><p class="releaseinfo">documentation in progress</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#introduction">1. Introducing pbuilder</a></span></dt><dd><dl><dt><span class="sect1"><a href="#aim">1. Aims of pbuilder</a></span></dt></dl></dd><dt><span class="chapter"><a href="#usingpbuilder">2. Using pbuilder</a></span></dt><dd><dl><dt><span class="sect1"><a href="#creatingbase">1. Creating a base chroot image tar-ball</a></span></dt><dt><span class="sect1"><a href="#basechroot">2. Updating the base.tgz</a></span></dt><dt><span class="sect1"><a href="#buildpackagechroot">3. Building a package using the base.tgz</a></span></dt><dt><span class="sect1"><a href="#pdebuild">4. Facilitating Debian Developers' typing, pdebuild</a></span></dt><dt><span class="sect1"><a href="#configfile">5. Configuration Files</a></span></dt><dt><span class="sect1"><a href="#nonrootchroot">6. Building packages as non-root inside the chroot</a></span></dt><dt><span class="sect1"><a href="#backporting">7. Using pbuilder for back-porting</a></span></dt><dt><span class="sect1"><a href="#massbuild">8. Mass-building packages</a></span></dt><dt><span class="sect1"><a href="#autobackport">9. Auto-backporting scripts</a></span></dt><dt><span class="sect1"><a href="#autotesting">10. Using pbuilder for automated testing of packages</a></span></dt><dt><span class="sect1"><a href="#altcompiler">11. Using pbuilder for testing builds with alternate compilers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#pbuilder-uml">3. Using User-mode-linux with pbuilder</a></span></dt><dd><dl><dt><span class="sect1"><a href="#user-mode-linux-config">1. Configuring user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#rootstrap">2. Configuring rootstrap</a></span></dt><dt><span class="sect1"><a href="#pbuilderumlconfig">3. Configuring pbuilder-uml</a></span></dt><dt><span class="sect1"><a href="#consideruml">4. Considerations for running pbuilder-user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#paralleluml">5. Parallel running of pbuilder-user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#pbuilderumlwrap">6. Using pbuilder-user-mode-linux as a wrapper script to start up a virtual machine</a></span></dt></dl></dd><dt><span class="chapter"><a href="#faq">4. Frequently asked questions </a></span></dt><dd><dl><dt><span class="sect1"><a href="#pbuildercreatefail">1. pbuilder create fails</a></span></dt><dt><span class="sect1"><a href="#bindmountlimits">2. Directories that cannot be bind-mounted</a></span></dt><dt><span class="sect1"><a href="#shellafterfail">3. Logging in to pbuilder to investigate build failure</a></span></dt><dt><span class="sect1"><a href="#modifyupdate">4. Logging in to pbuilder to modify the environment</a></span></dt><dt><span class="sect1"><a href="#BUILDRESULTUID">5. Setting BUILDRESULTUID for sudo sessions</a></span></dt><dt><span class="sect1"><a href="#tmpdir">6. Notes on usage of $TMPDIR</a></span></dt><dt><span class="sect1"><a href="#DISTRIBUTIONSWITCH">7. Creating a shortcut for running <span class="command"><strong>pbuilder</strong></span> with a specific distribution</a></span></dt><dt><span class="sect1"><a href="#ENVVARDISTRIBUTIONSWITCH">8. Using environmental variables for running <span class="command"><strong>pbuilder</strong></span>

2

for specific distribution

3

</a></span></dt><dt><span class="sect1"><a href="#usingspecialaptsources">9. Using special apt sources lists, and local packages</a></span></dt><dt><span class="sect1"><a href="#apt-getupdateonbuild-depend">10. How to get pbuilder to run apt-get update before trying to satisfy build-dependency</a></span></dt><dt><span class="sect1"><a href="#bashprompt">11. Different bash prompts inside pbuilder login</a></span></dt><dt><span class="sect1"><a href="#chrootmemo">12. Creating a chroot reminder</a></span></dt><dt><span class="sect1"><a href="#packagecachearchives">13. Using /var/cache/apt/archives for the package cache</a></span></dt><dt><span class="sect1"><a href="#stablebackport">14. pbuilder back ported to stable Debian releases</a></span></dt><dt><span class="sect1"><a href="#LOGNAME">15. Warning about LOGNAME not being defined</a></span></dt><dt><span class="sect1"><a href="#nobuildconflictessential">16. Cannot Build-conflict against an essential package</a></span></dt><dt><span class="sect1"><a href="#lninvalidcrossdevicelink">17. Avoiding the "ln: Invalid cross-device link" message</a></span></dt><dt><span class="sect1"><a href="#fakechroot">18. Using fakechroot</a></span></dt><dt><span class="sect1"><a href="#debconfinsidepbuilder">19. Using debconf inside pbuilder sessions</a></span></dt><dt><span class="sect1"><a href="#nodev">20. nodev mount options hinder pbuilder activity</a></span></dt><dt><span class="sect1"><a href="#faqslowpbuilder">21. pbuilder is slow</a></span></dt><dt><span class="sect1"><a href="#sponsor">22. Using pdebuild to sponsor package</a></span></dt><dt><span class="sect1"><a href="#sourcechanges">23. Why is there a source.changes file in ../?</a></span></dt><dt><span class="sect1"><a href="#amd64i386">24. amd64 and i386-mode</a></span></dt><dt><span class="sect1"><a href="#tmpfsforpbuilder">25. Using tmpfs for buildplace</a></span></dt><dt><span class="sect1"><a href="#idp57743216">26. Using svn-buildpackage together with pbuilder</a></span></dt></dl></dd><dt><span class="chapter"><a href="#develanddebug">5. Troubleshooting and development</a></span></dt><dd><dl><dt><span class="sect1"><a href="#bugreport">1. Reporting bugs </a></span></dt><dt><span class="sect1"><a href="#mailinglist">2. Mailing list</a></span></dt><dt><span class="sect1"><a href="#IRCchannel">3. IRC Channel</a></span></dt><dt><span class="sect1"><a href="#development">4. Information for pbuilder developers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#otheruse">6. Other uses of pbuilder</a></span></dt><dd><dl><dt><span class="sect1"><a href="#chroot">1. Using pbuilder for small experiments</a></span></dt><dt><span class="sect1"><a href="#runningprograms">2. Running little programs inside the chroot</a></span></dt></dl></dd><dt><span class="chapter"><a href="#experimental">7. Experimental or wishlist features of pbuilder</a></span></dt><dd><dl><dt><span class="sect1"><a href="#lvm">1. Using LVM</a></span></dt><dt><span class="sect1"><a href="#cowdancer">2. Using cowdancer</a></span></dt><dt><span class="sect1"><a href="#withouttargz">3. Using pbuilder without tar.gz</a></span></dt><dt><span class="sect1"><a href="#inavserver">4. Using pbuilder in a vserver</a></span></dt><dt><span class="sect1"><a href="#ccache">5. Usage of ccache</a></span></dt></dl></dd><dt><span class="chapter"><a href="#refs">8. Reference materials</a></span></dt><dd><dl><dt><span class="sect1"><a href="#dirstructoutside">1. Directory structure outside the chroot</a></span></dt><dt><span class="sect1"><a href="#dirstructinside">2. Directory structure inside the chroot</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp57886192">9. Minor archaeological details</a></span></dt><dd><dl><dt><span class="sect1"><a href="#idp57886832">1. Documentation history </a></span></dt><dt><span class="sect1"><a href="#pbuilderbackgroundhistory">2. Possibly inaccurate Background History of pbuilder</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp57896896">2.1. The Time Before pbuilder</a></span></dt><dt><span class="sect2"><a href="#birth">2.2. Birth of pbuilder</a></span></dt><dt><span class="sect2"><a href="#secondyear">2.3. And the second year of its life</a></span></dt><dt><span class="sect2"><a href="#fifthyear">2.4. Fifth year of pbuilder</a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>5.1. <a href="#dirtestsuites">Directory structure of the testsuite</a></dt><dt>8.1. <a href="#idp57833296">Directory Structure outside the chroot </a></dt><dt>8.2. <a href="#idp57863936">Directory Structure inside the chroot </a></dt></dl></div><div class="chapter" title="Chapter�1.�Introducing pbuilder"><div class="titlepage"><div><div><h2 class="title"><a name="introduction"></a>Chapter�1.�Introducing pbuilder</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#aim">1. Aims of pbuilder</a></span></dt></dl></div><div class="sect1" title="1.�Aims of pbuilder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aim"></a>1.�Aims of pbuilder</h2></div></div></div><p>

4

<span class="command"><strong>pbuilder</strong></span> stands for

5

Personal Builder, and it is an automatic Debian Package Building system

6

for personal development workstation environments.

7

<span class="command"><strong>pbuilder</strong></span> aims to be an

8

easy-to-setup system

9

for auto-building Debian packages inside a clean-room

10

environment, so that it is possible to verify that

11

a package can be built on most Debian installations.

12

The clean-room environment is achieved through the use of

13

a base chroot image,

14

so that only minimal packages will be installed inside the

15

chroot.

16

</p><p>

17

The Debian distribution consists of free software

18

accompanied with source.

19

The source code within Debian's "main" section

20

must build within Debian "main",

21

with only the explicitly specified build-dependencies

22

installed.

23

</p><p>

24

The primary aim of <span class="command"><strong>pbuilder</strong></span> is different from other

25

auto-building systems in Debian in that its aim is not

26

to try to build as many packages as possible.

27

It does not try to guess

28

what a package needs, and in most cases it tries the

29

worst choice of all if there is a choice to be made.

30

</p><p>

31

In this way, <span class="command"><strong>pbuilder</strong></span> tries to ensure

32

that packages

33

tested against <span class="command"><strong>pbuilder</strong></span> will build properly in

34

most Debian installations, hopefully resulting

35

in a good overall Debian source-buildability.

36

</p><p>

37

The goal of making Debian buildable from source is somewhat

38

accomplished, and has seen good progress. In the past age of

39

Debian 3.0, there were many problems when building from

40

source. More recent versions of Debian is much better.

41

</p></div></div><div class="chapter" title="Chapter�2.�Using pbuilder"><div class="titlepage"><div><div><h2 class="title"><a name="usingpbuilder"></a>Chapter�2.�Using pbuilder</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#creatingbase">1. Creating a base chroot image tar-ball</a></span></dt><dt><span class="sect1"><a href="#basechroot">2. Updating the base.tgz</a></span></dt><dt><span class="sect1"><a href="#buildpackagechroot">3. Building a package using the base.tgz</a></span></dt><dt><span class="sect1"><a href="#pdebuild">4. Facilitating Debian Developers' typing, pdebuild</a></span></dt><dt><span class="sect1"><a href="#configfile">5. Configuration Files</a></span></dt><dt><span class="sect1"><a href="#nonrootchroot">6. Building packages as non-root inside the chroot</a></span></dt><dt><span class="sect1"><a href="#backporting">7. Using pbuilder for back-porting</a></span></dt><dt><span class="sect1"><a href="#massbuild">8. Mass-building packages</a></span></dt><dt><span class="sect1"><a href="#autobackport">9. Auto-backporting scripts</a></span></dt><dt><span class="sect1"><a href="#autotesting">10. Using pbuilder for automated testing of packages</a></span></dt><dt><span class="sect1"><a href="#altcompiler">11. Using pbuilder for testing builds with alternate compilers</a></span></dt></dl></div><p>

42

There are several simple commands for operation.

43

<span class="command"><strong>pbuilder create</strong></span>, <span class="command"><strong>pbuilder

44

update</strong></span>, and <span class="command"><strong>pbuilder build</strong></span> commands

45

are the typical commands used. Let us look at the commands

46

one by one.

47

</p><div class="sect1" title="1.�Creating a base chroot image tar-ball"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creatingbase"></a>1.�Creating a base chroot image tar-ball</h2></div></div></div><p>

48

<span class="command"><strong>pbuilder create</strong></span>

49

will create a base chroot image tar-ball (base.tgz).

50

All other commands will operate on the resulting base.tgz

51

52

If the Debian release to be created within chroot is not going

53

to be "sid" (which is the default), the distribution code-name

54

needs to be specified with the

55

<span class="command"><strong><code class="option">--distribution</code></strong></span>

56

command-line option.

57

</p><p>

58

<span class="command"><strong>debootstrap</strong></span> <sup>[<a name="idp52238768" href="#ftn.idp52238768" class="footnote">1</a>]</sup>

59

is used to create

60

the bare minimum Debian installation,

61

and then build-essential packages are installed on top

62

of the minimum installation using <span class="command"><strong>apt-get</strong></span>

63

inside the chroot.

64

</p><p>

65

For fuller documentation of command-line options, see

66

the pbuilder.8 manual page.

67

Some configuration will be required for <code class="filename">/etc/pbuilderrc</code>

68

for the mirror site

69

70

to use, and proxy configuration may be required to allow access

71

through HTTP.

72

See the pbuilderrc.5 manual page for details.

73

</p></div><div class="sect1" title="2.�Updating the base.tgz"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="basechroot"></a>2.�Updating the base.tgz</h2></div></div></div><p><span class="command"><strong>pbuilder update</strong></span>

74

will update the base.tgz.

75

It will extract the chroot, invoke <span class="command"><strong>apt-get update</strong></span>

76

and <span class="command"><strong>apt-get dist-upgrade</strong></span> inside the

77

chroot, and then recreate the base.tgz (the base tar-ball).

78

</p><p>

79

It is possible to switch the distribution which the

80

base.tgz is targeted at at this point.

81

Specify <span class="command"><strong><code class="option">--distribution <em class="parameter"><code>sid</code></em></code> <code class="option">--override-config</code></strong></span> to change the distribution

82

to sid.

83

84

</p><p>

85

For fuller documentation of command-line options, see

86

the pbuilder.8 manual page

87

</p></div><div class="sect1" title="3.�Building a package using the base.tgz"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="buildpackagechroot"></a>3.�Building a package using the base.tgz</h2></div></div></div><p>

88

To build a package inside the chroot, invoke

89

<span class="command"><strong>pbuilder build <code class="option">whatever.dsc</code></strong></span>.

90

<span class="command"><strong>pbuilder</strong></span> will extract

91

the base.tgz to a temporary working directory,

92

enter the directory with chroot,

93

satisfy the build-dependencies inside chroot,

94

and build the package.

95

The built packages will be moved to a

96

directory specified with

97

the <span class="command"><strong><code class="option">--buildresult</code></strong></span>

98

command-line option.

99

</p><p>

100

The <span class="command"><strong><code class="option">--basetgz</code></strong></span> option can be

101

used to specify which base.tgz to use.

102

</p><p>

103

<span class="command"><strong>pbuilder</strong></span> will extract a fresh base chroot

104

image from base.tgz. (base.tgz is created with

105

<span class="command"><strong>pbuilder create</strong></span>, and updated with

106

<span class="command"><strong>pbuilder update</strong></span>). The chroot is populated

107

with build-dependencies by parsing debian/control and invoking

108

<span class="command"><strong>apt-get</strong></span>.

109

</p><p>

110

For fuller documentation of command-line options, see

111

the pbuilder.8 manual page

112

</p></div><div class="sect1" title="4.�Facilitating Debian Developers' typing, pdebuild"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pdebuild"></a>4.�Facilitating Debian Developers' typing, pdebuild</h2></div></div></div><p>

113

<span class="command"><strong>pdebuild</strong></span> is a little wrapper

114

script that does the most frequent of all tasks.

115

A Debian Developer may try to do <span class="command"><strong>debuild</strong></span>, and

116

build a package, inside a Debian source directory.

117

<span class="command"><strong>pdebuild</strong></span> will allow similar

118

control, and allow package to be built inside the chroot,

119

to check that the current source tree will build happily

120

inside the chroot.

121

</p><p>

122

<span class="command"><strong>pdebuild</strong></span> calls <span class="command"><strong>dpkg-source</strong></span>

123

to build the source packages, and then invokes

124

<span class="command"><strong>pbuilder</strong></span> on the resulting source package.

125

However, unlike debuild, the resulting deb files will be

126

found in the <span class="command"><strong><code class="option">--buildresult</code></strong></span>

127

directory.

128

</p><p>

129

See the pdebuild.1 manual page for more details.

130

</p><p>

131

There is a slightly different mode of operation available

132

in <span class="command"><strong>pdebuild</strong></span> since version 0.97. <span class="command"><strong>pdebuild</strong></span> usually runs

133

<span class="command"><strong>debian/rules clean</strong></span> outside of the chroot;

134

however, it is possible to change the behavior to run it

135

inside the chroot with

136

the <span class="command"><strong><code class="option">--use-pdebuild-internal</code></strong></span>.

137

It will try to bind mount the working directory inside chroot,

138

and run <span class="command"><strong>dpkg-buildpackage</strong></span> inside.

139

It has the following characteristics, and is not yet the

140

default mode of operation.

141

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

142

Satisfies build-dependency inside the chroot before creating source package.

143

(which is a good point that default <span class="command"><strong>pdebuild</strong></span> could not do).

144

</p></li><li class="listitem"><p>The working directory is modified

145

from inside the chroot.</p></li><li class="listitem"><p>Building with <span class="command"><strong>pdebuild</strong></span> does not guarantee

146

that it works with <span class="command"><strong>pbuilder</strong></span>.</p></li><li class="listitem"><p>If making the source package fails,

147

the session using the chroot is wasted

148

(chroot creation takes a bit of time, which should be improved with cowdancer).</p></li><li class="listitem"><p>Does not work in the same manner as it used to;

149

for example, <span class="command"><strong><code class="option">--buildresult</code></strong></span>

150

does not have any effect.</p></li><li class="listitem"><p>The build inside chroot is ran with the current user outside chroot.

151

</p></li></ul></div></div><div class="sect1" title="5.�Configuration Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configfile"></a>5.�Configuration Files</h2></div></div></div><p>

152

It is possible to specify all settings by command-line

153

options. However, for typing convenience, it is possible to

154

use a configuration file.

155

</p><p>

156

<code class="filename">/etc/pbuilderrc</code> and

157

<code class="filename">${HOME}/.pbuilderrc</code>

158

are read in when <span class="command"><strong>pbuilder</strong></span> is invoked.

159

The possible options are documented in

160

the pbuilderrc.5 manual page.

161

</p><p>

162

It is useful to use <code class="option">--configfile</code> option to load up a preset

163

configuration file when switching between configuration files for

164

different distributions.

165

</p><p>

166

Please note <code class="filename">${HOME}/.pbuilderrc</code> supersede

167

system settings. Caveats is that if you have some

168

configuration, you may need to tweak the configuration to work

169

with new versions of pbuilder when upgrading.

170

</p></div><div class="sect1" title="6.�Building packages as non-root inside the chroot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nonrootchroot"></a>6.�Building packages as non-root inside the chroot</h2></div></div></div><p>

171

<span class="command"><strong>pbuilder</strong></span> requires full root privilege

172

when it is satisfying the build-dependencies, but most packages do not

173

need root privilege to build, or even refused to build when they are built as root.

174

<span class="command"><strong>pbuilder</strong></span> can create a user which is only used

175

inside <span class="command"><strong>pbuilder</strong></span> and use that user id when

176

building, and use the <span class="command"><strong>fakeroot</strong></span> command

177

when root privilege is required.

178

</p><p>

179

BUILDUSERID configuration option should be set to a value for a user id that

180

does not already exist on the system, so that it is more difficult for

181

packages that are being built with

182

<span class="command"><strong>pbuilder</strong></span> to affect the environment outside the chroot.

183

When BUILDUSERNAME configuration option is also set,

184

<span class="command"><strong>pbuilder</strong></span> will use the specified user name and fakeroot for building packages,

185

instead of running as root inside chroot.

186

</p><p>

187

Even when using the fakerooting method, <span class="command"><strong>pbuilder</strong></span> will run with

188

root privilege when it is required.

189

For example, when installing

190

packages to the chroot, <span class="command"><strong>pbuilder</strong></span> will run under root privilege.

191

</p><p>

192

To be able to invoke <span class="command"><strong>pbuilder</strong></span> without being

193

root, you need to use user-mode-linux, as explained

194

in <a class="xref" href="#pbuilder-uml" title="Chapter�3.�Using User-mode-linux with pbuilder">Chapter�3, <i>Using User-mode-linux with pbuilder</i></a>.

195

</p></div><div class="sect1" title="7.�Using pbuilder for back-porting"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backporting"></a>7.�Using pbuilder for back-porting</h2></div></div></div><p>

196

<span class="command"><strong>pbuilder</strong></span> can be used for back-porting software from

197

the latest Debian distribution to

198

the older stable distribution, by using a chroot that contains

199

an image of the older distribution, and building packages inside the

200

chroot.

201

There are several points to consider, and due to the following reasons,

202

automatic back-porting is usually not possible, and

203

manual interaction is required:

204

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The package from the unstable distribution

205

may depend on packages or versions of packages which

206

are only available in unstable.

207

Thus, it may not be possible to satisfy Build-Depends:

208

on stable (without additional backporting work).</p></li><li class="listitem"><p>The stable distribution may have bugs that have been

209

fixed in unstable which need to be worked around.</p></li><li class="listitem"><p>The package in the unstable distribution may have

210

problems building even on unstable.</p></li></ul></div></div><div class="sect1" title="8.�Mass-building packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="massbuild"></a>8.�Mass-building packages</h2></div></div></div><p>

211

<span class="command"><strong>pbuilder</strong></span> can be automated, because its operations are

212

non-interactive.

213

It is possible to run <span class="command"><strong>pbuilder</strong></span> through multiple packages

214

non-interactively.

215

Several such scripts are known to exist.

216

Junichi Uekawa has been running such a script since 2001,

217

and has been filing bugs on packages that fail the

218

test of <span class="command"><strong>pbuilder</strong></span>. There were several problems with auto-building:

219

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Build-Dependencies need to install non-interactively, but

220

some packages are so broken that they cannot install

221

without interaction (like postgresql).</p></li><li class="listitem"><p>When a library package breaks, or gcc/gcj/g++ breaks,

222

or even bison, a large number of build failures are reported.

223

(gcj-3.0 which had no "javac", bison which got more strict, etc.)

224

</p></li><li class="listitem"><p>Some people were quite hostile against build failure reports.</p></li></ul></div><p>

225

Most of the initial bugs have been resolved in the <span class="command"><strong>pbuilder</strong></span>

226

sweep done around 2002, but these transitional problems which

227

affect a large portion of Debian Archive do arise from time to

228

time. Regression tests have their values.

229

</p><p>

230

A script that was used by Junichi Uekawa in the initial run is now included in

231

the <span class="command"><strong>pbuilder</strong></span> distribution, as <span class="command"><strong>pbuildd.sh</strong></span>.

232

It is available in <code class="filename">/usr/share/doc/pbuilder/examples/pbuildd/</code>

233

and its configuration is in <code class="filename">/etc/pbuilder/pbuildd-config.sh</code>.

234

It should be easy enough to set up for people who are used to

235

<span class="command"><strong>pbuilder</strong></span>. It has been running for quite a while, and it should be

236

possible to set the application up on your system also.

237

This version of the code is not the most tested, but should function as a starter.

238

</p><p>

239

To set up pbuildd, there are some points to be aware of.

240

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A file <code class="filename">./avoidlist</code> needs to be available with the list of packages to avoid building. </p></li><li class="listitem"><p>It will try building anything, even packages

241

which are not aimed for your architecture.</p></li><li class="listitem"><p>Because you are running random build scripts, it is better to use

242

the fakeroot option of <span class="command"><strong>pbuilder</strong></span>, to avoid running the build

243

under root privilege.</p></li><li class="listitem"><p>Because not all builds are guaranteed to finish in a finite time,

244

setting a timeout is probably necessary, or pbuildd may stall with

245

a bad build.</p></li><li class="listitem"><p>

246

Some packages require a lot of disk space,

247

around 2GB seems to be sufficient for the largest packages for the time being.

248

If you find otherwise, please inform the maintainer of this documentation.

249

</p></li></ul></div></div><div class="sect1" title="9.�Auto-backporting scripts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="autobackport"></a>9.�Auto-backporting scripts</h2></div></div></div><p>

250

There are some people who use <span class="command"><strong>pbuilder</strong></span> to automatically back-port

251

a subset of packages to the stable distribution.

252

</p><p>

253

I would like some information on how people are doing it,

254

I would appreciate any feedback or information on

255

how you are doing, or any examples.

256

</p></div><div class="sect1" title="10.�Using pbuilder for automated testing of packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="autotesting"></a>10.�Using pbuilder for automated testing of packages</h2></div></div></div><p>

257

<span class="command"><strong>pbuilder</strong></span> can be used for automated testing of packages.

258

It has the feature of allowing hooks to be placed,

259

and these hooks can try to install packages inside

260

the chroot, or run them, or whatever else that

261

can be done. Some known tests and ideas:

262

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Automatic install-remove-install-purge-upgrade-remove-upgrade-purge test-suite (distributed as an example, <code class="filename">B91dpkg-i</code>),

263

or just check that everything installs somewhat (<code class="filename">execute_installtest.sh</code>).</p></li><li class="listitem"><p>Automatically running lintian (distributed as an example in

264

<code class="filename">/usr/share/doc/pbuilder/examples/B90lintian</code>).</p></li><li class="listitem"><p>Automatic debian-test of the package?

265

The debian-test package has been removed from Debian.

266

A <span class="command"><strong>pbuilder</strong></span> implementation can be found as

267

debian/pbuilder-test directory, implemented through B92test-pkg script.</p></li></ul></div><p>

268

To use B92test-pkg script, first, add it to your hook directory.

269

<sup>[<a name="idp57538608" href="#ftn.idp57538608" class="footnote">4</a>]</sup>.

270

The test files are shell scripts

271

placed in

272

<code class="filename">debian/pbuilder-test/NN_name</code> (where

273

NN is a number) following run-parts standard<sup>[<a name="idp57540576" href="#ftn.idp57540576" class="footnote">5</a>]</sup>

274

for file names. After a successful build, packages are first

275

tested for installation and removal, and then each test is ran

276

inside the chroot. The current directory is the top directory

277

of the source-code. This means you can expect to be able to

278

use ./debian/ directory from inside your scripts.

279

</p><p>

280

Example scripts for use with pbuilder-test can be found in

281

<code class="filename">/usr/share/doc/pbuilder/examples/pbuilder-test</code>.

282

</p></div><div class="sect1" title="11.�Using pbuilder for testing builds with alternate compilers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="altcompiler"></a>11.�Using pbuilder for testing builds with alternate compilers</h2></div></div></div><p>

283

Most packages are compiled with <span class="command"><strong>gcc</strong></span>

284

or <span class="command"><strong>g++</strong></span>

285

and using the default compiler version, which was gcc 2.95 for Debian GNU/Linux 3.0 (i386).

286

However, Debian 3.0 was distributed with other compilers, under package names

287

such as <span class="command"><strong>gcc-3.2</strong></span> for gcc compiler

288

version 3.2.

289

It was therefore possible to try compiling packages against different

290

compiler versions.

291

<span class="command"><strong>pentium-builder</strong></span> provides an infrastructure for

292

using a different compiler for building packages than the default gcc, by

293

providing a wrapper script called gcc which calls the real gcc.

294

To use <span class="command"><strong>pentium-builder</strong></span> in <span class="command"><strong>pbuilder</strong></span>, it is possible to set up the

295

following in the configuration:

296

</p><pre class="screen">

297

EXTRAPACKAGES="pentium-builder gcc-3.2 g++-3.2"

298

export DEBIAN_BUILDARCH=athlon

299

export DEBIAN_BUILDGCCVER=3.2</pre><p>

300

</p><p>

301

It will instruct <span class="command"><strong>pbuilder</strong></span> to install the <span class="command"><strong>pentium-builder</strong></span> package

302

and also the GCC 3.2 compiler packages inside the chroot,

303

and set the environment variables required for

304

<span class="command"><strong>pentium-builder</strong></span> to function.

305

</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idp52238768" href="#idp52238768" class="para">1</a>] </sup>debootstrap or cdebootstrap can be chosen</p></div><div class="footnote"><p><sup>[<a id="ftn.idp52241680" href="#idp52241680" class="para">2</a>] </sup>

306

The mirror site should preferably be

307

a local mirror or a cache server,

308

so as not to overload the public mirrors with

309

a lot of access.

310

Use of tools such as apt-proxy would be advisable.

311

</p></div><div class="footnote"><p><sup>[<a id="ftn.idp52071072" href="#idp52071072" class="para">3</a>] </sup>Only upgrading is supported.

312

Debian does not generally support downgrading (yet?).</p></div><div class="footnote"><p><sup>[<a id="ftn.idp57538608" href="#idp57538608" class="para">4</a>] </sup>It is possible to specify <span class="command"><strong>--hookdir

313

/usr/share/doc/pbuilder/examples</strong></span> command-line

314

option to include all example hooks as

315

well.</p></div><div class="footnote"><p><sup>[<a id="ftn.idp57540576" href="#idp57540576" class="para">5</a>] </sup> See run-parts(8). For example, no '.' in file

316

names!

317

</p></div></div></div><div class="chapter" title="Chapter�3.�Using User-mode-linux with pbuilder"><div class="titlepage"><div><div><h2 class="title"><a name="pbuilder-uml"></a>Chapter�3.�Using User-mode-linux with pbuilder</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#user-mode-linux-config">1. Configuring user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#rootstrap">2. Configuring rootstrap</a></span></dt><dt><span class="sect1"><a href="#pbuilderumlconfig">3. Configuring pbuilder-uml</a></span></dt><dt><span class="sect1"><a href="#consideruml">4. Considerations for running pbuilder-user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#paralleluml">5. Parallel running of pbuilder-user-mode-linux</a></span></dt><dt><span class="sect1"><a href="#pbuilderumlwrap">6. Using pbuilder-user-mode-linux as a wrapper script to start up a virtual machine</a></span></dt></dl></div><p>

318

It is possible to use user-mode-linux by invoking

319

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> instead of

320

<span class="command"><strong>pbuilder</strong></span>.

321

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> doesn't require root

322

privileges, and it uses the copy-on-write (COW) disk access

323

method of <span class="command"><strong>User-mode-linux</strong></span> which typically

324

makes it much faster than the traditional

325

<span class="command"><strong>pbuilder</strong></span>.

326

</p><p>

327

<span class="command"><strong>User-mode-linux</strong></span> is a somewhat less proven

328

platform than the standard Unix tools which

329

<span class="command"><strong>pbuilder</strong></span> relies on

330

(<span class="command"><strong>chroot</strong></span>, <span class="command"><strong>tar</strong></span>, and

331

<span class="command"><strong>gzip</strong></span>) but mature enough to support

332

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> since its version

333

0.59. And since then,

334

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> has seen a rapid

335

evolution.

336

</p><p>

337

The configuration of <span class="command"><strong>pbuilder-user-mode-linux</strong></span>

338

goes in three steps:

339

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Configuration of user-mode-linux</p></li><li class="listitem"><p>Configuration of rootstrap</p></li><li class="listitem"><p>Configuration of pbuilder-uml</p></li></ul></div><p>

340

</p><div class="sect1" title="1.�Configuring user-mode-linux"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="user-mode-linux-config"></a>1.�Configuring user-mode-linux</h2></div></div></div><p>

341

user-mode-linux isn't completely trivial to set up. It would

342

probably be useful to acquaint yourself with it a bit before

343

attempting to use <span class="command"><strong>rootstrap</strong></span> or

344

<span class="command"><strong>pbuilder-user-mode-linux</strong></span>. For details,

345

read

346

<code class="filename">/usr/share/doc/uml-utilities/README.Debian</code>

347

and the <span class="command"><strong>user-mode-linux</strong></span> documentation. (It's in a separate

348

package, user-mode-linux-doc.)

349

</p><p>

350

<span class="command"><strong>user-mode-linux</strong></span> requires

351

the user to be in the uml-net group in order to configure the network

352

unless you are using slirp.

353

</p><p>

354

If you compile your own kernel, you may want to

355

verify that you enable TUN/TAP support,

356

and you might want to consider the SKAS patch.

357

</p></div><div class="sect1" title="2.�Configuring rootstrap"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rootstrap"></a>2.�Configuring rootstrap</h2></div></div></div><p>

358

<span class="command"><strong>rootstrap</strong></span>

359

is a wrapper around debootstrap.

360

It creates a Debian disk image for use with UML.

361

To configure rootstrap, there are several requirements.

362

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Install the rootstrap package.</p></li><li class="listitem"><p>

363

TUN/TAP only:

364

add the user to the uml-net group to allow access to the network

365

</p><pre class="screen">adduser dancer uml-net</pre><p>

366

</p></li><li class="listitem"><p>TUN/TAP only:

367

Check that the kernel supports the TUN/TAP interface,

368

or recompile the kernel if necessary.

369

</p></li><li class="listitem"><p>Set up <code class="filename">/etc/rootstrap/rootstrap.conf</code>.

370

For example,

371

if the current host is 192.168.1.2, changing following

372

entries to something like this seems to work.

373

</p><pre class="screen">

374

transport=tuntap

375

interface=eth0

376

gateway=192.168.1.1

377

mirror=http://192.168.1.2:8081/debian

378

host=192.168.1.198

379

uml=192.168.1.199

380

netmask=255.255.255.0</pre><p>

381

Some experimentation with configuration and running

382

<span class="command"><strong>rootstrap ~/test.uml</strong></span> to actually

383

test it would be handy.

384

</p><p>

385

Using slirp requires less configuration.

386

The default configuration comes with a working example.

387

</p></li></ul></div></div><div class="sect1" title="3.�Configuring pbuilder-uml"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pbuilderumlconfig"></a>3.�Configuring pbuilder-uml</h2></div></div></div><p>

388

The following needs to happen:

389

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Install the pbuilder-uml package.</p></li><li class="listitem"><p>

390

Set up the configuration file

391

<code class="filename">/etc/pbuilder/pbuilder-uml.conf</code>

392

in the following manner. It will be different for slirp.

393

</p><pre class="screen">

394

MY_ETH0=tuntap,,,192.168.1.198

395

UML_IP=192.168.1.199

396

UML_NETMASK=255.255.255.0

397

UML_NETWORK=192.168.1.0

398

UML_BROADCAST=255.255.255.255

399

UML_GATEWAY=192.168.1.1

400

PBUILDER_UML_IMAGE="/home/dancer/uml-image"</pre><p>

401

Also, it needs to match the rootstrap configuration.

402

</p></li><li class="listitem"><p>

403

Make sure BUILDPLACE is writable by the user.

404

Change BUILDPLACE in the configuration file to a place

405

where the user has access.

406

</p></li><li class="listitem"><p>Run <span class="command"><strong>pbuilder-user-mode-linux <code class="option">create --distribution sid</code></strong></span> to create the image.</p></li><li class="listitem"><p>Try running <span class="command"><strong>pbuilder-user-mode-linux build</strong></span>.</p></li></ul></div><p>

407

</p></div><div class="sect1" title="4.�Considerations for running pbuilder-user-mode-linux"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="consideruml"></a>4.�Considerations for running pbuilder-user-mode-linux</h2></div></div></div><p>

408

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> emulates most of <span class="command"><strong>pbuilder</strong></span>, but there

409

are some differences.

410

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>

411

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> does not support all options of <span class="command"><strong>pbuilder</strong></span>

412

properly yet. This is a problem, and will be addressed as

413

specific areas are discovered.

414

</p></li><li class="listitem"><p>

415

/tmp is handled differently inside

416

<span class="command"><strong>pbuilder-user-mode-linux</strong></span>. In

417

<span class="command"><strong>pbuilder-user-mode-linux</strong></span>,

418

<code class="filename">/tmp</code> is mounted as tmpfs inside UML,

419

so accessing files under <code class="filename">/tmp</code> from

420

outside user-mode-linux does not work. It affects options

421

like <span class="command"><strong><code class="option">--configfile</code></strong></span>, and

422

when trying to build packages placed under

423

<code class="filename">/tmp</code>.

424

</p></li></ul></div></div><div class="sect1" title="5.�Parallel running of pbuilder-user-mode-linux"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="paralleluml"></a>5.�Parallel running of pbuilder-user-mode-linux</h2></div></div></div><p>

425

To run <span class="command"><strong>pbuilder-user-mode-linux</strong></span> in parallel

426

on a system, there are a few things to bear in mind.

427

</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The create and update methods must not be run when

428

a build is in progress, or the COW file will be invalidated.</p></li><li class="listitem"><p>

429

If you are not using slirp, user-mode-linux processes which are

430

running in parallel need to have different IP addresses.

431

Just trying to run the <span class="command"><strong>pbuilder-user-mode-linux</strong></span>

432

several times will result in failure to access the network.

433

But something like the following will work:

434

</p><pre class="screen">

435

for IP in 102 103 104 105; do

436

xterm -e pbuilder-user-mode-linux build --uml-ip 192.168.0.$IP \

437

20030107/whizzytex_1.1.1-1.dsc &

438

done</pre><p>

439

When using slirp, this problem does not exist.

440

</p></li></ul></div></div><div class="sect1" title="6.�Using pbuilder-user-mode-linux as a wrapper script to start up a virtual machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pbuilderumlwrap"></a>6.�Using pbuilder-user-mode-linux as a wrapper script to start up a virtual machine</h2></div></div></div><p>

441

It is possible to use

442

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> for other uses

443

than just building Debian packages.

444

<span class="command"><strong>pbuilder-user-mode-linux

445

<code class="option">login</code></strong></span> will let a user use a shell

446

inside the user-mode-linux <span class="command"><strong>pbuilder</strong></span> base

447

image, and <span class="command"><strong>pbuilder-user-mode-linux

448

<code class="option">execute</code></strong></span> will allow the user to

449

execute a script inside the image.

450

</p><p>

451

You can use the script to install ssh and add a new user,

452

so that it is possible to access inside the user-mode-linux through ssh.

453

</p><p>

454

Note that it is not possible to use a script from

455

<code class="filename">/tmp</code> due to the way

456

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> mounts a tmpfs at

457

<code class="filename">/tmp</code>.

458

</p><p>

459

The following example script may be useful in starting a sshd

460

inside user-mode-linux.

461

</p><pre class="screen">

462

#!/bin/bash

463

464

apt-get install -y ssh xbase-clients xterm

465

echo "enter root password"

466

passwd

467

cp /etc/ssh/sshd_config{,-}

468

sed 's/X11Forwarding.*/X11Forwarding yes/' /etc/ssh/sshd_config- > /etc/ssh/sshd_config

469

470

/etc/init.d/ssh restart

471

ifconfig

472

echo "Hit enter to finish"

473

read</pre></div></div><div class="chapter" title="Chapter�4.�Frequently asked questions"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Chapter�4.�Frequently asked questions </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#pbuildercreatefail">1. pbuilder create fails</a></span></dt><dt><span class="sect1"><a href="#bindmountlimits">2. Directories that cannot be bind-mounted</a></span></dt><dt><span class="sect1"><a href="#shellafterfail">3. Logging in to pbuilder to investigate build failure</a></span></dt><dt><span class="sect1"><a href="#modifyupdate">4. Logging in to pbuilder to modify the environment</a></span></dt><dt><span class="sect1"><a href="#BUILDRESULTUID">5. Setting BUILDRESULTUID for sudo sessions</a></span></dt><dt><span class="sect1"><a href="#tmpdir">6. Notes on usage of $TMPDIR</a></span></dt><dt><span class="sect1"><a href="#DISTRIBUTIONSWITCH">7. Creating a shortcut for running <span class="command"><strong>pbuilder</strong></span> with a specific distribution</a></span></dt><dt><span class="sect1"><a href="#ENVVARDISTRIBUTIONSWITCH">8. Using environmental variables for running <span class="command"><strong>pbuilder</strong></span>

474

for specific distribution

475

</a></span></dt><dt><span class="sect1"><a href="#usingspecialaptsources">9. Using special apt sources lists, and local packages</a></span></dt><dt><span class="sect1"><a href="#apt-getupdateonbuild-depend">10. How to get pbuilder to run apt-get update before trying to satisfy build-dependency</a></span></dt><dt><span class="sect1"><a href="#bashprompt">11. Different bash prompts inside pbuilder login</a></span></dt><dt><span class="sect1"><a href="#chrootmemo">12. Creating a chroot reminder</a></span></dt><dt><span class="sect1"><a href="#packagecachearchives">13. Using /var/cache/apt/archives for the package cache</a></span></dt><dt><span class="sect1"><a href="#stablebackport">14. pbuilder back ported to stable Debian releases</a></span></dt><dt><span class="sect1"><a href="#LOGNAME">15. Warning about LOGNAME not being defined</a></span></dt><dt><span class="sect1"><a href="#nobuildconflictessential">16. Cannot Build-conflict against an essential package</a></span></dt><dt><span class="sect1"><a href="#lninvalidcrossdevicelink">17. Avoiding the "ln: Invalid cross-device link" message</a></span></dt><dt><span class="sect1"><a href="#fakechroot">18. Using fakechroot</a></span></dt><dt><span class="sect1"><a href="#debconfinsidepbuilder">19. Using debconf inside pbuilder sessions</a></span></dt><dt><span class="sect1"><a href="#nodev">20. nodev mount options hinder pbuilder activity</a></span></dt><dt><span class="sect1"><a href="#faqslowpbuilder">21. pbuilder is slow</a></span></dt><dt><span class="sect1"><a href="#sponsor">22. Using pdebuild to sponsor package</a></span></dt><dt><span class="sect1"><a href="#sourcechanges">23. Why is there a source.changes file in ../?</a></span></dt><dt><span class="sect1"><a href="#amd64i386">24. amd64 and i386-mode</a></span></dt><dt><span class="sect1"><a href="#tmpfsforpbuilder">25. Using tmpfs for buildplace</a></span></dt><dt><span class="sect1"><a href="#idp57743216">26. Using svn-buildpackage together with pbuilder</a></span></dt></dl></div><p>

476

Here, known problems and frequently asked questions are

477

documented. This portion was initially available in README.Debian

478

file, but moved here.

479

</p><div class="sect1" title="1.�pbuilder create fails"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pbuildercreatefail"></a>1.�pbuilder create fails</h2></div></div></div><p>

480

It often happens that <span class="command"><strong>pbuilder</strong></span> cannot create the latest chroot.

481

Try upgrading <span class="command"><strong>pbuilder</strong></span> and debootstrap.

482

It is currently only possible to create software that handles the

483

past. Future prediction is a feature which may be added later after

484

we have become comfortable with the past.

485

</p><p>

486

There are people who occasionally back port debootstrap to stable

487

versions; hunt for them.

488

</p><p>

489

When there are errors with the debootstrap phase,

490

the debootstrap script needs to be fixed.

491

<span class="command"><strong>pbuilder</strong></span> does not provide a way to work around debootstrap.

492

</p></div><div class="sect1" title="2.�Directories that cannot be bind-mounted"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bindmountlimits"></a>2.�Directories that cannot be bind-mounted</h2></div></div></div><p>

493

Because of the way <span class="command"><strong>pbuilder</strong></span> works, there

494

are several directories which cannot be bind-mounted when

495

running <span class="command"><strong>pbuilder</strong></span>. The directories include

496

<code class="filename">/tmp</code>,

497

<code class="filename">/var/cache/pbuilder</code>, and system

498

directories such as <code class="filename">/etc</code> and

499

<code class="filename">/usr</code>. The recommendation is to use

500

directories under the user's home directory for bind-mounts.

501

</p></div><div class="sect1" title="3.�Logging in to pbuilder to investigate build failure"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="shellafterfail"></a>3.�Logging in to pbuilder to investigate build failure</h2></div></div></div><p>

502

It is possible to invoke a shell session after a build

503

failure. Example hook scripts are provided as

504

<code class="filename">C10shell</code> and

505

<code class="filename">C11screen</code> scripts. C10shell script will

506

start bash inside chroot, and C11screen script will start GNU

507

screen inside the chroot.

508

</p></div><div class="sect1" title="4.�Logging in to pbuilder to modify the environment"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="modifyupdate"></a>4.�Logging in to pbuilder to modify the environment</h2></div></div></div><p>

509

It is sometimes necessary to modify the chroot environment.

510

<span class="command"><strong>login</strong></span> will remove the contents of the chroot after logout.

511

It is possible to invoke a shell using hook scripts.

512

<span class="command"><strong>pbuilder update</strong></span> executes 'E' scripts,

513

and a sample for invoking a shell

514

is provided as <code class="filename">C10shell</code>.

515

</p><pre class="screen">

516

$ mkdir ~/loginhooks

517

$ cp C10shell ~/loginhooks/E10shell

518

$ sudo pbuilder update --hookdir ~/loginhooks/E10shell</pre><p>

519

It is also possible to add <code class="option">--save-after-exec</code>

520

and/or <code class="option">--save-after-login</code> options

521

to the <span class="command"><strong>pbuilder login</strong></span> session

522

to accomplish the goal.

523

It is possible to add the <code class="option">--uml-login-nocow</code> option

524

to <span class="command"><strong>pbuilder-user-mode-linux <code class="option">login</code></strong></span> session

525

as well.

526

</p></div><div class="sect1" title="5.�Setting BUILDRESULTUID for sudo sessions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="BUILDRESULTUID"></a>5.�Setting BUILDRESULTUID for sudo sessions</h2></div></div></div><p>

527

It is possible to set

528

</p><pre class="screen">BUILDRESULTUID=$SUDO_UID</pre><p> in pbuilderrc to set

529

the proper BUILDRESULTUID when using <span class="command"><strong>sudo</strong></span>.

530

</p></div><div class="sect1" title="6.�Notes on usage of $TMPDIR"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tmpdir"></a>6.�Notes on usage of $TMPDIR</h2></div></div></div><p>

531

If you are setting $TMPDIR to an unusual value, of other than

532

<code class="filename">/tmp</code>, you will find that some errors may occur inside the chroot,

533

such as <span class="command"><strong>dpkg-source</strong></span> failing.

534

</p><p>There are two options, you may install a hook to create that

535

directory, or set

536

</p><pre class="screen">export TMPDIR=/tmp</pre><p>

537

in pbuilderrc. Take your pick.

538

</p><p>

539

An example script is provided as

540

<code class="filename">examples/D10tmp</code> with <span class="command"><strong>pbuilder</strong></span>.

541

</p></div><div class="sect1" title="7.�Creating a shortcut for running pbuilder with a specific distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="DISTRIBUTIONSWITCH"></a>7.�Creating a shortcut for running <span class="command"><strong>pbuilder</strong></span> with a specific distribution</h2></div></div></div><p>

542

When working with multiple chroots, it would be nice to work

543

with scripts that reduce the amount of typing. An example

544

script <code class="filename">pbuilder-distribution.sh</code> is

545

provided as an example. Invoking the script as

546

<code class="filename">pbuilder-squeeze</code> will invoke

547

<span class="command"><strong>pbuilder</strong></span> with a squeeze chroot.

548

</p></div><div class="sect1" title="8.�Using environmental variables for running pbuilder for specific distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ENVVARDISTRIBUTIONSWITCH"></a>8.�Using environmental variables for running <span class="command"><strong>pbuilder</strong></span>

549

for specific distribution

550

</h2></div></div></div><p> This section<sup>[<a name="idp57650688" href="#ftn.idp57650688" class="footnote">6</a>]</sup>

551

describes briefly a way to setup and use multiple pbuilder setups

552

by creating a pbuilderrc configuration in your home path (<code class="filename">$HOME/.pbuilderrc</code>)

553

and using the variable "DIST" when running pbuilder or pdebuild.

554

</p><p> First, setup <code class="filename">$HOME/.pbuilderrc</code> to look like:</p><p>

555

</p><pre class="screen">

556

if [ -n "${DIST}" ]; then

557

BASETGZ="`dirname $BASETGZ`/$DIST-base.tgz"

558

DISTRIBUTION="$DIST"

559

BUILDRESULT="/var/cache/pbuilder/$DIST/result/"

560

APTCACHE="/var/cache/pbuilder/$DIST/aptcache/"

561

fi

562

</pre><p>Then, whenever you wish to use pbuilder for a particular distro, assign a value

563

to "DIST" that is one of the distros available for Debian or any Debian based

564

distro you happen to be running (i.e. whatever is found under

565

/usr/lib/debootstrap/scripts).

566

</p><p>Here's some examples on running pbuilder or pdebuild:

567

</p><pre class="screen">

568

DIST=gutsy sudo pbuilder create

569

570

DIST=sid sudo pbuilder create --mirror http://http.us.debian.org/debian

571

572

DIST=gutsy sudo pbuilder create \

573

--othermirror "deb http://archive.ubuntu.com/ubuntu gutsy universe \

574

multiverse"

575

576

DIST=gutsy sudo pbuilder update

577

578

DIST=sid sudo pbuilder update --override-config --mirror \

579

http://http.us.debian.org/debian \

580

--othermirror "deb http://http.us.debian.org/debian sid contrib non-free"

581

582

DIST=gutsy pdebuild

583

</pre></div><div class="sect1" title="9.�Using special apt sources lists, and local packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingspecialaptsources"></a>9.�Using special apt sources lists, and local packages</h2></div></div></div><p>

584

If you have some very specialized requirements on your

585

apt setup inside <span class="command"><strong>pbuilder</strong></span>,

586

it is possible to specify that through

587

the <span class="command"><strong><code class="option">--othermirror</code></strong></span>

588

option.

589

Try something like:

590

<span class="command"><strong><code class="option">--othermirror "deb http://local/mirror stable main|deb-src http://local/source/repository ./"</code></strong></span>

591

</p><p>

592

To use the local file system instead of HTTP, it is necessary to do

593

bind-mounting.

594

<span class="command"><strong><code class="option">--bindmounts</code></strong></span>

595

is a command-line option useful for such cases.

596

</p><p>

597

It might be convenient to use your built packages from inside the chroot.

598

It is possible to automate the task with the following configuration.

599

First, set up pbuilderrc to bindmount your build results directory.

600

</p><p>

601

</p><pre class="screen">BINDMOUNTS="/var/cache/pbuilder/result"</pre><p>

602

</p><p>

603

Then, add the following hook

604

</p><p>

605

</p><pre class="screen">

606

# cat /var/cache/pbuilder/hooks/D70results

607

#!/bin/sh

608

cd /var/cache/pbuilder/result/

609

/usr/bin/dpkg-scanpackages . /dev/null > /var/cache/pbuilder/result/Packages

610

/usr/bin/apt-get update</pre><p>

611

</p><p>

612

This way, you can use <code class="filename">deb file:/var/cache/pbuilder/result</code>

613

</p><p>

614

To add new apt-key inside chroot:

615

616

</p><p>

617

</p><pre class="screen">

618

sudo pbuilder --login --save-after-login

619

# apt-key add - <<EOF

620

...public key goes here...

621

EOF

622

# logout

623

</pre></div><div class="sect1" title="10.�How to get pbuilder to run apt-get update before trying to satisfy build-dependency"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apt-getupdateonbuild-depend"></a>10.�How to get pbuilder to run apt-get update before trying to satisfy build-dependency</h2></div></div></div><p>

624

You can use hook scripts for this.

625

D scripts are run before satisfying build-dependency.

626

</p><p>

627

628

This snippet comes from Ondrej Sury.

629

</a>

630

</p></div><div class="sect1" title="11.�Different bash prompts inside pbuilder login"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bashprompt"></a>11.�Different bash prompts inside pbuilder login</h2></div></div></div><p>

631

To make distinguishing bash prompts inside

632

<span class="command"><strong>pbuilder</strong></span> easier, it is possible to set

633

environment variables such as PS1 inside

634

<code class="filename">pbuilderrc</code>

635

</p><p>

636

With versions of bash more recent than 2.05b-2-15,

637

the value of the debian_chroot variable, if set,

638

is included in the value of PS1 (the Bash prompt)

639

inside the chroot.

640

In prior versions of bash,<sup>[<a name="idp57674928" href="#ftn.idp57674928" class="footnote">7</a>]</sup>

641

setting PS1 in pbuilderrc worked.

642

</p><p>example of debian_chroot</p><pre class="screen">

643

export debian_chroot="pbuild$$"</pre><p>example of PS1</p><pre class="screen">

644

export PS1="pbuild chroot 32165 # "</pre></div><div class="sect1" title="12.�Creating a chroot reminder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="chrootmemo"></a>12.�Creating a chroot reminder</h2></div></div></div><p>

645

Bash prompts will help you remember that you are inside a

646

chroot. There are other cases where you may want other signs

647

of being inside a chroot. Check out the

648

<code class="filename">examples/F90chrootmemo</code> hook script. It

649

will create a file called <code class="filename">/CHROOT</code> inside

650

your chroot.

651

</p></div><div class="sect1" title="13.�Using /var/cache/apt/archives for the package cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packagecachearchives"></a>13.�Using /var/cache/apt/archives for the package cache</h2></div></div></div><p>

652

For the help of low-bandwidth systems, it is possible to use

653

<code class="filename">/var/cache/apt/archives</code> as the package

654

cache. Just specify it instead of the default

655

<code class="filename">/var/cache/pbuilder/aptcache</code>.

656

</p><p>

657

It is however not possible to do so currently with the

658

user-mode-linux version of <span class="command"><strong>pbuilder</strong></span>,

659

because <code class="filename">/var/cache/apt/archives</code> is

660

usually only writable by root.

661

</p><p>

662

Use of dedicated tools such as apt-proxy is recommended, since

663

caching of packages would benefit the system outside the scope

664

of <span class="command"><strong>pbuilder</strong></span>.

665

</p></div><div class="sect1" title="14.�pbuilder back ported to stable Debian releases"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="stablebackport"></a>14.�pbuilder back ported to stable Debian releases</h2></div></div></div><p>

666

Currently stable back port of pbuilder is available at backports.org.

667

</p></div><div class="sect1" title="15.�Warning about LOGNAME not being defined"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="LOGNAME"></a>15.�Warning about LOGNAME not being defined</h2></div></div></div><p>

668

You might see a lot of warning messages when running <span class="command"><strong>pbuilder</strong></span>.

669

</p><p>

670

</p><pre class="screen">

671

dpkg-genchanges: warning: no utmp entry available and LOGNAME not defined; using uid of process (1234)</pre><p>

672

</p><p>

673

It is currently safe to ignore this warning message. Please

674

report back if you find any problem with having LOGNAME unset.

675

Setting LOGNAME caused a few problems when invoking

676

<span class="command"><strong>chroot</strong></span>. For example, dpkg requires getpwnam

677

to succeed inside chroot, which means LOGNAME and the related

678

user information have to be set up inside chroot.

679

</p></div><div class="sect1" title="16.�Cannot Build-conflict against an essential package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nobuildconflictessential"></a>16.�Cannot Build-conflict against an essential package</h2></div></div></div><p>

680

<span class="command"><strong>pbuilder</strong></span> does not currently allow Build-Conflicts against

681

essential packages.

682

It should be obvious that essential packages should not be

683

removed from a working Debian system, and a source

684

package should not try to force removal of such packages

685

on people building the package.

686

</p></div><div class="sect1" title='17.�Avoiding the "ln: Invalid cross-device link" message'><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lninvalidcrossdevicelink"></a>17.�Avoiding the "ln: Invalid cross-device link" message</h2></div></div></div><p>

687

By default, <span class="command"><strong>pbuilder</strong></span> uses hard links to

688

manage the <span class="command"><strong>pbuilder</strong></span> package cache. It is

689

not possible to make hard links across different devices; and

690

thus this error will occur, depending on your set up. If this

691

happens, set </p><pre class="screen">APTCACHEHARDLINK=no</pre><p> in your

692

pbuilderrc file. Note that packages in

693

<span class="command"><strong>APTCACHE</strong></span> will be copied into chroot local

694

cache, so plan for enough space on

695

<span class="command"><strong>BUILDPLACE</strong></span> device.

696

</p></div><div class="sect1" title="18.�Using fakechroot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fakechroot"></a>18.�Using fakechroot</h2></div></div></div><p>

697

It is possible to use <span class="command"><strong>fakechroot</strong></span> instead of

698

being root to run <span class="command"><strong>pbuilder</strong></span>; however,

699

several things make this impractical.

700

<span class="command"><strong>fakechroot</strong></span> overrides library loads and

701

tries to override default libc functions when providing the

702

functionality of virtual <span class="command"><strong>chroot</strong></span>. However,

703

some binaries do no use libc to function, or override the

704

overriding provided by <span class="command"><strong>fakechroot</strong></span>. One

705

example is <span class="command"><strong>ldd</strong></span>. Inside

706

<span class="command"><strong>fakechroot</strong></span>, <span class="command"><strong>ldd</strong></span> will

707

check the library dependency outside of the chroot, which is

708

not the expected behavior.

709

</p><p>

710

To work around the problem, debootstrap has a

711

<code class="option">--variant fakechroot</code> option. Use that, so

712

that ldd and ldconfig are overridden.

713

</p><p>

714

Make sure you have set your LD_PRELOAD path correctly, as described in

715

the fakechroot manpage.

716

</p></div><div class="sect1" title="19.�Using debconf inside pbuilder sessions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="debconfinsidepbuilder"></a>19.�Using debconf inside pbuilder sessions</h2></div></div></div><p>

717

To use debconf inside <span class="command"><strong>pbuilder</strong></span>, setting DEBIAN_FRONTEND to

718

<span class="quote">“<span class="quote">readline</span>”</span> in <code class="filename">pbuilderrc</code> should work.

719

Setting it to <span class="quote">“<span class="quote">dialog</span>”</span> should also work, but make sure

720

whiptail or dialog is installed inside the chroot.

721

</p></div><div class="sect1" title="20.�nodev mount options hinder pbuilder activity"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nodev"></a>20.�nodev mount options hinder pbuilder activity</h2></div></div></div><p>

722

If you see messages such as this when building a chroot, you are mounting the file system with

723

the nodev option.

724

</p><pre class="screen">

725

/var/lib/dpkg/info/base-files.postinst: /dev/null: Permission denied</pre><p>

726

You will also have problems if you mount the file system with

727

the noexec option, or nosuid.

728

Make sure you do not have these flags set when mounting the file system for

729

<code class="filename">/var/cache/pbuilder</code> or $BUILDPLACE.

730

</p><p>

731

This is not a problem when using <span class="command"><strong>user-mode-linux</strong></span>.

732

</p><p>

733

See <a class="ulink" href="http://bugs.debian.org/316135" target="_top">

734

316135

735

</a> for example.

736

</p></div><div class="sect1" title="21.�pbuilder is slow"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="faqslowpbuilder"></a>21.�pbuilder is slow</h2></div></div></div><p>

737

<span class="command"><strong>pbuilder</strong></span> is often slow. The slowest part of

738

<span class="command"><strong>pbuilder</strong></span> is extracting the tar.gz every

739

time <span class="command"><strong>pbuilder</strong></span> is invoked. That can be

740

avoided by using <span class="command"><strong>pbuilder-user-mode-linux</strong></span>.

741

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> uses COW file

742

system, and thus does not need to clean up and recreate the

743

root file system.

744

</p><p>

745

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> is slower in

746

executing the actual build system, due to the usual

747

<span class="command"><strong>user-mode-linux</strong></span> overhead for system

748

calls. It is more friendly to the hard drive.

749

</p><p>

750

<span class="command"><strong>pbuilder</strong></span> with cowdancer is also an

751

alternative that improves speed of pbuilder startup.

752

</p></div><div class="sect1" title="22.�Using pdebuild to sponsor package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sponsor"></a>22.�Using pdebuild to sponsor package</h2></div></div></div><p>

753

To sign a package marking for sponsorship, it is possible to

754

use<span class="command"><strong><code class="option"> --auto-debsign</code></strong></span> and

755

<span class="command"><strong><code class="option">--debsign-k</code></strong></span> options of

756

<span class="command"><strong>pdebuild</strong></span>.

757

</p><pre class="screen">

758

<span class="command"><strong>pdebuild <code class="option">--auto-debsign </code> <code class="option">--debsign-k </code><em class="parameter"><code>XXXXXXXX</code></em></strong></span></pre></div><div class="sect1" title="23.�Why is there a source.changes file in ../?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sourcechanges"></a>23.�Why is there a source.changes file in ../?</h2></div></div></div><p>

759

When running <span class="command"><strong>pdebuild</strong></span>, <span class="command"><strong>pbuilder</strong></span> will run dpkg-buildpackage to create a

760

Debian source package to pass it on to <span class="command"><strong>pbuilder</strong></span>.

761

File named XXXX_YYY_source.changes is what remains from that process.

762

It is harmless unless you try to upload it to the Debian archive.

763

</p><p>

764

This behavior is different when running through <code class="option">--use-pdebuild-internal</code>

765

</p></div><div class="sect1" title="24.�amd64 and i386-mode"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="amd64i386"></a>24.�amd64 and i386-mode</h2></div></div></div><p>

766

amd64 architectures are capable of running binaries in i386

767

mode. It is possible to use <span class="command"><strong>pbuilder</strong></span> to

768

run packages, using <span class="command"><strong>linux32</strong></span> and

769

<span class="command"><strong>debootstrap <code class="option">--arch</code></strong></span> option.

770

Specifically, a command-line option like the following will

771

work.

772

</p><p>

773

</p><pre class="screen">

774

<span class="command"><strong>pbuilder create --distribution sid --debootstrapopts --arch --debootstrapopts i386 \

775

--basetgz /var/cache/pbuilder/base-i386.tgz --mirror http://ftp.jp.debian.org/debian</strong></span>

776

<span class="command"><strong>linux32 pbuilder build --basetgz /var/cache/pbuilder/base-i386.tgz</strong></span></pre><p>

777

</p></div><div class="sect1" title="25.�Using tmpfs for buildplace"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tmpfsforpbuilder"></a>25.�Using tmpfs for buildplace</h2></div></div></div><p>

778

To improve speed of operation, it is possible to use tmpfs for

779

pbuilder build location. Mount tmpfs to

780

<code class="filename">/var/cache/pbuilder/build</code>, and set

781

</p><pre class="screen">APTCACHEHARDLINK=no</pre><p>.

782

</p></div><div class="sect1" title="26.�Using svn-buildpackage together with pbuilder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp57743216"></a>26.�Using svn-buildpackage together with pbuilder</h2></div></div></div><p>

783

pdebuild command can be used with svn-buildpackage

784

--svn-builder command-line option.

785

786

</p><pre class="screen">

787

alias svn-cowbuilder="svn-buildpackage --svn-builder='pdebuild --pbuilder cowbuilder"</pre></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.idp57650688" href="#idp57650688" class="para">6</a>] </sup>This part of the documentation contributed by Andres Mejia</p><p>

788

This example was taken from a wiki (<a class="ulink" href="https://wiki.ubuntu.com/PbuilderHowto" target="_top">https://wiki.ubuntu.com/PbuilderHowto</a>).

789

</p></div><div class="footnote"><p><sup>[<a id="ftn.idp57674928" href="#idp57674928" class="para">7</a>] </sup>Versions of bash from and before Debian 3.0</p></div><div class="footnote"><p><sup>[<a id="ftn.idp57744464" href="#idp57744464" class="para">8</a>] </sup><a class="ulink" href="http://upsilon.cc/~zack/blog/posts/2007/09/svn-cowbuilder/" target="_top">

790

Zack has posted an example on his blog.

791

</a></p></div></div></div><div class="chapter" title="Chapter�5.�Troubleshooting and development"><div class="titlepage"><div><div><h2 class="title"><a name="develanddebug"></a>Chapter�5.�Troubleshooting and development</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#bugreport">1. Reporting bugs </a></span></dt><dt><span class="sect1"><a href="#mailinglist">2. Mailing list</a></span></dt><dt><span class="sect1"><a href="#IRCchannel">3. IRC Channel</a></span></dt><dt><span class="sect1"><a href="#development">4. Information for pbuilder developers</a></span></dt></dl></div><div class="sect1" title="1.�Reporting bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bugreport"></a>1.�Reporting bugs </h2></div></div></div><p>

792

To report bugs, it would be important to have a log of what's

793

going wrong. Most of the time, adding a

794

<span class="command"><strong><code class="option">--debug</code></strong></span> option and

795

re-running the session should do the trick. Please send the

796

log of such session along with your problem to ease the

797

debugging process.

798

</p></div><div class="sect1" title="2.�Mailing list"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mailinglist"></a>2.�Mailing list</h2></div></div></div><p>

799

There is a mailing list for <span class="command"><strong>pbuilder</strong></span> on

800

alioth (pbuilder-maint@lists.alioth.debian.org). You can

801

subscribe through the alioth web interface.

802

803

http://alioth.debian.org/mail/?group_id=30778</a>.

804

</p></div><div class="sect1" title="3.�IRC Channel"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="IRCchannel"></a>3.�IRC Channel</h2></div></div></div><p>

805

For coordination and communication,

806

IRC channel #pbuilder on irc.oftc.net is used.

807

Please log your intent there when you are going to

808

start doing some changes and committing some change.

809

</p></div><div class="sect1" title="4.�Information for pbuilder developers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="development"></a>4.�Information for pbuilder developers</h2></div></div></div><p>

810

This section tries to document current development practices

811

and how things generally operate in development.

812

</p><p>

813

<span class="command"><strong>pbuilder</strong></span> is co-maintained with resources

814

provided by Alioth.

815

816

There is an Alioth project page at

817

818

http://alioth.debian.org/projects/pbuilder</a>.

819

Home page is also available,

820

at <a class="ulink" href="http://pbuilder.alioth.debian.org/" target="_top">

821

http://alioth.debian.org/projects/pbuilder</a>

822

which shows this text.

823

git repository is available through http, git, or (if you have an

824

account on alioth, ) ssh.

825

</p><pre class="screen">

826

git-clone git://git.debian.org/git/pbuilder/pbuilder.git

827

git-clone http://git.debian.org/git/pbuilder/pbuilder.git

828

git-clone ssh://git.debian.org/git/pbuilder/pbuilder.git</pre><p>

829

Git commit message should have the first one line describing

830

what the commit does, formatted in the way debian/changelog is

831

formatted because it is copied verbatim to changelog via

832

git-dch. The second line is empty, and the rest should

833

describe the background and extra information related to

834

implementation of the commit.

835

</p><p>

836

Test-suites are available in <code class="filename">./testsuite/</code> directory.

837

Changes are expected not to break the test-suites.

838

<code class="filename">./run-test.sh</code> is a basic test-suite, which puts a summary in

839

<code class="filename">run-test.log</code>, and <code class="filename">run-test-cdebootstrap.log</code>.

840

<code class="filename">./run-test-regression.sh</code> is a regression test-suite,

841

which puts the result in <code class="filename">run-test-regression.log</code>.

842

Currently, run-test.sh is ran automatically daily to ensure that pbuilder is working.

843

</p><div class="table"><a name="dirtestsuites"></a><p class="title"><b>Table�5.1.�Directory structure of the testsuite</b></p><div class="table-contents"><table summary="Directory structure of the testsuite" border="1"><colgroup><col align="left" class="c1"><col align="left" class="c2"></colgroup><thead><tr><th align="left">Directory</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><code class="filename">./testsuite/</code></td><td align="left">Directory for testsuite</td></tr><tr><td align="left"><code class="filename">./testsuite/run-test.sh</code></td><td align="left">Daily regression test to test against Debian Archive changes breaking pbuilder.</td></tr><tr><td align="left"><code class="filename">./testsuite/run-test.log</code></td><td align="left">A summary of testsuite</td></tr><tr><td align="left"><code class="filename">./testsuite/normal/</code></td><td align="left">Directory for testsuite results of running pbuilder with debootstrap</td></tr><tr><td align="left"><code class="filename">./testsuite/cdebootstrap/</code></td><td align="left">Directory for testsuite results of running pbuilder with cdebootstrap</td></tr><tr><td align="left"><code class="filename">./testsuite/run-regression.sh</code></td><td align="left">Regression testsuite, ran every time change is made to pbuilder to make sure there is no regression.</td></tr><tr><td align="left"><code class="filename">./testsuite/run-regression.log</code></td><td align="left">Summary of test result</td></tr><tr><td align="left"><code class="filename">./testsuite/regression/BugID-*.sh</code></td><td align="left">Regression tests, exit 0 for success, exit 1 for failure</td></tr><tr><td align="left"><code class="filename">./testsuite/regression/BugID-*</code></td><td align="left">Files used for the regression testsuite.</td></tr><tr><td align="left"><code class="filename">./testsuite/regression/log/BugID-*.sh.log</code></td><td align="left">Output of the regression test, output from the script is redirected by run-regression.sh</td></tr></tbody></table></div></div><br class="table-break"><p>

844

When making changes, changes should be documented in the Git

845

commit log. git-dch will generate debian/changelog from the

846

commit log. Make the first line of your commit log meaningful,

847

and add any bug-closing information available.

848

debian/changelog should not be edited directly unless when

849

releasing a new version.

850

</p><p>

851

A TODO file is available in <code class="filename">debian/TODO</code>.

852

It's mostly not well-maintained, but hopefully it will be more

853

up-to-date when people start using it. emacs todoo-mode is

854

used in editing the file.

855

</p><p>

856

When releasing a new version of <span class="command"><strong>pbuilder</strong></span>,

857

the version is tagged with the git tag

858

X.XXX (version number).

859

This is done with <span class="command"><strong>./git-tag.sh</strong></span> script available in the source tree.

860

</p></div></div><div class="chapter" title="Chapter�6.�Other uses of pbuilder"><div class="titlepage"><div><div><h2 class="title"><a name="otheruse"></a>Chapter�6.�Other uses of pbuilder</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#chroot">1. Using pbuilder for small experiments</a></span></dt><dt><span class="sect1"><a href="#runningprograms">2. Running little programs inside the chroot</a></span></dt></dl></div><div class="sect1" title="1.�Using pbuilder for small experiments"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="chroot"></a>1.�Using pbuilder for small experiments</h2></div></div></div><p>

861

There are cases when some small experimenting is required, and

862

you do not want to damage the main system,

863

like when installing experimental library packages,

864

or compiling with experimental compilers.

865

For such cases, the <span class="command"><strong>pbuilder login</strong></span> command is available.

866

</p><p>

867

<span class="command"><strong>pbuilder login </strong></span> is a debugging feature for

868

<span class="command"><strong>pbuilder</strong></span> itself, but it also allows users to have a temporary chroot.

869

</p><p>

870

Note that the chroot is cleaned after logging out of the shell,

871

and mounting file systems inside it is considered harmful.

872

</p></div><div class="sect1" title="2.�Running little programs inside the chroot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="runningprograms"></a>2.�Running little programs inside the chroot</h2></div></div></div><p>

873

To facilitate using <span class="command"><strong>pbuilder</strong></span> for other uses,

874

<span class="command"><strong>pbuilder execute</strong></span> is available.

875

<span class="command"><strong>pbuilder execute </strong></span> will take a script

876

specified in the command-line argument, and

877

invoke the script inside the chroot.

878

</p><p>

879

The script can be useful for sequences of operations such as

880

installing ssh and adding a new user inside the chroot.

881

</p></div></div><div class="chapter" title="Chapter�7.�Experimental or wishlist features of pbuilder"><div class="titlepage"><div><div><h2 class="title"><a name="experimental"></a>Chapter�7.�Experimental or wishlist features of pbuilder</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#lvm">1. Using LVM</a></span></dt><dt><span class="sect1"><a href="#cowdancer">2. Using cowdancer</a></span></dt><dt><span class="sect1"><a href="#withouttargz">3. Using pbuilder without tar.gz</a></span></dt><dt><span class="sect1"><a href="#inavserver">4. Using pbuilder in a vserver</a></span></dt><dt><span class="sect1"><a href="#ccache">5. Usage of ccache</a></span></dt></dl></div><p>

882

There are some advanced features, above that of the

883

basic feature of <span class="command"><strong>pbuilder</strong></span>, for some specific purposes.

884

</p><div class="sect1" title="1.�Using LVM"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="lvm"></a>1.�Using LVM</h2></div></div></div><p>

885

LVM2 has a useful snapshot function that features Copy-on-write images.

886

That could be used for <span class="command"><strong>pbuilder</strong></span> just as it can be used for

887

the user-mode-linux <span class="command"><strong>pbuilder</strong></span> port.

888

lvmpbuilder script in the examples directory implements such port.

889

The scripts and documentation can be found under

890

<code class="filename">/usr/share/doc/pbuilder/examples/lvmpbuilder/</code>.

891

</p></div><div class="sect1" title="2.�Using cowdancer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cowdancer"></a>2.�Using cowdancer</h2></div></div></div><p>

892

<span class="command"><strong>cowdancer</strong></span> allows copy-on-write semantics on

893

file system using hard links and hard-link-breaking-on-write

894

tricks. <span class="command"><strong>pbuilder</strong></span> using

895

<span class="command"><strong>cowdancer</strong></span> seems to be much faster and it is

896

one ideal point for improvement.

897

<span class="command"><strong>cowbuilder</strong></span>, a wrapper for

898

<span class="command"><strong>pbuilder</strong></span> for using

899

<span class="command"><strong>cowdancer</strong></span> is available from

900

<span class="command"><strong>cowdancer</strong></span> package since 0.14

901

</p><p>

902

Example command-lines for cowbuilder look like the following.

903

</p><p>

904

</p><pre class="screen">

905

# cowbuilder --create --distribution sid

906

# cowbuilder --update --distribution sid

907

# cowbuilder --build XXX.dsc</pre><p>

908

</p><p>

909

It is also possible to use cowdancer with pdebuild command.

910

Specify with command-line option <code class="option">--pbuilder</code>

911

or set it in PDEBUILD_PBUILDER configuration option.

912

</p><p>

913

</p><pre class="screen">

914

$ pdebuild --pbuilder cowbuilder</pre><p>

915

</p></div><div class="sect1" title="3.�Using pbuilder without tar.gz"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="withouttargz"></a>3.�Using pbuilder without tar.gz</h2></div></div></div><p>

916

The <span class="command"><strong><code class="option">--no-targz</code></strong></span>

917

option of <span class="command"><strong>pbuilder</strong></span>

918

will allow usage of <span class="command"><strong>pbuilder</strong></span> in a different way

919

from conventional usage.

920

It will try to use an existing chroot,

921

and will not try to clean up after

922

working on it.

923

It is an operation mode more like

924

<span class="command"><strong>sbuild</strong></span>.

925

</p><p>

926

It should be possible to create base chroot images

927

for <span class="command"><strong>dchroot</strong></span> with the following commands:

928

</p><pre class="screen">

929

# pbuilder create --distribution lenny --no-targz --basetgz /chroot/lenny

930

# pbuilder create --distribution squeeze --no-targz --basetgz /chroot/squeeze

931

# pbuilder create --distribution sid --no-targz --basetgz /chroot/sid</pre><p>

932

</p></div><div class="sect1" title="4.�Using pbuilder in a vserver"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="inavserver"></a>4.�Using pbuilder in a vserver</h2></div></div></div><p>

933

It is possible to use <span class="command"><strong>pbuilder</strong></span> in a vserver

934

environment. This requires either vserver-patches in version 2.1.1-rc14

935

or higher, or a Linux kernel version 2.6.16 or higher.

936

</p><p>

937

To use <span class="command"><strong>pbuilder</strong></span> in a vserver, you need to set the

938

<span class="command"><strong>secure_mount</strong></span> <span class="command"><strong>CAPS</strong></span> in the

939

<span class="command"><strong>ccapabilities</strong></span> of this vserver.

940

</p></div><div class="sect1" title="5.�Usage of ccache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ccache"></a>5.�Usage of ccache</h2></div></div></div><p>

941

It is possible to use C compiler cache

942

<span class="command"><strong>ccache</strong></span> to speed up repeated builds of the same

943

package (or packages that compile the same files multiple times for some

944

reason). Using <span class="command"><strong>ccache</strong></span> can speed up repeated building

945

of large packages dramatically, at the cost of some disk space and

946

bookkeeping.

947

</p><p>

948

To enable usage of <span class="command"><strong>ccache</strong></span> with

949

<span class="command"><strong>pbuilder</strong></span>, you should set CCACHEDIR in your

950

pbuilderrc file.

951

</p><p>

952

Current implementation of ccache support has several bugs,

953

that CCACHEDIR must be owned by the pbuilder build user, and

954

parallel runs of pbuilder is not supported. Therefore it is

955

not enabled by default.

956

</p></div></div><div class="chapter" title="Chapter�8.�Reference materials"><div class="titlepage"><div><div><h2 class="title"><a name="refs"></a>Chapter�8.�Reference materials</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#dirstructoutside">1. Directory structure outside the chroot</a></span></dt><dt><span class="sect1"><a href="#dirstructinside">2. Directory structure inside the chroot</a></span></dt></dl></div><div class="sect1" title="1.�Directory structure outside the chroot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirstructoutside"></a>1.�Directory structure outside the chroot</h2></div></div></div><div class="table"><a name="idp57833296"></a><p class="title"><b>Table�8.1.�Directory Structure outside the chroot </b></p><div class="table-contents"><table summary="Directory Structure outside the chroot " border="1"><colgroup><col align="left" class="c1"><col align="left" class="c2"></colgroup><thead><tr><th align="left">Directory</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><code class="filename">/etc/pbuilderrc</code></td><td align="left">configuration file</td></tr><tr><td align="left"><code class="filename">/usr/share/pbuilder/pbuilderrc</code></td><td align="left">Default configuration</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/base.tgz</code></td><td align="left">Default location pbuilder uses for base.tgz, the tar-ball containing a basic Debian installation

957

with only the build-essential packages.

958

</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/build/PID/</code></td><td align="left">Default location pbuilder uses for chroot</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/aptcache</code></td><td align="left">Default location <span class="command"><strong>pbuilder</strong></span> will use as apt cache, to store deb packages required during <span class="command"><strong>pbuilder</strong></span> build.</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/ccache</code></td><td align="left">Default location <span class="command"><strong>pbuilder</strong></span> will use as

959

cache location</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/result</code></td><td align="left">Default location <span class="command"><strong>pbuilder</strong></span> puts the deb files and other files created after build</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/pbuilder-umlresult</code></td><td align="left">Default location <span class="command"><strong>pbuilder-user-mode-linux</strong></span> puts the deb files and other files created after build </td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/pbuilder-mnt</code></td><td align="left">Default location <span class="command"><strong>pbuilder-user-mode-linux</strong></span> uses for mounting the COW file system, for chrooting.</td></tr><tr><td align="left"><code class="filename">/tmp</code></td><td align="left"><span class="command"><strong>pbuilder-user-mode-linux</strong></span> will mount tmpfs for work.</td></tr><tr><td align="left"><code class="filename">${HOME}/tmp/PID.cow</code></td><td align="left"><span class="command"><strong>pbuilder-user-mode-linux</strong></span> use this directory for location of COW file system.</td></tr><tr><td align="left"><code class="filename">${HOME}/uml-image</code></td><td align="left"><span class="command"><strong>pbuilder-user-mode-linux</strong></span> use this directory for user-mode-linux full disk image.</td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect1" title="2.�Directory structure inside the chroot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dirstructinside"></a>2.�Directory structure inside the chroot</h2></div></div></div><div class="table"><a name="idp57863936"></a><p class="title"><b>Table�8.2.�Directory Structure inside the chroot </b></p><div class="table-contents"><table summary="Directory Structure inside the chroot " border="1"><colgroup><col align="left" class="c1"><col align="left" class="c2"></colgroup><thead><tr><th align="left">Directory</th><th align="left">Meaning</th></tr></thead><tbody><tr><td align="left"><code class="filename">/etc/mtab</code></td><td align="left">

960

symlink to <code class="filename">/proc/mounts</code>.

961

</td></tr><tr><td align="left"><code class="filename">/tmp/buildd</code></td><td align="left">Default place used in <span class="command"><strong>pbuilder</strong></span>

962

to place the Debian package to be processed.

963

<code class="filename">/tmp/buildd/packagename-version/</code>

964

will be the root directory of the package being

965

processed. HOME environment variable is set to this

966

value inside chroot by pbuilder-buildpackage.

967

<code class="option">--inputfile</code> will place files here.

968

</td></tr><tr><td align="left"><code class="filename">/runscript</code></td><td align="left">The

969

script passed as an argument to

970

<span class="command"><strong>pbuilder</strong></span> execute is passed on.

971

</td></tr><tr><td align="left"><code class="filename">/tmp/hooks</code></td><td align="left">

972

The location of hooks.

973

</td></tr><tr><td align="left"><code class="filename">/var/cache/apt/archives</code></td><td align="left">

974

<span class="command"><strong>pbuilder</strong></span> copies the content of this directory to and from

975

the aptcache directory of outside chroot.

976

</td></tr><tr><td align="left"><code class="filename">/var/cache/pbuilder/ccache</code></td><td align="left">

977

<span class="command"><strong>pbuilder</strong></span> bind-mounts this directory for use

978

by ccache.

979

</td></tr><tr><td align="left"><code class="filename">/tmp/XXXX</code></td><td align="left"><span class="command"><strong>pbuilder-user-mode-linux</strong></span> uses

980

a script in <code class="filename">/tmp</code> to bootstrap into

981

user-mode-linux</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="chapter" title="Chapter�9.�Minor archaeological details"><div class="titlepage"><div><div><h2 class="title"><a name="idp57886192"></a>Chapter�9.�Minor archaeological details</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#idp57886832">1. Documentation history </a></span></dt><dt><span class="sect1"><a href="#pbuilderbackgroundhistory">2. Possibly inaccurate Background History of pbuilder</a></span></dt><dd><dl><dt><span class="sect2"><a href="#idp57896896">2.1. The Time Before pbuilder</a></span></dt><dt><span class="sect2"><a href="#birth">2.2. Birth of pbuilder</a></span></dt><dt><span class="sect2"><a href="#secondyear">2.3. And the second year of its life</a></span></dt><dt><span class="sect2"><a href="#fifthyear">2.4. Fifth year of pbuilder</a></span></dt></dl></dd></dl></div><div class="sect1" title="1.�Documentation history"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp57886832"></a>1.�Documentation history </h2></div></div></div><p>

982

This document was started on 28 Dec 2002 by

983

Junichi Uekawa, trying to document what is known

984

about <span class="command"><strong>pbuilder</strong></span>.

985

</p><p>

986

This documentation is available from the <span class="command"><strong>pbuilder</strong></span> source tar-ball,

987

and from the git repository of <span class="command"><strong>pbuilder</strong></span> (web-based access is possible).

988

A copy of this documentation can be found on the

989

<a class="ulink" href="http://pbuilder.alioth.debian.org/pbuilder-doc.html" target="_top">Alioth project page for pbuilder</a>.

990

<a class="ulink" href="http://pbuilder.alioth.debian.org/pbuilder-doc.pdf" target="_top">There is also a PDF version</a>.

991

The homepage for <span class="command"><strong>pbuilder</strong></span> is

992

993

http://pbuilder.alioth.debian.org/

994

</a> hosted by alioth project.

995

</p><p>

996

Documentation is written using DocBook XML,

997

with emacs PSGML mode, and using wysidocbookxml for live

998

previewing.

999

</p></div><div class="sect1" title="2.�Possibly inaccurate Background History of pbuilder"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="pbuilderbackgroundhistory"></a>2.�Possibly inaccurate Background History of pbuilder</h2></div></div></div><p>

1000

The following is a most possibly inaccurate account of how

1001

<span class="command"><strong>pbuilder</strong></span> came to happen, and other attempts to

1002

make something like <span class="command"><strong>pbuilder</strong></span> happen.

1003

This part of the document was originally in the AUTHORS file,

1004

to give credit to those who existed before <span class="command"><strong>pbuilder</strong></span>.

1005

</p><div class="sect2" title="2.1.�The Time Before pbuilder"><div class="titlepage"><div><div><h3 class="title"><a name="idp57896896"></a>2.1.�The Time Before pbuilder</h3></div></div></div><p>

1006

There was once dbuild, which was a shell script to build

1007

Debian packages from source. Lars Wirzenius wrote that

1008

script, and it was good, short, and simple (probably).

1009

There was nothing like build-depends then (I think), and it was simple.

1010

It could have been improved, I could only find references and no actual source.

1011

</p><p>

1012

debbuild was probably written by James Troup. I don't know it

1013

because I have never seen the actual code, I could only find some

1014

references to it on the net, and mailing list logs.

1015

</p><p>

1016

sbuild is a perl script to build Debian packages from source.

1017

It parses Build-Depends, and performs other miscellaneous checks,

1018

and has a lot of hacks to actually get things building,

1019

including a table of what package to use when virtual packages are

1020

specified (does it do that still?).

1021

It supports the use of a local database for packages which do not

1022

have build-dependencies. It was written by Ronan Hodek,

1023

and I think it was patched and fixed and extended by

1024

several people. It is part of wanna-build, and used extensively

1025

in the Debian buildd system. I think it was maintained

1026

mostly by Ryan Murray.

1027

</p></div><div class="sect2" title="2.2.�Birth of pbuilder"><div class="titlepage"><div><div><h3 class="title"><a name="birth"></a>2.2.�Birth of pbuilder</h3></div></div></div><p>

1028

wanna-build (sbuild) was (at the time of year 2001) quite

1029

difficult to set up, and it was never a Debian

1030

package. dbuild was something that predated Build-Depends.

1031

</p><p>

1032

Building packages from source using Build-Depends

1033

information within a chroot sounded trivial; and

1034

<span class="command"><strong>pbuilder</strong></span> was born. It was initially a shell script

1035

with only a few lines, which called debootstrap

1036

and chroot and dpkg-buildpackage in the same run,

1037

but soon, it was decided that that's too slow.

1038

</p><p>

1039

Yes, and it took almost an year to get things somewhat

1040

right, and in the middle of the process, Debian 3.0

1041

was released. Yay.

1042

Debian 3.0 wasn't completely buildable with <span class="command"><strong>pbuilder</strong></span>,

1043

but the amount of packages which are not buildable

1044

is steadily decreasing (I hope).

1045

</p></div><div class="sect2" title="2.3.�And the second year of its life"><div class="titlepage"><div><div><h3 class="title"><a name="secondyear"></a>2.3.�And the second year of its life</h3></div></div></div><p>

1046

Someone wanted <span class="command"><strong>pbuilder</strong></span> to not run as

1047

root, and as User-mode-linux has become more useful as time

1048

passed, I've started experimenting with

1049

<span class="command"><strong>pbuilder-user-mode-linux</strong></span>.

1050

<span class="command"><strong>pbuilder-user-mode-linux</strong></span> has not stayed

1051

functional as much as I would have liked, and bootstrapping

1052

<span class="command"><strong>user-mode-linux</strong></span> environment has been

1053

pretty hard, due to the quality of user-mode-linux code or

1054

packaging at that time, which kept on breaking network

1055

support in one way or the other.

1056

</p></div><div class="sect2" title="2.4.�Fifth year of pbuilder"><div class="titlepage"><div><div><h3 class="title"><a name="fifthyear"></a>2.4.�Fifth year of pbuilder</h3></div></div></div><p>

1057

<span class="command"><strong>pbuilder</strong></span> is now widely adopted as a 'almost standard' tool

1058

for testing packages, and building packages in a pristine

1059

environment. There are other similar tools that do similar

1060

tasks, but they do not share the exact same goal. To

1061

commemorate this fact, <span class="command"><strong>pbuilder</strong></span> is now co-maintained with

1062

several people.

1063

</p><p>

1064

<span class="command"><strong>sbuild</strong></span> is now a well-maintained Debian package within

1065

Debian, and with <span class="command"><strong>pbuilder</strong></span> being such a slow monster, some

1066

people prefer the approach of sbuild. Development to use

1067

LVM-snapshots, cowloop, or cowdancer is hoped to improve the

1068

situation somewhat.

1069

</p></div></div></div></div></body></html>