emake: refresh comments/docs/style

The comments for this code is woefully out of date.  The man page too
has not been updated in a long time to reflect the latest behavior.

2 files changed, 31 insertions, 19 deletions

diff --git a/bin/ebuild-helpers/emake b/bin/ebuild-helpers/emake
index 4618053bf..2a3c2f09e 100755
--- a/bin/ebuild-helpers/emake
+++ b/bin/ebuild-helpers/emake
@@ -1,19 +1,23 @@
 #!/bin/bash
-# Copyright 1999-2010 Gentoo Foundation
+# Copyright 1999-2015 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 #
-# emake: Supplies some default parameters to GNU make. At the moment the
-#        only parameter supplied is -jN, where N is a number of
-#        parallel processes that should be ideal for the running host
-#        (e.g. on a single-CPU machine, N=2).  The MAKEOPTS variable
-#        is set in make.globals. We don't source make.globals
-#        here because emake is only called from an ebuild.
+# emake: Run make and automatically pass along flags set in the env.  We support
+# MAKEOPTS & EXTRA_EMAKE which allows the user to customize behavior (such as
+# parallel builds and load limiting).  The latter overrides the ebuild and thus
+# should be used with caution (more a debugging knob).
+#
+# With newer EAPIs, we also automatically fail the build if make itself fails.
 
 source "${PORTAGE_BIN_PATH:-/usr/lib/portage/bin}"/isolated-functions.sh
 
-if [[ $PORTAGE_QUIET != 1 ]] ; then
+cmd=(
+	${MAKE:-make} ${MAKEOPTS} "$@" ${EXTRA_EMAKE}
+)
+
+if [[ ${PORTAGE_QUIET} != 1 ]] ; then
 	(
-	for arg in ${MAKE:-make} $MAKEOPTS "$@" $EXTRA_EMAKE ; do
+	for arg in "${cmd[@]}" ; do
 		[[ ${arg} == *" "* ]] \
 			&& printf "'%s' " "${arg}" \
 			|| printf "%s " "${arg}"
@@ -22,7 +26,7 @@ if [[ $PORTAGE_QUIET != 1 ]] ; then
 	) >&2
 fi
 
-${MAKE:-make} ${MAKEOPTS} "$@" ${EXTRA_EMAKE}
+"${cmd[@]}"
 ret=$?
-[[ $ret -ne 0 ]] && __helpers_die "${0##*/} failed"
-exit $ret
+[[ ${ret} -ne 0 ]] && __helpers_die "${0##*/} failed"
+exit ${ret}
diff --git a/man/ebuild.5 b/man/ebuild.5
index 7049f1727..6a27cc527 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -1189,16 +1189,24 @@ string \fIdisable\-silent\-rules\fR occurs in the output
 of \fIconfigure \-\-help\fR.
 .TP
 .B emake\fR \fI[make options]
-This is used as a replacement for make.  Performs 'make ${MAKEOPTS}
-\fImake options\fR' (as set in make.globals), default is MAKEOPTS="\-j2".
+This must be used in place of `make` in ebuilds.  Performs `${MAKE:-make}
+${MAKEOPTS} \fImake options\fR ${EXTRA_EMAKE}`, and calls `die` automatically
+starting with \fBEAPI 4\fR.
+
+The \fBMAKEOPTS\fR variable is set by the user so they can enable features such
+as parallel builds; see \fBmake.conf\fR(5) for more details.
+
+The \fBEXTRA_EMAKE\fR knob is portage feature so developers can override things
+while debugging ebuilds; it is not part of any EAPI specification.
 
 .B ***WARNING***
 .br
-if you are going to use \fBemake\fR, make sure your build is happy with
-parallel makes (make \-j2).  It should be tested thoroughly as parallel
-makes are notorious for failing _sometimes_ but not always.  If you determine
-that your package fails to build in parallel, and you are unable to resolve
-the issue, then you should run '\fBemake\fR \-j1' instead of 'make'.
+You must make sure your build is happy with parallel makes (make \-j2).  It
+should be tested thoroughly as parallel makes are notorious for failing
+_sometimes_ but not always.  If you determine that your package fails to build
+in parallel, and you are unable to resolve the issue, then you should run
+`\fBemake\fR \-j1` explicitly.  This is a last resort however as it can
+significantly slow down builds on systems with lots of processors.
 
 .SS "Install:"
 .TP