pym/_emerge/help.py

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