1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
<?xml version="1.0"?>
<guide self="ebuild-writing/messages/">
<chapter>
<title>Messages</title>
<body>
<p>
Sometimes it is necessary to display messages for the user. This can be for
errors, post-install help messages, pre-install warnings or simply to notify the
user of what's going on. It is considered good form to display a message
before any particularly long and silent task is carried out, for example (and it
also helps cut down on bogus "compiling foo froze!" bugs).
</p>
<note>
It is a policy violation to use any of these functions to display a line
of characters (a banner header). The use of colours and special leading
characters provided by these functions is sufficient to make a message stand
out.
</note>
<p>
In all cases, assume that the user's terminal is no wider than 79 columns, and
that the <c>elog</c>,<c>einfo</c>, <c>ewarn</c> and <c>eerror</c> functions will
occupy 4 columns with their fancy leading markers.
</p>
</body>
<section>
<title>Information Messages</title>
<body>
<p>
There are a number of functions available to assist here. The `echo` bash
internal is the simplest <d/> it simply displays its parameters as a message.
</p>
<p>
The <c>elog</c> function can be used to display an informational message which is
meant to 'stand out' and is logged by the elog functionality in Portage 2.1 and
Paludis 0.6 or newer. On a colour terminal, the message provided will be prefixed
with a green asterisk. On earlier versions, elog behaves just like einfo.
</p>
<codesample lang="ebuild">
pkg_postinst() {
elog "You will need to set up your /etc/foo/foo.conf file before"
elog "running foo for the first time. For details, please see the"
elog "foo.conf(5) manual page."
}
</codesample>
<p>
The <c>einfo</c> function can be used to display an informational message which is
meant to 'stand out'. On a colour terminal, the message provided will be
prefixed with a green asterisk. einfo messages go to the INFO elog class which is not
logged by default.
</p>
<codesample lang="ebuild">
src_compile() {
einfo "Starting a silent compile that takes hours."
./build
}
</codesample>
</body>
</section>
<section>
<title>Warning Messages</title>
<body>
<p>
The <c>ewarn</c> function is similar, but displays a yellow asterisk. This should be
used for warning messages rather than information.
</p>
</body>
</section>
<section>
<title>Error Messages</title>
<body>
<p>
The <c>eerror</c> function displays a red star, and is used for displaying error
messages. It should almost always be followed by a <c>die</c> call. This function
is mainly used for displaying additional error details before bailing out.
</p>
</body>
</section>
<section>
<title>QA warnings</title>
<body>
<p>
The <c>eqawarn</c> function can be used by eclass authors to notify ebuild writers about
deprecated functionality. eqawarn is defined in eutils. Portage doesn't log the qa message
class by default so users don't get annoyed by seeing messages they can't do much about.
</p>
</body>
</section>
<section>
<title>Message function reference</title>
<body>
<p>
See <uri link="::function-reference/message-functions/"/> for a full list of functions.
</p>
</body>
</section>
<section>
<title>Good and Bad Messages</title>
<body>
<p>
Here is an example of a bad message:
</p>
<codesample lang="ebuild">
i=10
while ((i--)) ; do
ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
done
</codesample>
<ul>
<li>Displaying the same message repeatedly is excessive.</li>
<li>The uppercase is excessive.</li>
<li>The bad English looks unprofessional.</li>
<li>
The message will only confuse the end user and will not help them work out
whether they have a problem and how to solve it if they do.
</li>
</ul>
<p>
It would be better written as:
</p>
<codesample lang="ebuild">
ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
ewarn "in favour of frozbinate.eclass, but this package has not been"
ewarn "updated yet. If this is a package from the main tree, please check"
ewarn "https://bugs.gentoo.org/ and file a bug if there is not one already."
ewarn "If this is your own package, please read the comments in the"
ewarn "frozbinate eclass for instructions on how to convert."
</codesample>
</body>
</section>
</chapter>
</guide>
|
GitWeb