Document the new --jobs and --load-average options for parallelization.

svn path=/main/trunk/; revision=11014

3 files changed, 37 insertions, 5 deletions

diff --git a/NEWS b/NEWS
index df08cf75..d0d7f78f 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,9 @@ News (mainly features/major bug fixes)
 portage-2.2
 -------------
 
+* Add emerge --jobs and --load-average options which specify behavior
+  for building packages in parallel or for generating metadata in parallel
+  with emerge --regen.
 * Add emerge --keep-going option to continue as much as possible after
   an error. When an error occurs, dependencies are recalculated for
   remaining packages and any with unsatisfied dependencies are
diff --git a/man/emerge.1 b/man/emerge.1
index 0dc6884e..fdf94c13 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -165,7 +165,8 @@ differences between a 'rsync user' and some other user, then you are a 'rsync
 user' :).  Rsync users should simply run \fBemerge \-\-sync\fR to regenerate 
 the cache.  After a portage update, rsync users may find it convenient to run 
 \fBemerge \-\-metadata\fR to rebuild the cache as portage does at the end of 
-a sync operation.
+a sync operation. In order to specify parallel \fB\-\-regen\fR behavior, use
+the \fB\-\-jobs\fR and \fB\-\-load\-average\fR options.
 .TP
 .BR "\-\-resume"
 Resumes the most recent merge list that has been aborted due to an error.
@@ -321,12 +322,20 @@ directory.
 .BR "\-\-ignore-default-opts"
 Causes \fIEMERGE_DEFAULT_OPTS\fR (see \fBmake.conf\fR(5)) to be ignored.
 .TP
+.BR \-\-jobs=JOBS
+Specifies the number of packages to build simultaneously. Also see
+the related \fB\-\-load\-average\fR option.
+.TP
 .BR "\-\-keep\-going"
 Continue as much as possible after an error. When an error occurs,
 dependencies are recalculated for remaining packages and any with
 unsatisfied dependencies are automatically dropped. Also see
 the related \fB\-\-skipfirst\fR option.
 .TP
+.BR \-\-load\-average=LOAD
+Specifies that no new builds should be started if there are other builds
+running and the load average is at least LOAD (a floating-point number).
+.TP
 .BR "\-\-newuse " (\fB\-N\fR)
 Tells emerge to include installed packages where USE flags have changed since 
 compilation.  USE flag changes include:
diff --git a/pym/_emerge/help.py b/pym/_emerge/help.py
index 27e150d8..756f9156 100644
--- a/pym/_emerge/help.py
+++ b/pym/_emerge/help.py
@@ -15,10 +15,11 @@ def shorthelp():
 	print "   "+turquoise("emerge")+" "+turquoise("--resume")+" [ "+green("--pretend")+" | "+green("--ask")+" | "+green("--skipfirst")+" ]"
 	print "   "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("system")+" | "+green("world")+" | "+green("--sync")+" ] "
 	print bold("Options:")+" "+green("-")+"["+green("abBcCdDefgGhkKlnNoOpqPsStuvV")+"]"
-	print "          [ "+green("--columns")+"   ] [ "+green("--deep")+"      ] [ "+green("--keep-going")+" ] [ "+green("--newuse")+"   ]"
-	print "          [ "+green("--noconfmem")+" ] [ "+green("--nospinner")+" ] [ "+green("--oneshot")+"    ]"
-	print "          [ " + green("--color")+" < " + turquoise("y") + " | "+ turquoise("n")+" >           ] [ "+green("--complete-graph")+"            ]"
-	print "          [ "+green("--reinstall ")+turquoise("changed-use")+"     ] [ " + green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" >      ]"
+	print "          [ " + green("--color")+" < " + turquoise("y") + " | "+ turquoise("n")+" >            ] [ "+green("--columns")+"    ]"
+	print "          [ "+green("--complete-graph")+"             ] [ "+green("--deep")+"       ]"
+	print "          [ "+green("--jobs") + " " + turquoise("JOBS")+" ] [ "+green("--keep-going")+" ] [ " + green("--load-average")+" " + turquoise("LOAD") + "            ]"
+	print "          [ "+green("--newuse")+"    ] [ "+green("--noconfmem")+"  ] [ "+green("--nospinner")+"  ] [ "+green("--oneshot")+"     ]"
+	print "          [ "+green("--reinstall ")+turquoise("changed-use")+"      ] [ " + green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" >         ]"
 	print bold("Actions:")+"  [ "+green("--clean")+" | "+green("--depclean")+" | "+green("--prune")+" | "+green("--regen")+" | "+green("--search")+" | "+green("--unmerge")+" ]"
 
 def help(myaction,myopts,havecolor=1):
@@ -127,6 +128,10 @@ def help(myaction,myopts,havecolor=1):
 		print "              ebuilds in the portage tree. This is not recommended for rsync"
 		print "              users as rsync updates the cache using server-side caches."
 		print "              Rsync users should simply 'emerge --sync' to regenerate."
+		desc = "In order to specify parallel --regen behavior, use "+ \
+			"the ---jobs and --load-average options."
+		for line in wrap(desc, desc_width):
+			print desc_indent + line
 		print
 		print "       "+green("--resume")
 		print "              Resumes the most recent merge list that has been aborted due to an"
@@ -292,6 +297,13 @@ def help(myaction,myopts,havecolor=1):
 		print "              downloaded from the remote server without consulting packages"
 		print "              existing in the packages directory."
 		print
+		print "       " + green("--jobs") + " " + turquoise("JOBS")
+		desc = "Specifies the number of packages " + \
+			"to build simultaneously. Also see " + \
+			"the related --load-average option."
+		for line in wrap(desc, desc_width):
+			print desc_indent + line
+		print
 		print "       "+green("--keep-going")
 		desc = "Continue as much as possible after " + \
 			"an error. When an error occurs, " + \
@@ -303,6 +315,14 @@ def help(myaction,myopts,havecolor=1):
 		for line in wrap(desc, desc_width):
 			print desc_indent + line
 		print
+		print "       " + green("--load-average") + " " + turquoise("LOAD")
+		desc = "Specifies that no new builds should " + \
+			"be started if there are other builds " + \
+			"running and the load average is at " + \
+			"least LOAD (a floating-point number)."
+		for line in wrap(desc, desc_width):
+			print desc_indent + line
+		print
 		print "       "+green("--newuse")+" ("+green("-N")+" short option)"
 		print "              Tells emerge to include installed packages where USE flags have "
 		print "              changed since installation."