Gentoo Development Guide

Messages

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).

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.

In all cases, assume that the user's terminal is no wider than 79 columns, and that the elog,einfo, ewarn and eerror functions will occupy 4 columns with their fancy leading markers.

Information Messages

There are a number of functions available to assist here. The `echo` bash internal is the simplest — it simply displays its parameters as a message.

The elog 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.

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."
}

The einfo 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.

src_compile() {
    einfo "Starting a silent compile that takes hours."
    ./build
}

Warning Messages

The ewarn function is similar, but displays a yellow asterisk. This should be used for warning messages rather than information.

Error Messages

The eerror function displays a red star, and is used for displaying error messages. It should almost always be followed by a die call. This function is mainly used for displaying additional error details before bailing out.

Important Messages

For really important messages, eutils.eclass provides ebeep and epause. The former will beep a number of times, and the latter will pause for several seconds to allow the user to read any messages. Both can be disabled by the user — you must not attempt to override the user's preference in this. ebeep takes an optional parameter specifying how many times to beep. epause takes an optional parameter (which must be an exact whole number) specifying for how long it should sleep.

Do not abuse these functions — better to save them for when things really are important.

See Message Functions Reference for a full list of functions.

Good and Bad Messages

Here is an example of a bad message:

i=10
while ((i--)) ; do
    ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
done

Displaying the same message repeatedly is excessive.
The uppercase is excessive.
The bad English looks unprofessional.
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.

It would be better written as:

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 "http://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."

← Users and Groups

↑ Ebuild Writing ↑

Variables →