1 # Copyright 1999-2011 Gentoo Foundation
2 # Distributed under the terms of the GNU General Public License v2
4 from __future__ import print_function
6 from portage.const import _ENABLE_DYN_LINK_MAP
7 from portage.output import bold, turquoise, green
10 print(bold("emerge:")+" the other white meat (command-line interface to the Portage system)")
12 print(" "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] [ "+turquoise("ebuild")+" | "+turquoise("tbz2")+" | "+turquoise("file")+" | "+turquoise("@set")+" | "+turquoise("atom")+" ] [ ... ]")
13 print(" "+turquoise("emerge")+" [ "+green("options")+" ] [ "+green("action")+" ] < "+turquoise("system")+" | "+turquoise("world")+" >")
14 print(" "+turquoise("emerge")+" < "+turquoise("--sync")+" | "+turquoise("--metadata")+" | "+turquoise("--info")+" >")
15 print(" "+turquoise("emerge")+" "+turquoise("--resume")+" [ "+green("--pretend")+" | "+green("--ask")+" | "+green("--skipfirst")+" ]")
16 print(" "+turquoise("emerge")+" "+turquoise("--help")+" [ "+green("--verbose")+" ] ")
17 print(bold("Options:")+" "+green("-")+"["+green("abBcCdDefgGhjkKlnNoOpPqrsStuvV")+"]")
18 print(" [ " + green("--color")+" < " + turquoise("y") + " | "+ turquoise("n")+" > ] [ "+green("--columns")+" ]")
19 print(" [ "+green("--complete-graph")+" ] [ "+green("--deep")+" ]")
20 print(" [ "+green("--jobs") + " " + turquoise("JOBS")+" ] [ "+green("--keep-going")+" ] [ " + green("--load-average")+" " + turquoise("LOAD") + " ]")
21 print(" [ "+green("--newuse")+" ] [ "+green("--noconfmem")+" ] [ "+green("--nospinner")+" ]")
22 print(" [ "+green("--oneshot")+" ] [ "+green("--onlydeps")+" ]")
23 print(" [ "+green("--reinstall ")+turquoise("changed-use")+" ] [ " + green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" > ]")
24 print(bold("Actions:")+" [ "+green("--depclean")+" | "+green("--list-sets")+" | "+green("--search")+" | "+green("--sync")+" | "+green("--version")+" ]")
26 def help(myopts, havecolor=1):
27 # TODO: Implement a wrap() that accounts for console color escape codes.
28 from textwrap import wrap
30 desc_indent = desc_left_margin * " "
31 desc_width = 80 - desc_left_margin - 5
32 if "--verbose" not in myopts:
35 print(" For more help try 'emerge --help --verbose' or consult the man page.")
39 print(turquoise("Help (this screen):"))
40 print(" "+green("--help")+" ("+green("-h")+" short option)")
41 print(" Displays this help; an additional argument (see above) will tell")
42 print(" emerge to display detailed help.")
44 print(turquoise("Actions:"))
45 print(" "+green("--clean"))
46 print(" Cleans the system by removing outdated packages which will not")
47 print(" remove functionalities or prevent your system from working.")
48 print(" The arguments can be in several different formats :")
51 print(" * 'dependency specification' (in single quotes is best.)")
52 print(" Here are a few examples of the dependency specification format:")
53 print(" "+bold("binutils")+" matches")
54 print(" binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1")
55 print(" "+bold("sys-devel/binutils")+" matches")
56 print(" binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1")
57 print(" "+bold(">sys-devel/binutils-2.11.90.0.7")+" matches")
58 print(" binutils-2.11.92.0.12.3-r1")
59 print(" "+bold(">=sys-devel/binutils-2.11.90.0.7")+" matches")
60 print(" binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1")
61 print(" "+bold("<=sys-devel/binutils-2.11.92.0.12.3-r1")+" matches")
62 print(" binutils-2.11.90.0.7 and binutils-2.11.92.0.12.3-r1")
64 print(" "+green("--config"))
65 print(" Runs package-specific operations that must be executed after an")
66 print(" emerge process has completed. This usually entails configuration")
67 print(" file setup or other similar setups that the user may wish to run.")
69 print(" "+green("--depclean")+" ("+green("-c")+" short option)")
71 paragraph = "Cleans the system by removing packages that are " + \
72 "not associated with explicitly merged packages. Depclean works " + \
73 "by creating the full dependency tree from the " + \
74 "@world set, then comparing it to installed packages. Packages " + \
75 "installed, but not part of the dependency tree, will be " + \
76 "uninstalled by depclean. See --with-bdeps for behavior with " + \
77 "respect to build time dependencies that are not strictly " + \
78 "required. Packages that are part of the world set will " + \
79 "always be kept. They can be manually added to this set with " + \
80 "emerge --noreplace <atom>. As a safety measure, depclean " + \
81 "will not remove any packages unless *all* required dependencies " + \
82 "have been resolved. As a consequence, it is often necessary to " + \
83 "run emerge --update --newuse --deep @world " + \
86 for line in wrap(paragraph, desc_width):
87 print(desc_indent + line)
90 paragraph = "WARNING: Inexperienced users are advised to use " + \
91 "--pretend with this option in order to see a preview of which " + \
92 "packages will be uninstalled. Always study the list of packages " + \
93 "to be cleaned for any obvious mistakes. Note that packages " + \
94 "listed in package.provided (see portage(5)) may be removed by " + \
95 "depclean, even if they are part of the world set."
97 paragraph += " Also note that " + \
98 "depclean may break link level dependencies"
100 if _ENABLE_DYN_LINK_MAP:
101 paragraph += ", especially when the " + \
102 "--depclean-lib-check option is disabled"
104 paragraph += ". Thus, it is " + \
105 "recommended to use a tool such as revdep-rebuild(1) " + \
106 "in order to detect such breakage."
108 for line in wrap(paragraph, desc_width):
109 print(desc_indent + line)
112 paragraph = "Depclean serves as a dependency aware version of " + \
113 "--unmerge. When given one or more atoms, it will unmerge " + \
114 "matched packages that have no reverse dependencies. Use " + \
115 "--depclean together with --verbose to show reverse dependencies."
117 for line in wrap(paragraph, desc_width):
118 print(desc_indent + line)
120 print(" " + green("--deselect") + " [ %s | %s ]" % \
121 (turquoise("y"), turquoise("n")))
124 "Remove atoms and/or sets from the world file. This action is implied " + \
125 "by uninstall actions, including --depclean, " + \
126 "--prune and --unmerge. Use --deselect=n " + \
127 "in order to prevent uninstall actions from removing " + \
128 "atoms from the world file."
130 for line in wrap(paragraph, desc_width):
131 print(desc_indent + line)
133 print(" " + green("--ignore-default-opts"))
136 "Causes EMERGE_DEFAULT_OPTS (see make.conf(5)) to be ignored."
138 for line in wrap(paragraph, desc_width):
139 print(desc_indent + line)
141 print(" "+green("--info"))
142 print(" Displays important portage variables that will be exported to")
143 print(" ebuild.sh when performing merges. This information is useful")
144 print(" for bug reports and verification of settings. All settings in")
145 print(" make.{conf,globals,defaults} and the environment show up if")
146 print(" run with the '--verbose' flag.")
148 print(" " + green("--list-sets"))
149 paragraph = "Displays a list of available package sets."
151 for line in wrap(paragraph, desc_width):
152 print(desc_indent + line)
154 print(" "+green("--metadata"))
155 print(" Transfers metadata cache from ${PORTDIR}/metadata/cache/ to")
156 print(" /var/cache/edb/dep/ as is normally done on the tail end of an")
157 print(" rsync update using " + bold("emerge --sync") + ". This process populates the")
158 print(" cache database that portage uses for pre-parsed lookups of")
159 print(" package data. It does not populate cache for the overlays")
160 print(" listed in PORTDIR_OVERLAY. In order to generate cache for")
161 print(" overlays, use " + bold("--regen") + ".")
163 print(" "+green("--prune")+" ("+green("-P")+" short option)")
164 print(" "+turquoise("WARNING: This action can remove important packages!"))
165 paragraph = "Removes all but the highest installed version of a " + \
166 "package from your system. Use --prune together with " + \
167 "--verbose to show reverse dependencies or with --nodeps " + \
168 "to ignore all dependencies. "
170 for line in wrap(paragraph, desc_width):
171 print(desc_indent + line)
173 print(" "+green("--regen"))
174 print(" Causes portage to check and update the dependency cache of all")
175 print(" ebuilds in the portage tree. This is not recommended for rsync")
176 print(" users as rsync updates the cache using server-side caches.")
177 print(" Rsync users should simply 'emerge --sync' to regenerate.")
178 desc = "In order to specify parallel --regen behavior, use "+ \
179 "the ---jobs and --load-average options. If you would like to " + \
180 "generate and distribute cache for use by others, use egencache(1)."
181 for line in wrap(desc, desc_width):
182 print(desc_indent + line)
184 print(" "+green("--resume")+" ("+green("-r")+" short option)")
185 print(" Resumes the most recent merge list that has been aborted due to an")
186 print(" error. Please note that this operation will only return an error")
187 print(" on failure. If there is nothing for portage to do, then portage")
188 print(" will exit with a message and a success condition. A resume list")
189 print(" will persist until it has been completed in entirety or until")
190 print(" another aborted merge list replaces it. The resume history is")
191 print(" capable of storing two merge lists. After one resume list")
192 print(" completes, it is possible to invoke --resume once again in order")
193 print(" to resume an older list.")
195 print(" "+green("--search")+" ("+green("-s")+" short option)")
196 print(" Searches for matches of the supplied string in the current local")
197 print(" portage tree. By default emerge uses a case-insensitive simple ")
198 print(" search, but you can enable a regular expression search by ")
199 print(" prefixing the search string with %.")
200 print(" Prepending the expression with a '@' will cause the category to")
201 print(" be included in the search.")
202 print(" A few examples:")
203 print(" "+bold("emerge --search libc"))
204 print(" list all packages that contain libc in their name")
205 print(" "+bold("emerge --search '%^kde'"))
206 print(" list all packages starting with kde")
207 print(" "+bold("emerge --search '%gcc$'"))
208 print(" list all packages ending with gcc")
209 print(" "+bold("emerge --search '%@^dev-java.*jdk'"))
210 print(" list all available Java JDKs")
212 print(" "+green("--searchdesc")+" ("+green("-S")+" short option)")
213 print(" Matches the search string against the description field as well")
214 print(" the package's name. Take caution as the descriptions are also")
215 print(" matched as regular expressions.")
216 print(" emerge -S html")
217 print(" emerge -S applet")
218 print(" emerge -S 'perl.*module'")
220 print(" "+green("--sync"))
221 desc = "This updates the portage tree that is located in the " + \
222 "directory that the PORTDIR variable refers to (default " + \
223 "location is /usr/portage). The SYNC variable specifies " + \
224 "the remote URI from which files will be synchronized. " + \
225 "The PORTAGE_SYNC_STALE variable configures " + \
226 "warnings that are shown when emerge --sync has not " + \
227 "been executed recently."
228 for line in wrap(desc, desc_width):
229 print(desc_indent + line)
231 print(desc_indent + turquoise("WARNING:"))
232 desc = "The emerge --sync action will modify and/or delete " + \
233 "files located inside the directory that the PORTDIR " + \
234 "variable refers to (default location is /usr/portage). " + \
235 "For more information, see the PORTDIR documentation in " + \
236 "the make.conf(5) man page."
237 for line in wrap(desc, desc_width):
238 print(desc_indent + line)
240 print(desc_indent + green("NOTE:"))
241 desc = "The emerge-webrsync program will download the entire " + \
242 "portage tree as a tarball, which is much faster than emerge " + \
243 "--sync for first time syncs."
244 for line in wrap(desc, desc_width):
245 print(desc_indent + line)
247 print(" "+green("--unmerge")+" ("+green("-C")+" short option)")
248 print(" "+turquoise("WARNING: This action can remove important packages!"))
249 print(" Removes all matching packages. This does no checking of")
250 print(" dependencies, so it may remove packages necessary for the proper")
251 print(" operation of your system. Its arguments can be atoms or")
252 print(" ebuilds. For a dependency aware version of --unmerge, use")
253 print(" --depclean or --prune.")
255 print(" "+green("--version")+" ("+green("-V")+" short option)")
256 print(" Displays the currently installed version of portage along with")
257 print(" other information useful for quick reference on a system. See")
258 print(" "+bold("emerge info")+" for more advanced information.")
260 print(turquoise("Options:"))
261 print(" "+green("--accept-properties=ACCEPT_PROPERTIES"))
262 desc = "This option temporarily overrides the ACCEPT_PROPERTIES " + \
263 "variable. The ACCEPT_PROPERTIES variable is incremental, " + \
264 "which means that the specified setting is appended to the " + \
265 "existing value from your configuration. The special -* " + \
266 "token can be used to discard the existing configuration " + \
267 "value and start fresh. See the MASKED PACKAGES section " + \
268 "and make.conf(5) for more information about " + \
269 "ACCEPT_PROPERTIES. A typical usage example for this option " + \
270 "would be to use --accept-properties=-interactive to " + \
271 "temporarily mask interactive packages. With default " + \
272 "configuration, this would result in an effective " + \
273 "ACCEPT_PROPERTIES value of \"* -interactive\"."
274 for line in wrap(desc, desc_width):
275 print(desc_indent + line)
277 print(" "+green("--alphabetical"))
278 print(" When displaying USE and other flag output, combines the enabled")
279 print(" and disabled flags into a single list and sorts it alphabetically.")
280 print(" With this option, output such as USE=\"dar -bar -foo\" will instead")
281 print(" be displayed as USE=\"-bar dar -foo\"")
283 print(" " + green("--ask") + \
284 " [ %s | %s ] (%s short option)" % \
285 (turquoise("y"), turquoise("n"), green("-a")))
286 desc = "Before performing the action, display what will take place (server info for " + \
287 "--sync, --pretend output for merge, and so forth), then ask " + \
288 "whether to proceed with the action or abort. Using --ask is more " + \
289 "efficient than using --pretend and then executing the same command " + \
290 "without --pretend, as dependencies will only need to be calculated once. " + \
291 "WARNING: If the \"Enter\" key is pressed at the prompt (with no other input), " + \
292 "it is interpreted as acceptance of the first choice. Note that the input " + \
293 "buffer is not cleared prior to the prompt, so an accidental press of the " + \
294 "\"Enter\" key at any time prior to the prompt will be interpreted as a choice! " + \
295 "Use the --ask-enter-invalid option if you want a single \"Enter\" key " + \
296 "press to be interpreted as invalid input."
297 for line in wrap(desc, desc_width):
298 print(desc_indent + line)
300 print(" " + green("--ask-enter-invalid"))
301 desc = "When used together with the --ask option, " + \
302 "interpret a single \"Enter\" key press as " + \
303 "invalid input. This helps prevent accidental " + \
304 "acceptance of the first choice. This option is " + \
305 "intended to be set in the make.conf(5) " + \
306 "EMERGE_DEFAULT_OPTS variable."
307 for line in wrap(desc, desc_width):
308 print(desc_indent + line)
310 print(" " + green("--autounmask") + " [ %s | %s ]" % \
311 (turquoise("y"), turquoise("n")))
312 desc = "Automatically unmask packages and generate package.use " + \
313 "settings as necessary to satisfy dependencies. This " + \
314 "option is enabled by default. If any configuration " + \
315 "changes are required, then they will be displayed " + \
316 "after the merge list and emerge will immediately " + \
317 "abort. If the displayed configuration changes are " + \
318 "satisfactory, you should copy and paste them into " + \
319 "the specified configuration file(s), or enable the " + \
320 "--autounmask-write option."
321 for line in wrap(desc, desc_width):
322 print(desc_indent + line)
324 print(" " + green("--autounmask-write") + " [ %s | %s ]" % \
325 (turquoise("y"), turquoise("n")))
326 desc = "If --autounmask is enabled, changes are written " + \
327 "to config files, respecting CONFIG_PROTECT."
328 for line in wrap(desc, desc_width):
329 print(desc_indent + line)
331 print(" " + green("--backtrack") + " " + turquoise("COUNT"))
332 desc = "Specifies an integer number of times to backtrack if " + \
333 "dependency calculation fails due to a conflict or an " + \
334 "unsatisfied dependency (default: '10')."
335 for line in wrap(desc, desc_width):
336 print(desc_indent + line)
338 print(" " + green("--binpkg-respect-use") + " [ %s | %s ]" % \
339 (turquoise("y"), turquoise("n")))
340 desc = "Tells emerge to ignore binary packages if their use flags" + \
341 " don't match the current configuration. (default: 'n')"
342 for line in wrap(desc, desc_width):
343 print(desc_indent + line)
345 print(" " + green("--buildpkg") + \
346 " [ %s | %s ] (%s short option)" % \
347 (turquoise("y"), turquoise("n"), green("-b")))
348 desc = "Tells emerge to build binary packages for all ebuilds processed in" + \
349 " addition to actually merging the packages. Useful for maintainers" + \
350 " or if you administrate multiple Gentoo Linux systems (build once," + \
351 " emerge tbz2s everywhere) as well as disaster recovery. The package" + \
352 " will be created in the" + \
353 " ${PKGDIR}/All directory. An alternative for already-merged" + \
354 " packages is to use quickpkg(1) which creates a tbz2 from the" + \
356 for line in wrap(desc, desc_width):
357 print(desc_indent + line)
359 print(" "+green("--buildpkgonly")+" ("+green("-B")+" short option)")
360 print(" Creates a binary package, but does not merge it to the")
361 print(" system. This has the restriction that unsatisfied dependencies")
362 print(" must not exist for the desired package as they cannot be used if")
363 print(" they do not exist on the system.")
365 print(" " + green("--changed-use"))
366 desc = "This is an alias for --reinstall=changed-use."
367 for line in wrap(desc, desc_width):
368 print(desc_indent + line)
370 print(" "+green("--changelog")+" ("+green("-l")+" short option)")
371 print(" When pretending, also display the ChangeLog entries for packages")
372 print(" that will be upgraded.")
374 print(" "+green("--color") + " < " + turquoise("y") + " | "+ turquoise("n")+" >")
375 print(" Enable or disable color output. This option will override NOCOLOR")
376 print(" (see make.conf(5)) and may also be used to force color output when")
377 print(" stdout is not a tty (by default, color is disabled unless stdout")
380 print(" "+green("--columns"))
381 print(" Display the pretend output in a tabular form. Versions are")
382 print(" aligned vertically.")
384 print(" "+green("--complete-graph") + " [ %s | %s ]" % \
385 (turquoise("y"), turquoise("n")))
386 desc = "This causes emerge to consider the deep dependencies of all" + \
387 " packages from the world set. With this option enabled," + \
388 " emerge will bail out if it determines that the given operation will" + \
389 " break any dependencies of the packages that have been added to the" + \
390 " graph. Like the --deep option, the --complete-graph" + \
391 " option will significantly increase the time taken for dependency" + \
392 " calculations. Note that, unlike the --deep option, the" + \
393 " --complete-graph option does not cause any more packages to" + \
394 " be updated than would have otherwise " + \
395 "been updated with the option disabled. " + \
396 "Using --with-bdeps=y together with --complete-graph makes " + \
397 "the graph as complete as possible."
398 for line in wrap(desc, desc_width):
399 print(desc_indent + line)
401 print(" "+green("--config-root=DIR"))
402 desc = "Set the PORTAGE_CONFIGROOT environment variable " + \
403 "which is documented in the emerge(1) man page."
404 for line in wrap(desc, desc_width):
405 print(desc_indent + line)
407 print(" "+green("--debug")+" ("+green("-d")+" short option)")
408 print(" Tell emerge to run the ebuild command in --debug mode. In this")
409 print(" mode, the bash build environment will run with the -x option,")
410 print(" causing it to output verbose debug information print to stdout.")
411 print(" --debug is great for finding bash syntax errors as providing")
412 print(" very verbose information about the dependency and build process.")
414 print(" "+green("--deep") + " " + turquoise("[DEPTH]") + \
415 " (" + green("-D") + " short option)")
416 print(" This flag forces emerge to consider the entire dependency tree of")
417 print(" packages, instead of checking only the immediate dependencies of")
418 print(" the packages. As an example, this catches updates in libraries")
419 print(" that are not directly listed in the dependencies of a package.")
420 print(" Also see --with-bdeps for behavior with respect to build time")
421 print(" dependencies that are not strictly required.")
424 if _ENABLE_DYN_LINK_MAP:
425 print(" " + green("--depclean-lib-check") + " [ %s | %s ]" % \
426 (turquoise("y"), turquoise("n")))
427 desc = "Account for library link-level dependencies during " + \
428 "--depclean and --prune actions. This " + \
429 "option is enabled by default. In some cases this can " + \
430 "be somewhat time-consuming. This option is ignored " + \
431 "when FEATURES=\"preserve-libs\" is enabled in " + \
432 "make.conf(5), since any libraries that have " + \
433 "consumers will simply be preserved."
434 for line in wrap(desc, desc_width):
435 print(desc_indent + line)
438 print(" "+green("--emptytree")+" ("+green("-e")+" short option)")
439 desc = "Reinstalls target atoms and their entire deep " + \
440 "dependency tree, as though no packages are currently " + \
441 "installed. You should run this with --pretend " + \
442 "first to make sure the result is what you expect."
443 for line in wrap(desc, desc_width):
444 print(desc_indent + line)
446 print(" " + green("--exclude") + " " + turquoise("ATOMS"))
447 desc = "A space separated list of package names or slot atoms. " + \
448 "Emerge won't install any ebuild or binary package that " + \
449 "matches any of the given package atoms."
450 for line in wrap(desc, desc_width):
451 print(desc_indent + line)
453 print(" " + green("--fail-clean") + " [ %s | %s ]" % \
454 (turquoise("y"), turquoise("n")))
455 desc = "Clean up temporary files after a build failure. This is " + \
456 "particularly useful if you have PORTAGE_TMPDIR on " + \
457 "tmpfs. If this option is enabled, you probably also want " + \
458 "to enable PORT_LOGDIR (see make.conf(5)) in " + \
459 "order to save the build log."
460 for line in wrap(desc, desc_width):
461 print(desc_indent + line)
463 print(" "+green("--fetchonly")+" ("+green("-f")+" short option)")
464 print(" Instead of doing any package building, just perform fetches for")
465 print(" all packages (main package as well as all dependencies.) When")
466 print(" used in combination with --pretend all the SRC_URIs will be")
467 print(" displayed multiple mirrors per line, one line per file.")
469 print(" "+green("--fetch-all-uri")+" ("+green("-F")+" short option)")
470 print(" Same as --fetchonly except that all package files, including those")
471 print(" not required to build the package, will be processed.")
473 print(" " + green("--getbinpkg") + \
474 " [ %s | %s ] (%s short option)" % \
475 (turquoise("y"), turquoise("n"), green("-g")))
476 print(" Using the server and location defined in PORTAGE_BINHOST, portage")
477 print(" will download the information from each binary file there and it")
478 print(" will use that information to help build the dependency list. This")
479 print(" option implies '-k'. (Use -gK for binary-only merging.)")
481 print(" " + green("--getbinpkgonly") + \
482 " [ %s | %s ] (%s short option)" % \
483 (turquoise("y"), turquoise("n"), green("-G")))
484 print(" This option is identical to -g, as above, except it will not use")
485 print(" ANY information from the local machine. All binaries will be")
486 print(" downloaded from the remote server without consulting packages")
487 print(" existing in the packages directory.")
489 print(" " + green("--jobs") + " " + turquoise("[JOBS]") + " ("+green("-j")+" short option)")
490 desc = "Specifies the number of packages " + \
491 "to build simultaneously. If this option is " + \
492 "given without an argument, emerge will not " + \
493 "limit the number of jobs that " + \
494 "can run simultaneously. Also see " + \
495 "the related --load-average option. " + \
496 "Note that interactive packages currently force a setting " + \
497 "of --jobs=1. This issue can be temporarily avoided " + \
498 "by specifying --accept-properties=-interactive."
499 for line in wrap(desc, desc_width):
500 print(desc_indent + line)
502 print(" " + green("--keep-going") + " [ %s | %s ]" % \
503 (turquoise("y"), turquoise("n")))
504 desc = "Continue as much as possible after " + \
505 "an error. When an error occurs, " + \
506 "dependencies are recalculated for " + \
507 "remaining packages and any with " + \
508 "unsatisfied dependencies are " + \
509 "automatically dropped. Also see " + \
510 "the related --skipfirst option."
511 for line in wrap(desc, desc_width):
512 print(desc_indent + line)
514 print(" " + green("--load-average") + " " + turquoise("LOAD"))
515 desc = "Specifies that no new builds should " + \
516 "be started if there are other builds " + \
517 "running and the load average is at " + \
518 "least LOAD (a floating-point number). " + \
519 "This option is recommended for use " + \
520 "in combination with --jobs in " + \
521 "order to avoid excess load. See " + \
522 "make(1) for information about " + \
523 "analogous options that should be " + \
524 "configured via MAKEOPTS in " + \
526 for line in wrap(desc, desc_width):
527 print(desc_indent + line)
529 print(" " + green("--misspell-suggestions") + " < %s | %s >" % \
530 (turquoise("y"), turquoise("n")))
531 desc = "Enable or disable misspell suggestions. By default, " + \
532 "emerge will show a list of packages with similar names " + \
533 "when a package doesn't exist. The EMERGE_DEFAULT_OPTS " + \
534 "variable may be used to disable this option by default"
535 for line in wrap(desc, desc_width):
536 print(desc_indent + line)
538 print(" "+green("--newuse")+" ("+green("-N")+" short option)")
539 desc = "Tells emerge to include installed packages where USE " + \
540 "flags have changed since compilation. This option " + \
541 "also implies the --selective option. If you would " + \
542 "like to skip rebuilds for which disabled flags have " + \
543 "been added to or removed from IUSE, see the related " + \
544 "--reinstall=changed-use option."
545 for line in wrap(desc, desc_width):
546 print(desc_indent + line)
548 print(" "+green("--noconfmem"))
549 print(" Portage keeps track of files that have been placed into")
550 print(" CONFIG_PROTECT directories, and normally it will not merge the")
551 print(" same file more than once, as that would become annoying. This")
552 print(" can lead to problems when the user wants the file in the case")
553 print(" of accidental deletion. With this option, files will always be")
554 print(" merged to the live fs instead of silently dropped.")
556 print(" "+green("--nodeps")+" ("+green("-O")+" short option)")
557 print(" Merge specified packages, but don't merge any dependencies.")
558 print(" Note that the build may fail if deps aren't satisfied.")
560 print(" "+green("--noreplace")+" ("+green("-n")+" short option)")
561 print(" Skip the packages specified on the command-line that have")
562 print(" already been installed. Without this option, any packages,")
563 print(" ebuilds, or deps you specify on the command-line *will* cause")
564 print(" Portage to remerge the package, even if it is already installed.")
565 print(" Note that Portage won't remerge dependencies by default.")
566 desc = "Also note that this option takes " + \
567 "precedence over options such as --newuse, preventing a package " + \
568 "from being reinstalled even though the corresponding USE flag settings " + \
570 for line in wrap(desc, desc_width):
571 print(desc_indent + line)
573 print(" "+green("--nospinner"))
574 print(" Disables the spinner regardless of terminal type.")
576 print(" " + green("--usepkg-exclude") + " " + turquoise("ATOMS"))
577 desc = "A space separated list of package names or slot atoms." + \
578 " Emerge will ignore matching binary packages."
579 for line in wrap(desc, desc_width):
580 print(desc_indent + line)
582 print(" " + green("--rebuild-exclude") + " " + turquoise("ATOMS"))
583 desc = "A space separated list of package names or slot atoms." + \
584 " Emerge will not rebuild matching packages due to --rebuild."
585 for line in wrap(desc, desc_width):
586 print(desc_indent + line)
588 print(" " + green("--rebuild-ignore") + " " + turquoise("ATOMS"))
589 desc = "A space separated list of package names or slot atoms." + \
590 " Emerge will not rebuild packages that depend on matching " + \
591 " packages due to --rebuild."
592 for line in wrap(desc, desc_width):
593 print(desc_indent + line)
595 print(" "+green("--oneshot")+" ("+green("-1")+" short option)")
596 print(" Emerge as normal, but don't add packages to the world profile.")
597 print(" This package will only be updated if it is depended upon by")
598 print(" another package.")
600 print(" "+green("--onlydeps")+" ("+green("-o")+" short option)")
601 print(" Only merge (or pretend to merge) the dependencies of the")
602 print(" specified packages, not the packages themselves.")
604 print(" " + green("--package-moves") + " [ %s | %s ]" % \
605 (turquoise("y"), turquoise("n")))
606 desc = "Perform package moves when necessary. This option " + \
607 "is enabled by default. WARNING: This option " + \
608 "should remain enabled under normal circumstances. " + \
609 "Do not disable it unless you know what you are " + \
611 for line in wrap(desc, desc_width):
612 print(desc_indent + line)
614 print(" "+green("--pretend")+" ("+green("-p")+" short option)")
615 print(" Instead of actually performing the merge, simply display what")
616 print(" ebuilds and tbz2s *would* have been installed if --pretend")
617 print(" weren't used. Using --pretend is strongly recommended before")
618 print(" installing an unfamiliar package. In the printout, N = new,")
619 print(" U = updating, R = replacing, F = fetch restricted, B = blocked")
620 print(" by an already installed package, D = possible downgrading,")
621 print(" S = slotted install. --verbose causes affecting use flags to be")
622 print(" printed out accompanied by a '+' for enabled and a '-' for")
623 print(" disabled USE flags.")
625 print(" " + green("--quiet") + \
626 " [ %s | %s ] (%s short option)" % \
627 (turquoise("y"), turquoise("n"), green("-q")))
628 print(" Effects vary, but the general outcome is a reduced or condensed")
629 print(" output from portage's displays.")
631 print(" " + green("--quiet-build") + \
632 " [ %s | %s ]" % (turquoise("y"), turquoise("n")))
633 desc = "Redirect all build output to logs alone, and do not " + \
634 "display it on stdout."
635 for line in wrap(desc, desc_width):
636 print(desc_indent + line)
638 print(" "+green("--quiet-unmerge-warn"))
639 desc = "Disable the warning message that's shown prior to " + \
640 "--unmerge actions. This option is intended " + \
641 "to be set in the make.conf(5) " + \
642 "EMERGE_DEFAULT_OPTS variable."
643 for line in wrap(desc, desc_width):
644 print(desc_indent + line)
646 print(" " + green("--rebuild-if-new-rev") + " [ %s | %s ]" % \
647 (turquoise("y"), turquoise("n")))
648 desc = "Rebuild packages when dependencies that are " + \
649 "used at both build-time and run-time are built, " + \
650 "if the dependency is not already installed with the " + \
651 "same version and revision."
652 for line in wrap(desc, desc_width):
653 print(desc_indent + line)
655 print(" " + green("--rebuild-if-new-ver") + " [ %s | %s ]" % \
656 (turquoise("y"), turquoise("n")))
657 desc = "Rebuild packages when dependencies that are " + \
658 "used at both build-time and run-time are built, " + \
659 "if the dependency is not already installed with the " + \
660 "same version. Revision numbers are ignored."
661 for line in wrap(desc, desc_width):
662 print(desc_indent + line)
664 print(" " + green("--rebuild-if-unbuilt") + " [ %s | %s ]" % \
665 (turquoise("y"), turquoise("n")))
666 desc = "Rebuild packages when dependencies that are " + \
667 "used at both build-time and run-time are built."
668 for line in wrap(desc, desc_width):
669 print(desc_indent + line)
671 print(" " + green("--rebuilt-binaries") + " [ %s | %s ]" % \
672 (turquoise("y"), turquoise("n")))
673 desc = "Replace installed packages with binary packages that have " + \
674 "been rebuilt. Rebuilds are detected by comparison of " + \
675 "BUILD_TIME package metadata. This option is enabled " + \
676 "automatically when using binary packages " + \
677 "(--usepkgonly or --getbinpkgonly) together with " + \
678 "--update and --deep."
679 for line in wrap(desc, desc_width):
680 print(desc_indent + line)
682 print(" "+green("--rebuilt-binaries-timestamp") + "=%s" % turquoise("TIMESTAMP"))
683 desc = "This option modifies emerge's behaviour only if " + \
684 "--rebuilt-binaries is given. Only binaries that " + \
685 "have a BUILD_TIME that is larger than the given TIMESTAMP " + \
686 "and that is larger than that of the installed package will " + \
687 "be considered by the rebuilt-binaries logic."
688 for line in wrap(desc, desc_width):
689 print(desc_indent + line)
691 print(" "+green("--reinstall ") + turquoise("changed-use"))
692 print(" Tells emerge to include installed packages where USE flags have")
693 print(" changed since installation. Unlike --newuse, this option does")
694 print(" not trigger reinstallation when flags that the user has not")
695 print(" enabled are added or removed.")
697 print(" " + green("--reinstall-atoms") + " " + turquoise("ATOMS"))
698 desc = "A space separated list of package names or slot atoms. " + \
699 "Emerge will treat matching packages as if they are not " + \
700 "installed, and reinstall them if necessary."
701 for line in wrap(desc, desc_width):
702 print(desc_indent + line)
704 print(" "+green("--root=DIR"))
705 desc = "Set the ROOT environment variable " + \
706 "which is documented in the emerge(1) man page."
707 for line in wrap(desc, desc_width):
708 print(desc_indent + line)
710 print(" "+green("--root-deps[=rdeps]"))
711 desc = "If no argument is given then build-time dependencies of packages for " + \
712 "ROOT are installed to " + \
713 "ROOT instead of /. If the rdeps argument is given then discard " + \
714 "all build-time dependencies of packages for ROOT. This option is " + \
715 "only meaningful when used together with ROOT and it should not " + \
716 "be enabled under normal circumstances. For currently supported " + \
717 "EAPI values, the build-time dependencies are specified in the " + \
718 "DEPEND variable. However, behavior may change for new " + \
719 "EAPIs when related extensions are added in the future."
720 for line in wrap(desc, desc_width):
721 print(desc_indent + line)
723 print(" " + green("--select") + " [ %s | %s ]" % \
724 (turquoise("y"), turquoise("n")))
725 desc = "Add specified packages to the world set (inverse of " + \
726 "--oneshot). This is useful if you want to " + \
727 "use EMERGE_DEFAULT_OPTS to make " + \
728 "--oneshot behavior default."
729 for line in wrap(desc, desc_width):
730 print(desc_indent + line)
732 print(" " + green("--selective") + " [ %s | %s ]" % \
733 (turquoise("y"), turquoise("n")))
734 desc = "This is similar to the --noreplace option, except that it " + \
735 "does not take precedence over options such as --newuse. " + \
736 "Some options, such as --update, imply --selective. " + \
737 "Use --selective=n if you want to forcefully disable " + \
738 "--selective, regardless of options like --update."
739 for line in wrap(desc, desc_width):
740 print(desc_indent + line)
742 print(" "+green("--skipfirst"))
743 desc = "This option is only valid when " + \
744 "used with --resume. It removes the " + \
745 "first package in the resume list. " + \
746 "Dependencies are recalculated for " + \
747 "remaining packages and any that " + \
748 "have unsatisfied dependencies or are " + \
749 "masked will be automatically dropped. " + \
750 "Also see the related " + \
751 "--keep-going option."
752 for line in wrap(desc, desc_width):
753 print(desc_indent + line)
755 print(" "+green("--tree")+" ("+green("-t")+" short option)")
756 print(" Shows the dependency tree using indentation for dependencies.")
757 print(" The packages are also listed in reverse merge order so that")
758 print(" a package's dependencies follow the package. Only really useful")
759 print(" in combination with --emptytree, --update or --deep.")
761 print(" " + green("--unordered-display"))
762 desc = "By default the displayed merge list is sorted using the " + \
763 "order in which the packages will be merged. When " + \
764 "--tree is used together with this option, this " + \
765 "constraint is removed, hopefully leading to a more " + \
766 "readable dependency tree."
767 for line in wrap(desc, desc_width):
768 print(desc_indent + line)
770 print(" "+green("--update")+" ("+green("-u")+" short option)")
771 desc = "Updates packages to the best version available, which may " + \
772 "not always be the highest version number due to masking " + \
773 "for testing and development. Package atoms specified on " + \
774 "the command line are greedy, meaning that unspecific " + \
775 "atoms may match multiple versions of slotted packages."
776 for line in wrap(desc, desc_width):
777 print(desc_indent + line)
779 print(" " + green("--use-ebuild-visibility") + " [ %s | %s ]" % \
780 (turquoise("y"), turquoise("n")))
781 desc = "Use unbuilt ebuild metadata for visibility " + \
782 "checks on built packages."
783 for line in wrap(desc, desc_width):
784 print(desc_indent + line)
786 print(" " + green("--useoldpkg-atoms") + " " + turquoise("ATOMS"))
787 desc = "A space separated list of package names or slot atoms." + \
788 " Emerge will prefer matching binary packages over newer" + \
790 for line in wrap(desc, desc_width):
791 print(desc_indent + line)
793 print(" " + green("--usepkg") + \
794 " [ %s | %s ] (%s short option)" % \
795 (turquoise("y"), turquoise("n"), green("-k")))
796 print(" Tell emerge to use binary packages (from $PKGDIR) if they are")
797 print(" available, thus possibly avoiding some time-consuming compiles.")
798 print(" This option is useful for CD installs; you can export")
799 print(" PKGDIR=/mnt/cdrom/packages and then use this option to have")
800 print(" emerge \"pull\" binary packages from the CD in order to satisfy")
801 print(" dependencies.")
803 print(" " + green("--usepkgonly") + \
804 " [ %s | %s ] (%s short option)" % \
805 (turquoise("y"), turquoise("n"), green("-K")))
806 print(" Like --usepkg above, except this only allows the use of binary")
807 print(" packages, and it will abort the emerge if the package is not")
808 print(" available at the time of dependency calculation.")
810 print(" "+green("--verbose")+" ("+green("-v")+" short option)")
811 print(" Effects vary, but the general outcome is an increased or expanded")
812 print(" display of content in portage's displays.")
814 print(" "+green("--with-bdeps")+" < " + turquoise("y") + " | "+ turquoise("n")+" >")
815 print(" In dependency calculations, pull in build time dependencies that")
816 print(" are not strictly required. This defaults to 'n' for installation")
817 print(" actions and 'y' for the --depclean action. This setting can be")
818 print(" added to EMERGE_DEFAULT_OPTS (see make.conf(5)) and later")
819 print(" overridden via the command line.")