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

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

diff --git a/NEWS b/NEWS
index df08cf759304c036f1594e44ab2431d902ed0250..d0d7f78fca73a51e40f29a025badc548afd4d85b 100644 (file)
--- 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 0dc6884eff5a8d71f4f76932a163a3fd72fa5a8a..fdf94c13c3a53faa6822ba1a3e4e9a6c0cbdf4f1 100644 (file)
--- 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 27e150d882699c7ca4d4fbe0822d6b4baa2e56d9..756f9156bf253ba04752f3384c7b828bfe3d0e33 100644 (file)
--- 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."