reStructuredText source of the devmanual

Taken from ~sekretarz/public_html/devmanual.tar.bz on dev.gentoo.org
and removed all generated HTML, PNG, and temporary files.

Timestamp of oldest file: 2005-06-04 11:50:45 +0000
Timestamp of newest file: 2005-07-12 17:21:19 +0000

Signed-off-by: Ulrich Müller <ulm@gentoo.org>

6 files changed, 90 insertions, 0 deletions

diff --git a/ebuild-writing/error-handling/error-handling-1.ebuild b/ebuild-writing/error-handling/error-handling-1.ebuild
new file mode 100644
index 0000000..317029c
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-1.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+[[ -f foorc ]] && ( update_foorc || die "Couldn't update foorc!" )
diff --git a/ebuild-writing/error-handling/error-handling-2.ebuild b/ebuild-writing/error-handling/error-handling-2.ebuild
new file mode 100644
index 0000000..7ac1b45
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-2.ebuild
@@ -0,0 +1,5 @@
+# Header
+
+if [[ -f foorc ]] ; then
+	update_foorc || die "Couldn't update foorc!"
+fi
diff --git a/ebuild-writing/error-handling/error-handling-3.ebuild b/ebuild-writing/error-handling/error-handling-3.ebuild
new file mode 100644
index 0000000..daf667f
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-3.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+cat list | while read file ; do epatch ${file} ; done
diff --git a/ebuild-writing/error-handling/error-handling-4.ebuild b/ebuild-writing/error-handling/error-handling-4.ebuild
new file mode 100644
index 0000000..ff45221
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-4.ebuild
@@ -0,0 +1,3 @@
+# Header
+
+while read file ; do epatch ${file} ; done < list
diff --git a/ebuild-writing/error-handling/error-handling-5.ebuild b/ebuild-writing/error-handling/error-handling-5.ebuild
new file mode 100644
index 0000000..af0133f
--- /dev/null
+++ b/ebuild-writing/error-handling/error-handling-5.ebuild
@@ -0,0 +1,4 @@
+# Header
+
+bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf
+assert
diff --git a/ebuild-writing/error-handling/text.rst b/ebuild-writing/error-handling/text.rst
new file mode 100644
index 0000000..5e27eab
--- /dev/null
+++ b/ebuild-writing/error-handling/text.rst
@@ -0,0 +1,72 @@
+Error Handling
+==============
+
+Importance of Error Handling
+----------------------------
+
+Decent error handling is important because:
+
+* Errors must be detected *before* 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.
+
+* When receiving bug reports, it is a lot easier to figure out what went wrong
+  if you know exactly which function caused the error, rather than just knowing
+  that, say, something somewhere in ``src_compile`` broke.
+
+* Good error handling and notification can help cut down on the number of bug
+  reports received for a package.
+
+The ``die`` Function
+--------------------
+
+The ``die`` function should be used to indicate a fatal error and abort the
+build. Its parameters should be the message to display.
+
+Although ``die`` 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.
+
+Some portage-provided functions will automatically die upon failure. Others will
+not. It is safe to omit the ``|| die`` after a call to ``epatch``, but not
+``econf`` or ``emake``.
+
+Sometimes displaying additional error information beforehand can be useful. Use
+``eerror`` to do this. See `Messages`_.
+
+``die`` and Subshells
+---------------------
+
+.. Warning:: ``die`` **will not work in a subshell**.
+
+The following code will not work as expected, since the ``die`` is inside a
+subshell:
+
+.. CODESAMPLE error-handling-1.ebuild
+
+The correct way to rewrite this is to use an ``if`` block:
+
+.. CODESAMPLE error-handling-2.ebuild
+
+When using pipes, a subshell is introduced, so the following is unsafe:
+
+.. CODESAMPLE error-handling-3.ebuild
+
+Using input redirection (see `Abuse of cat`_) avoids this problem:
+
+.. CODESAMPLE error-handling-4.ebuild
+
+The ``assert`` Function and ``$PIPESTATUS``
+-------------------------------------------
+
+When using pipes, simple conditionals and tests upon ``$?`` will not correctly
+detect errors occurring in anything except the final command in the chain. To get
+around this, ``bash`` provides the ``$PIPESTATUS`` variable, and portage
+provides the ``assert`` function to check this variable.
+
+.. CODESAMPLE error-handling-5.ebuild
+
+If you need the gory details of ``$PIPESTATUS``, see `bash-1`_. Most of the
+time, ``assert`` is enough.
+
+.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..