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 Portage's elog functionality. On a colour terminal, the message provided will be prefixed with a green asterisk.

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 || die
}

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.

QA warnings

The eqawarn function can be used by eclass authors to notify ebuild writers about deprecated functionality. 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.

Message function reference

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:

eqawarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
eqawarn "in favour of frozbinate.eclass, but this package has not been"
eqawarn "updated yet. If this is a package from the main tree, please check"
eqawarn "https://bugs.gentoo.org/ and file a bug if there is not one already."
eqawarn "If this is your own package, please read the comments in the"
eqawarn "frozbinate eclass for instructions on how to convert."