[gentoo-dev] how to use die() and assert_true_or_die()

[Chris Houser]

Okay, here's some quick documentation on Aron Griffis' new "exception
handling" functions.  I am confidant Aron will correct any mistakes I
make here.


Although try() still exists, there are two new functions available that
are much better.  For a details on why try() should be deprecated, and
for more examples of how to use these functions in less common
situations, see Aron's earlier messages.  Note that these new functions
give more detailed error messages than try() did.

--- Simple die() --
In most cases where you used to use try(), you should now use die().
For example, the Development HOWTO has the following:

    try ./configure ${myvar} --prefix=/usr --host=${CHOST}

To use die() instead, use this syntax:

    ./configure ${myvar} --prefix=/usr --host=${CHOST} || die

You may optionally include a message to describe what failed:

    ./configure ${myvar} --prefix=/usr --host=${CHOST} || die "Bad configure"


--- Pipelined die() --
If you want to check the results of a pipelined command, you may
only need to attach die to the last command.  This is often sufficient
because if commands earlier in the pipeline fail, later commands often
fail as well:

    bzip2 -dc ${DISTDIR}/patch-${KV}.bz2 | patch -p0 || die

However, it is possible for earlier commands to fail and for later ones
to succeed anyway.  This example, for instance, will appear to succeed
if the patch file does not exists.  So, to make sure your .ebuild
catches this type of situation, you can attach die to each command of
the pipeline:

    ( bzip2 -dc ${DISTDIR}/patch-${KV}.bz2 || die ) | ( patch -p0 || die )


--- assert_true_or_die() --
This function is meant to be used when you don't want to make long
commands even longer by adding the "|| die" syntax.  To use it, simply
add the function call after the command you want to check:

    ./configure ${myvar} --prefix=/usr --host=${CHOST}
    assert_true_or_die "Bad configure"

Note that using the function this way doesn't allow you to check
multiple commands in a pipeline the way die() does.

--Chouser