1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
<?xml version="1.0"?>
<guide self="ebuild-writing/error-handling/">
<chapter>
<title>Error Handling</title>
<section>
<title>Importance of Error Handling</title>
<body>
<p>
Decent error handling is important because:
</p>
<ul>
<li>
Errors must be detected <e>before</e> portage tries to install a broken or
incomplete package onto the live filesystem. If build failures aren't caught,
a working package could be unmerged and replaced with nothing.
</li>
<li>
When receiving bug reports, it is a lot easier to figure out what went wrong
if you know exactly which call caused the error, rather than just knowing
that, say, something somewhere in <c>src_compile</c> broke.
</li>
<li>
Good error handling and notification can help cut down on the number of bug
reports received for a package.
</li>
</ul>
</body>
</section>
<section>
<title>The <c>die</c> Function</title>
<body>
<p>
The <c>die</c> function should be used to indicate a fatal error and abort the
build. Its parameters should be the message to display.
</p>
<p>
Although <c>die</c> will work with no parameters, a short message should always be
provided to ease error identification. This is especially important when a
function can die in multiple places.
</p>
<p>
Some portage-provided functions will automatically die upon failure. Others will
not. It is safe to omit the <c>|| die</c> after a call to <c>epatch</c>, but not
<c>econf</c> or <c>emake</c>.
</p>
<p>
Sometimes displaying additional error information beforehand can be useful. Use
<c>eerror</c> to do this. See `Messages`_.
</p>
</body>
</section>
<section>
<title><c>die</c> and Subshells</title>
<body>
<warning>
<c>die</c> <b>will not work in a subshell</b>.
</warning>
<p>
The following code will not work as expected, since the <c>die</c> is inside a
subshell:
</p>
<codesample lang="ebuild">
[[ -f foorc ]] && ( update_foorc || die "Couldn't update foorc!" )
</codesample>
<p>
The correct way to rewrite this is to use an <c>if</c> block:
</p>
<codesample lang="ebuild">
if [[ -f foorc ]] ; then
update_foorc || die "Couldn't update foorc!"
fi
</codesample>
<p>
When using pipes, a subshell is introduced, so the following is unsafe:
</p>
<codesample lang="ebuild">
cat list | while read file ; do epatch ${file} ; done
</codesample>
<p>
Using input redirection (see `Abuse of cat`_) avoids this problem:
</p>
<codesample lang="ebuild">
while read file ; do epatch ${file} ; done < list
</codesample>
</body>
</section>
<section>
<title>The <c>assert</c> Function and <c>$PIPESTATUS</c></title>
<body>
<p>
When using pipes, simple conditionals and tests upon <c>$?</c> will not correctly
detect errors occurring in anything except the final command in the chain. To get
around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and portage
provides the <c>assert</c> function to check this variable.
</p>
<codesample lang="ebuild">
bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf
assert
</codesample>
<p>
If you need the gory details of <c>$PIPESTATUS</c>, see the bash manpage. Most of the
time, <c>assert</c> is enough.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb