EMERGE(1)                           Portage                          EMERGE(1)



NAME
       emerge - Command-line interface to the Portage system

SYNOPSIS
       emerge [options] [action] [ebuild | tbz2file | file | @set | atom] ...

       emerge --sync | --version

       emerge --info [atom]

       emerge --search somestring

       emerge --help

DESCRIPTION
       emerge  is the definitive command-line interface to the Portage system.
       It is primarily used for installing packages, and emerge can  automati-
       cally handle any dependencies that the desired package has.  emerge can
       also update the portage tree, making new and  updated  packages  avail-
       able.   emerge  gracefully handles updating installed packages to newer
       releases as well.  It handles both source and binary packages,  and  it
       can be used to create binary packages for distribution.

EBUILDS, TBZ2S, SETS AND ATOMS
       emerge  primarily  installs  packages.   You  can  specify  packages to
       install in five possible ways: an atom, a set, an  installed  file,  an
       ebuild, or a tbz2file.

       ebuild An  ebuild must be, at a minimum, a valid Portage package direc-
              tory name without a version or  category,  such  as  portage  or
              python.   Both  categories  and  version  numbers may be used in
              addition, such as sys-apps/portage or =python-2.2.1-r2.   emerge
              ignores  a  trailing  slash  so  that filename completion can be
              used.  The ebuild may  also  be  an  actual  filename,  such  as
              /usr/portage/app-admin/python/python-2.2.1-r2.ebuild.   WARNING:
              The implementation of emerge /path/to/ebuild is  broken  and  so
              this syntax shouldn't be used.

       tbz2file
              A  tbz2file  must  be  a  valid .tbz2 created with ebuild <pack-
              age>-<version>.ebuild  package  or  emerge   --buildpkg   [cate-
              gory/]<package> or quickpkg /var/db/pkg/<category>/<package>.

       file   A  file  must  be a file or directory that has been installed by
              one or more packages. If an absolute path is not used,  then  it
              must  begin  with either "./" or "../". For directories that are
              owned  by  multiple  packages,  all  owning  packages  will   be
              selected.  See  the portageq(1) owners command if you would like
              to query the owners of one or more files or directories.

       set    A set is a convenient shorthand for a large group  of  packages.
              Six  sets  are  currently  always  available: selected-packages,
              selected-sets, selected, system, profile, and world.   selected-
              packages  contains  the  user-selected "world" packages that are
              listed in /var/lib/portage/world, while  selected-sets  contains
              the     nested     sets     that     may     be     listed    in
              /var/lib/portage/world_sets.  system and profile both  refer  to
              sets  of  packages deemed necessary for your system to run prop-
              erly (the differences between these two sets are  documented  in
              portage(5)).   selected  encompasses  both the selected-packages
              and selected-sets sets, while world  encompasses  the  selected,
              system and profile sets. (See FILES below for more information.)
              Other sets can exist depending on the current configuration. The
              default     set     configuration     is    located    in    the
              /usr/share/portage/config/sets directory.  User sets may be cre-
              ated  by  placing files in the /etc/portage/sets/ directory (see
              portage(5)). Note that a set is generally  used  in  conjunction
              with  --update. When used as arguments to emerge sets have to be
              prefixed with @ to be recognized. Use the --list-sets action  to
              display a list of available package sets.

       atom   An  atom describes bounds on a package that you wish to install.
              See ebuild(5) for the details  on  atom  syntax.   For  example,
              >=dev-lang/python-2.2.1-r2  matches the latest available version
              of  Python  greater  than  or  equal  to  2.2.1-r2.   Similarly,
              <dev-lang/python-2.0  matches  the  latest  available version of
              Python before 2.0.  Note that in many shells you  will  need  to
              escape  characters  such  as  '<'  and  '='; use single- or dou-
              ble-quotes around the atom to get around escaping problems.  You
              may also constrain an atom to match a specific SLOT by appending
              a colon and a SLOT. Example: x11-libs/qt:3.

ACTIONS
       No action
              If no action is specified, the action is to merge in the  speci-
              fied  packages,  satisfying any dependencies that they may have.
              The arguments can be atoms, sets, installed files,  ebuilds,  or
              tbz2s.   Note  that  you  need to use the --usepkg option if you
              want to install a tbz2.  The packages are  added  to  the  world
              file at the end, so that they are considered for later updating.

       --check-news
              Scan  all  repositories  for relevant unread GLEP 42 news items,
              and  display  how  many   are   found.   See   https://wiki.gen-
              too.org/wiki/GLEP:42.

       --clean
              Cleans  up  the  system  by examining the installed packages and
              removing older packages.  This is  accomplished  by  looking  at
              each  installed package and separating the installed versions by
              slot.  Clean will remove all but  the  most  recently  installed
              version  in  each slot.  Clean should not remove unslotted pack-
              ages. Note: Most recently installed means most recent, not high-
              est version.

       --config
              Run  package  specific  actions  needed to be executed after the
              emerge process has completed.  This usually  entails  configura-
              tion  file  setup or other similar setups that the user may wish
              to run.

       --depclean (-c)
              Cleans the system by removing packages that are  not  associated
              with  explicitly merged packages. Depclean works by creating the
              full dependency tree from the @world set, then comparing  it  to
              installed  packages.  Packages  installed,  but  not part of the
              dependency  tree,  will  be  uninstalled   by   depclean.    See
              --with-bdeps  for  behavior with respect to build time dependen-
              cies that are not strictly required. Packages that are  part  of
              the world set will always be kept. They can be manually added to
              this set with emerge --noreplace <atom>. As  a  safety  measure,
              depclean  will  not  remove  any  packages unless *all* required
              dependencies have been resolved. As a consequence, it  is  often
              necessary to run emerge --update --newuse --deep @world prior to
              depclean. Also note that depclean may break link level dependen-
              cies,  especially  when  the --depclean-lib-check option is dis-
              abled. Thus, it is recommended to use a  tool  such  as  revdep-
              rebuild(1) in order to detect such breakage.

              WARNING:  Inexperienced  users  are  advised to use --pretend or
              --ask with this option in order to see a preview of which  pack-
              ages  will  be uninstalled. Always study the list of packages to
              be cleaned for any obvious mistakes. Note that  packages  listed
              in package.provided (see portage(5)) may be removed by depclean,
              even if they are part of the world set.

              Depclean serves as a dependency aware version of --unmerge. When
              given  one  or more atoms, it will unmerge matched packages that
              have no  reverse  dependencies.  Use  --depclean  together  with
              --verbose to show reverse dependencies.

       --deselect [ y | n ]
              Remove  atoms  and/or  sets  from the world file. This action is
              implied by uninstall actions, including --depclean, --prune  and
              --unmerge.  Use  --deselect=n  in  order  to  prevent  uninstall
              actions from removing atoms from the world file.

       --help (-h)
              Displays help information for emerge.  Adding one of  the  addi-
              tional  arguments  listed above will give you more specific help
              information on that subject.  The internal emerge help  documen-
              tation  is  updated more frequently than this man page; check it
              out if you are having problems that this man page does not  help
              resolve.

       --info Produces  a  list of information to include in bug reports which
              aids the developers when fixing the  reported  problem.   Please
              include this information when submitting a bug report.  Expanded
              output can be obtained with the --verbose option.

       --list-sets
              Displays a list of available package sets.

       --metadata
              Transfers pregenerated metadata  cache  from  ${repository_loca-
              tion}/metadata/md5-cache/  to /var/cache/edb/dep/ as is normally
              done on the tail end of an rsync  update  using  emerge  --sync.
              This  process populates the cache database that Portage uses for
              pre-parsed lookups of package data. It does not  populate  cache
              for  repositories  not distributing pregenerated metadata cache.
              In order to generate cache for these repositories, use  --regen.
              In  versions of portage >=2.1.5 the --metadata action is totally
              unnecessary unless  the  user  has  enabled  FEATURES="metadata-
              transfer" in make.conf(5).

       --prune (-P)
              Removes  all but the highest installed version of a package from
              your system. Use --prune together with --verbose to show reverse
              dependencies or with --nodeps to ignore all dependencies.  WARN-
              ING: This action can remove packages from your world file! Check
              the  emerge  output  of  the  next --depclean run carefully! Use
              --depclean to avoid this issue.

       --regen
              Causes portage to check and update the dependency cache  of  all
              ebuilds  in  the  portage  tree.   The cache is used to speed up
              searches and the building of dependency trees.  This command  is
              not recommended for rsync users as rsync updates the cache using
              server-side caches.  If you do not know the differences  between
              a  'rsync user' and some other user, then you are a 'rsync user'
              :).  Rsync users should simply run emerge --sync  to  regenerate
              the cache.  After a portage update, rsync users may find it con-
              venient to run emerge --metadata to rebuild the cache as portage
              does  at the end of a sync operation. In order to specify paral-
              lel --regen behavior, use the --jobs and --load-average options.
              If  you  would  like to generate and distribute cache for use by
              others, use egencache(1).

       --resume(-r)
              Resumes the most recent merge list that has been aborted due  to
              an  error.   This  re-uses  the  arguments and options that were
              given with the original command that's being  resumed,  and  the
              user  may also provide additional options when calling --resume.
              It is an  error  to  provide  atoms  or  sets  as  arguments  to
              --resume,  since the arguments from the resumed command are used
              instead.  Please note that this operation will  only  return  an
              error  on  failure.  If there is nothing for portage to do, then
              portage will exit with a message  and  a  success  condition.  A
              resume list will persist until it has been completed in entirety
              or until another aborted merge list  replaces  it.   The  resume
              history is capable of storing two merge lists.  After one resume
              list completes, it is possible to invoke --resume once again  in
              order  to  resume an older list.  The resume lists are stored in
              /var/cache/edb/mtimedb, and may be explicitly discarded by  run-
              ning `emaint --fix cleanresume` (see emaint(1)).

       --search (-s)
              Searches for matches of the supplied string in the portage tree.
              By default emerge uses a case-insensitive simple search, but you
              can  enable  a regular expression search by prefixing the search
              string with %.  For example, emerge  --search  "%^kde"  searches
              for  any  package  whose name starts with "kde"; emerge --search
              "%gcc$" searches for any package that ends  with  "gcc";  emerge
              --search  "office"  searches  for  any package that contains the
              word "office".  If you want to include  the  category  into  the
              search string, prepend an @: emerge --search "%@^dev-java.*jdk".
              If you want to search the package descriptions as well, use  the
              --searchdesc action.

       --searchdesc (-S)
              Matches  the search string against the description field as well
              as the package name.  Take caution as the descriptions are  also
              matched as regular expressions.

       --sync Updates   repositories,   for  which  auto-sync,  sync-type  and
              sync-uri attributes are set in repos.conf.  See  portage(5)  for
              more  information.   The  PORTAGE_SYNC_STALE variable configures
              warnings that are shown when emerge --sync has not been executed
              recently.

              WARNING:  The  emerge  --sync  action  will revert local changes
              (e.g. modifications or additions of files)  inside  repositories
              synchronized using rsync.

              NOTE:  The  emerge  --sync  command  is a compatibility command.
              Sync operations are now performed using the the new emaint  sync
              module.  This  new  emaint sync module has greater functionality
              and flexibility.  Please refer to emaint(1) for more information
              about sync operations.

              NOTE:  The  emerge-webrsync  program  will  download  the entire
              portage tree as a tarball, which  is  much  faster  than  emerge
              --sync for first time syncs.


       --unmerge (-C)
              WARNING:  This action can remove important packages! Removes all
              matching packages following a counter governed  by  CLEAN_DELAY.
              This does no checking of dependencies, so it may remove packages
              necessary for the proper operation of your  system.   Its  argu-
              ments can be atoms or ebuilds. For a dependency aware version of
              --unmerge, use  --depclean  or  --prune.   For  a  version  with
              CLEAN_DELAY=0, use --rage-clean.

       --version (-V)
              Displays the version number of emerge.

OPTIONS
       --accept-properties=ACCEPT_PROPERTIES
              This  option  temporarily  overrides the ACCEPT_PROPERTIES vari-
              able. The ACCEPT_PROPERTIES variable is incremental, which means
              that  the  specified  setting  is appended to the existing value
              from your configuration. The special -* token  can  be  used  to
              discard  the  existing  configuration value and start fresh. See
              the MASKED PACKAGES section and make.conf(5) for  more  informa-
              tion  about  ACCEPT_PROPERTIES. A typical usage example for this
              option would be to use --accept-properties=-interactive to  tem-
              porarily  mask interactive packages. With default configuration,
              this would result in an effective ACCEPT_PROPERTIES value of  "*
              -interactive".

       --accept-restrict=ACCEPT_RESTRICT
              This  option temporarily overrides the ACCEPT_RESTRICT variable.
              The ACCEPT_RESTRICT variable is incremental,  which  means  that
              the  specified  setting  is  appended to the existing value from
              your configuration. The special -* token can be used to  discard
              the existing configuration value and start fresh. See the MASKED
              PACKAGES section and make.conf(5)  for  more  information  about
              ACCEPT_RESTRICT.  A  typical usage example for this option would
              be to use --accept-restrict=-bindist to temporarily  mask  pack-
              ages that are not binary re-distributable. With default configu-
              ration, this would result in an effective ACCEPT_RESTRICT  value
              of "* -bindist".

       --alert [ y | n ] (-A short option)
              Add a terminal bell character ('\a') to all interactive prompts.
              This is especially useful if dependency resolution is  taking  a
              long time, and you want emerge to alert you when it is finished.
              If you use emerge -auAD world, emerge will courteously point out
              when it has finished calculating the graph.

              --alert  may  be  'y'  or  'n'. 'true' and 'false' mean the same
              thing.  Using --alert without an option is the same as using  it
              with 'y'.  Try it with 'emerge -aA portage'.

              If  your  terminal emulator is set up to make '\a' into a window
              manager urgency hint, move your cursor to a different window  to
              get the effect.

       --alphabetical
              When  displaying USE and other flag output, combines the enabled
              and disabled lists into one list and sorts the whole list alpha-
              betically.

       --ask [ y | n ] (-a short option)
              Before  performing  the  action,  display  what  will take place
              (server info for --sync, --pretend  output  for  merge,  and  so
              forth),  then  ask  whether to proceed with the action or abort.
              Using --ask is more efficient than using --pretend and then exe-
              cuting  the same command without --pretend, as dependencies will
              only need to be calculated once. WARNING: If the "Enter" key  is
              pressed  at  the prompt (with no other input), it is interpreted
              as acceptance of the first choice.  Note that the  input  buffer
              is  not  cleared  prior to the prompt, so an accidental press of
              the "Enter" key at any time prior to the prompt will  be  inter-
              preted  as  a choice!  Use the --ask-enter-invalid option if you
              want a single "Enter" key press to  be  interpreted  as  invalid
              input.

       --ask-enter-invalid
              When  used  together  with  the --ask option, interpret a single
              "Enter" key press as invalid input. This helps prevent  acciden-
              tal  acceptance  of the first choice. This option is intended to
              be set in the make.conf(5) EMERGE_DEFAULT_OPTS variable.

       --autounmask [ y | n ]
              Automatically unmask packages and generate package.use  settings
              as  necessary to satisfy dependencies. This option is enabled by
              default. If any configuration changes are  required,  then  they
              will  be  displayed after the merge list and emerge will immedi-
              ately abort. If the displayed configuration changes  are  satis-
              factory,  you should copy and paste them into the specified con-
              figuration file(s), or enable the --autounmask-write option. The
              EMERGE_DEFAULT_OPTS  variable may be used to disable this option
              by default in make.conf(5).

       --autounmask-continue [ y | n ]
              Automatically apply autounmask changes to  configuration  files,
              and continue to execute the specified command. If the dependency
              calculation is not entirely successful, then emerge will  simply
              abort  without modifying any configuration files.  WARNING: This
              option is intended to be used only with great caution, since  it
              is  possible  for  it  to make nonsensical configuration changes
              which may lead to system breakage. Therefore, it is advisable to
              use --ask together with this option.

       --autounmask-only [ y | n ]
              Instead  of doing any package building, just unmask packages and
              generate package.use settings as necessary to satisfy  dependen-
              cies. This option is disabled by default.

       --autounmask-unrestricted-atoms [ y | n ]
              If  --autounmask  is enabled, keyword and mask changes using the
              '=' operator will be written. With this option,  '>='  operators
              will  be used whenever possible.  USE and license changes always
              use the latter behavior.

       --autounmask-keep-masks [ y | n ]
              If --autounmask is enabled,  no  package.unmask  or  **  keyword
              changes  will be created. This leads to unsatisfied dependencies
              if no other solution exists.

       --autounmask-write [ y | n ]
              If --autounmask is enabled, changes are written to config files,
              respecting CONFIG_PROTECT and --ask.  If the corresponding pack-
              age.* is a file, the changes are appended to  it,  if  it  is  a
              directory,  changes  are  written  to the lexicographically last
              file. This way it is always ensured that the  new  changes  take
              precedence  over  existing changes. This option is automatically
              enabled with --ask.

       --backtrack=COUNT
              Specifies an integer number of times to backtrack if  dependency
              calculation fails due to a conflict or an unsatisfied dependency
              (default: '3').

       --binpkg-changed-deps [ y | n ]
              Tells emerge to ignore binary packages for which the correspond-
              ing  ebuild  dependencies  have  changed since the packages were
              built.  In order to help avoid issues with  resolving  inconsis-
              tent  dependencies,  this option is automatically enabled unless
              the --usepkgonly option is enabled.  Behavior  with  respect  to
              changed   build-time   dependencies   is   controlled   by   the
              --with-bdeps option.

       --binpkg-respect-use [ y | n ]
              Tells emerge to ignore binary packages if their USE flags  don't
              match  the  current configuration. In order to help avoid issues
              with resolving inconsistent USE flag settings,  this  option  is
              automatically enabled unless the --usepkgonly option is enabled.

       --buildpkg [ y | n ] (-b short option)
              Tells  emerge to build binary packages for all ebuilds processed
              in addition to actually merging the packages.  Useful for  main-
              tainers  or  if  you  administrate multiple Gentoo Linux systems
              (build once, emerge tbz2s everywhere) as well as disaster recov-
              ery.  The  package  will be created in the PKGDIR directory (see
              make.conf(5)).  An alternative for already-merged packages is to
              use quickpkg(1) which creates a tbz2 from the live filesystem.

       --buildpkg-exclude ATOMS
              A  space  separated  list  of  package atoms for which no binary
              packages should be built. This  option  overrides  all  possible
              ways  to enable building of binary packages except for the down-
              grade-backup   and   unmerge-backup   FEATURES   settings   (see
              make.conf(5) for more information about FEATURES settings).

       --buildpkgonly (-B)
              Creates  binary packages for all ebuilds processed without actu-
              ally merging the packages.  This comes with the caveat that  all
              build-time dependencies must already be emerged on the system.

       --changed-deps [ y | n ]
              Tells  emerge to replace installed packages for which the corre-
              sponding ebuild dependencies have  changed  since  the  packages
              were  built.  This  option  also implies the --selective option.
              Behavior with respect to changed build-time dependencies is con-
              trolled by the --with-bdeps option.

       --changed-use (-U)
              Tells  emerge to include installed packages where USE flags have
              changed  since  installation.  This  option  also  implies   the
              --selective  option.  Unlike  --newuse, the --changed-use option
              does not trigger reinstallation when flags that the user has not
              enabled are added or removed.

              NOTE:  This  option  ignores  the  state of the "test" USE flag,
              since that flag has a special binding  to  FEATURES="test"  (see
              make.conf(5) for more information about FEATURES settings).

       --changelog (-l)
              Use  this  in  conjunction with the --pretend option.  This will
              show the ChangeLog entries for all the  packages  that  will  be
              upgraded.

       --color < y | n >
              Enable  or  disable  color  output.   This  option will override
              NOCOLOR (see make.conf(5)) and may also be used to  force  color
              output  when  stdout is not a tty (by default, color is disabled
              unless stdout is a tty).

       --columns
              Used alongside --pretend to cause the package name, new version,
              and  old  version  to be displayed in an aligned format for easy
              cut-n-paste.

       --complete-graph [ y | n ]
              This causes emerge to consider  the  deep  dependencies  of  all
              packages  from  the  world set. With this option enabled, emerge
              will bail out if it determines that  the  given  operation  will
              break  any  dependencies of the packages that have been added to
              the graph. Like the --deep option, the  --complete-graph  option
              will significantly increase the time taken for dependency calcu-
              lations.  Note  that,  unlike  the  --deep  option,  the  --com-
              plete-graph  option  does  not  cause  any  more  packages to be
              updated than would have otherwise been updated with  the  option
              disabled.   Using  --with-bdeps=y together with --complete-graph
              makes the graph as complete as possible.

       --complete-graph-if-new-use < y | n >
              Trigger the --complete-graph behavior if USE or IUSE will change
              for an installed package. This option is enabled by default.

       --complete-graph-if-new-ver < y | n >
              Trigger  the  --complete-graph  behavior if an installed package
              version will change  (upgrade  or  downgrade).  This  option  is
              enabled by default.

       --config-root=DIR
              Set the PORTAGE_CONFIGROOT environment variable.

       --debug (-d)
              Tells emerge to run the emerge command in --debug mode.  In this
              mode the bash build environment will run  with  the  -x  option,
              causing  it  to  output verbose debugging information to stdout.
              This also enables a plethora of other output (mostly  dependency
              resolution messages).

       --deep [DEPTH] (-D)
              This  flag  forces emerge to consider the entire dependency tree
              of packages, instead of checking only the immediate dependencies
              of  the  packages.   As  an  example,  this  catches  updates in
              libraries that are not directly listed in the dependencies of  a
              package.   Also  see  --with-bdeps  for behavior with respect to
              build time dependencies that are not strictly required.

       --depclean-lib-check [ y | n ]
              Account for library link-level  dependencies  during  --depclean
              and --prune actions.  This option is enabled by default. If FEA-
              TURES="preserve-libs"  is  enabled  in  make.conf(5),  and  pre-
              serve-libs  is  not  restricted for any of the packages selected
              for removal, then this option is ignored because  any  libraries
              that have consumers will simply be preserved.

       --digest
              Prevent  corruption  from  being noticed. The `repoman manifest`
              command is the preferred way to generate  manifests  and  it  is
              capable  of  doing an entire repository or category at once (see
              repoman(1)).

       --dynamic-deps < y | n >
              In  dependency  calculations,  substitute  the  dependencies  of
              installed   packages  with  the  dependencies  of  corresponding
              unbuilt ebuilds from source repositories. This causes the effec-
              tive dependencies of installed packages to vary dynamically when
              source ebuild dependencies are modified. This option is  enabled
              by default.

              WARNING:  If  you want to disable --dynamic-deps, then it may be
              necessary to first run fixpackages(1) in order to get  the  best
              results. The fixpackages(1) command performs two different oper-
              ations that can also be  performed  separately  by  the  `emaint
              --fix   moveinst`  and  `emaint  --fix  movebin`  commands  (see
              emaint(1)).

       --emptytree (-e)
              Reinstalls target atoms and their entire deep  dependency  tree,
              as  though  no  packages are currently installed. You should run
              this with --pretend first to make sure the result  is  what  you
              expect.

       --exclude ATOMS
              A  space  separated list of package names or slot atoms.  Emerge
              won't  install any ebuild or binary package that matches any  of
              the given package atoms.

       --fail-clean [ y | n ]
              Clean up temporary files after a build failure. This is particu-
              larly useful if you have PORTAGE_TMPDIR on tmpfs. If this option
              is  enabled,  you  probably also want to enable PORT_LOGDIR (see
              make.conf(5)) in order to save the build log.

       --fetchonly (-f)
              Instead of doing any package building, just perform fetches  for
              all packages (fetch things from SRC_URI based upon USE setting).

       --fetch-all-uri (-F)
              Instead  of doing any package building, just perform fetches for
              all packages (fetch everything in SRC_URI regardless of USE set-
              ting).

       --fuzzy-search [ y | n ]
              Enable  or  disable  fuzzy search for search actions. When fuzzy
              search is enabled, a result is returned if  it  is  sufficiently
              similar  to the search string, without requiring an exact match.
              This option is enabled by default. Fuzzy search does not support
              regular  expressions, therefore it is automatically disabled for
              regular expression searches. Fuzzy  search  is  slightly  slower
              than non-fuzzy search.

       --getbinpkg [ y | n ] (-g short option)
              Using  the  server  and location defined in PORTAGE_BINHOST (see
              make.conf(5)), portage will download the information  from  each
              binary  package  found  and it will use that information to help
              build the dependency list.  This option implies  -k.   (Use  -gK
              for binary-only merging.)

       --getbinpkgonly [ y | n ] (-G short option)
              This  option  is identical to -g, as above, except binaries from
              the remote server are preferred over local packages if they  are
              not identical.

       --ignore-default-opts
              Causes EMERGE_DEFAULT_OPTS (see make.conf(5)) to be ignored.

       --ignore-built-slot-operator-deps < y | n >
              Ignore  the slot/sub-slot := operator parts of dependencies that
              have been recorded when packages where  built.  This  option  is
              intended  only for debugging purposes, and it only affects built
              packages that specify  slot/sub-slot  :=  operator  dependencies
              which are supported beginning with EAPI 5.

       --ignore-soname-deps < y | n >
              Ignore the soname dependencies of binary and installed packages.
              This option is enabled by default, since soname dependencies are
              relatively  new,  and the required metadata is not guaranteed to
              exist for binary and installed packages built  with  older  ver-
              sions  of  portage.  Also, soname dependencies will be automati-
              cally ignored for dependency calculations that can pull  unbuilt
              ebuilds  into the dependency graph, since unbuilt ebuilds do not
              have any soname dependency metadata,  making  it  impossible  to
              determine  whether an unresolved soname dependency can be satis-
              fied.  Therefore, --usepkgonly (or --getbinpkgonly) must be used
              in  order  to enable soname depedency resolution when installing
              packages.

       -j [JOBS], --jobs[=JOBS]
              Specifies the number of packages  to  build  simultaneously.  If
              this  option is given without an argument, emerge will not limit
              the number of jobs that can run  simultaneously.  Also  see  the
              related  --load-average  option.  Similarly to the --quiet-build
              option, the --jobs option causes all build output  to  be  redi-
              rected  to logs.  Note that interactive packages currently force
              a setting of --jobs=1. This issue can be temporarily avoided  by
              specifying --accept-properties=-interactive.

       --keep-going [ y | n ]
              Continue  as  much  as  possible  after  an error. When an error
              occurs, dependencies are recalculated for remaining packages and
              any  with  unsatisfied  dependencies  are automatically dropped.
              Also see the related --skipfirst option.

       --load-average [LOAD]
              Specifies that no new builds should  be  started  if  there  are
              other  builds  running  and the load average is at least LOAD (a
              floating-point number).  With no argument,  removes  a  previous
              load  limit.   This option is recommended for use in combination
              with --jobs in order to  avoid  excess  load.  See  make(1)  for
              information  about  analogous  options that should be configured
              via MAKEOPTS in make.conf(5).

       --misspell-suggestions < y | n >
              Enable or disable misspell suggestions. By default, emerge  will
              show  a  list  of  packages  with  similar  names when a package
              doesn't exist.  The EMERGE_DEFAULT_OPTS variable may be used  to
              disable this option by default.

       --newrepo
              Tells  emerge  to  recompile a package if it is now being pulled
              from a  different  repository.  This  option  also  implies  the
              --selective option.

       --newuse (-N)
              Tells  emerge to include installed packages where USE flags have
              changed since compilation. This option also implies the --selec-
              tive option.  USE flag changes include:

              A  USE flag was added to a package.  A USE flag was removed from
              a package.  A USE flag was turned on for a package.  A USE  flag
              was turned off for a package.

              USE flags may be toggled by your profile as well as your USE and
              package.use settings. If you would like  to  skip  rebuilds  for
              which  disabled  flags  have been added to or removed from IUSE,
              see the related --changed-use option. If you would like to  skip
              rebuilds for specific packages, see the --exclude option.

              NOTE:  This  option  ignores  the  state of the "test" USE flag,
              since that flag has a special binding  to  FEATURES="test"  (see
              make.conf(5) for more information about FEATURES settings).

       --noconfmem
              Causes portage to disregard merge records indicating that a con-
              fig file inside of a CONFIG_PROTECT directory  has  been  merged
              already.   Portage  will normally merge those files only once to
              prevent the user from dealing  with  the  same  config  multiple
              times.  This flag will cause the file to always be merged.

       --nodeps (-O)
              Merges  specified  packages  without  merging  any dependencies.
              Note that the build may fail if the dependencies  aren't  satis-
              fied.

       --noreplace (-n)
              Skips  the  packages  specified  on  the  command-line that have
              already been installed.  Without this option, any package  atoms
              or  package  sets  you  specify  on  the command-line will cause
              Portage to remerge the package, even if it is already installed.
              Note that Portage will not remerge dependencies by default. This
              option can be used to update the world file  without  rebuilding
              the packages.

       --nospinner
              Disables  the  spinner  for  the session.  The spinner is active
              when the terminal device is determined to be a TTY.   This  flag
              disables it regardless.

       --usepkg-exclude ATOMS
              A  space  separated  list of package names or slot atoms. Emerge
              will ignore matching binary packages.

       --rebuild-exclude ATOMS
              A space separated list of package names or  slot  atoms.  Emerge
              will not rebuild matching packages due to --rebuild.

       --rebuild-ignore ATOMS
              A  space  separated  list of package names or slot atoms. Emerge
              will not rebuild packages that depend on matching  packages  due
              to --rebuild.

       --oneshot (-1)
              Emerge  as normal, but do not add the packages to the world file
              for later updating.

              WARNING: This option should only be used for packages  that  are
              reachable  from  the @world package set (those that would not be
              removed by --depclean), since dependencies of unreachable  pack-
              ages  are  allowed  to be broken when satisfying dependencies of
              other packages.  Broken dependencies of this sort  will  invali-
              date assumptions that make it possible for --deep to be disabled
              by default.

       --onlydeps (-o)
              Only merge (or pretend to merge) the dependencies of  the  pack-
              ages specified, not the packages themselves.

       --package-moves [ y | n ]
              Perform  package moves when necessary. This option is enabled by
              default. Package moves are typically applied immediately after a
              --sync action. They are applied in an incremental fashion, using
              only the subset of the history of package moves which have  been
              added  or  modified  since  the  previous application of package
              moves.

              WARNING: This option should remain enabled under normal  circum-
              stances.  Do not disable it unless you know what you are doing.

              NOTE:  The  fixpackages(1)  command  can be used to exhaustively
              apply the entire history of package moves, regardless of whether
              or not any of the package moves have been previously applied.

       --pkg-format
              Specify  which  binary package format will be created as target.
              Possible choices now are tar and rpm or their combinations.

       --prefix=DIR
              Set the EPREFIX environment variable.

       --pretend (-p)
              Instead of actually performing the merge,  simply  display  what
              *would*  have  been  installed if --pretend weren't used.  Using
              --pretend is strongly recommended before installing an  unfamil-
              iar package.  In the printout:


              N   new (not yet installed)
              S   new SLOT installation (side-by-side versions)
              U   updating (to another version)
              D   downgrading (best version seems lower)
              r   reinstall (forced for some reason, possibly due to slot or sub-slot)

              R   replacing (remerging same version)
              F   fetch restricted (must be manually downloaded)
              f   fetch restricted (already downloaded)
              I   interactive (requires user input)
              B   blocked by another package (unresolved conflict)
              b   blocked by another package (automatically resolved conflict)

       --quiet [ y | n ] (-q short option)
              Results  may  vary, but the general outcome is a reduced or con-
              densed output from portage's displays.

       --quiet-build [ y | n ]
              Redirect all build output to logs alone, and do not  display  it
              on  stdout.  If a build failure occurs for a single package, the
              build log will be automatically displayed on stdout (unless  the
              --quiet-fail  option  is  enabled).  If there are multiple build
              failures (due to options like --keep-going or --jobs), then  the
              content  of the log files will not be displayed, and instead the
              paths of the log files will be displayed together with the  cor-
              responding  die  messages.   Note that interactive packages cur-
              rently force all build output to be displayed  on  stdout.  This
              issue  can be temporarily avoided by specifying --accept-proper-
              ties=-interactive.  Further, note that  disabling  --quiet-build
              has no effect if --jobs is set to anything higher than 1.

       --quiet-fail [ y | n ]
              Suppresses  display of the build log on stdout when build output
              is  hidden  due  to  options  such  as   --jobs,   --quiet,   or
              --quiet-build.  Only  the  die message and the path of the build
              log will be displayed on stdout.

       --quiet-repo-display
              In the package merge list display, suppress ::repository output,
              and  instead  use numbers to indicate which repositories package
              come from.

       --quiet-unmerge-warn
              Disable the warning message  that's  shown  prior  to  --unmerge
              actions.  This  option is intended to be set in the make.conf(5)
              EMERGE_DEFAULT_OPTS variable.

       --rage-clean
              WARNING:   This   action   can   remove   important    packages!
              --rage-clean does --unmerge with CLEAN_DELAY=0.

       --read-news [ y | n ]
              Offer  to  read  news via eselect if there are unread news. This
              option has no effect unless --ask is enabled.

       --rebuild-if-new-slot [ y | n ]
              Automatically rebuild or reinstall packages  when  slot/sub-slot
              :=  operator  dependencies  can be satisfied by a newer slot, so
              that older packages slots will become eligible  for  removal  by
              the  --depclean  action  as  soon  as possible. This option only
              affects packages  that  specify  slot/sub-slot  :=  dependencies
              which  are  supported  beginning with EAPI 5.  Since this option
              requires checking of reverse  dependencies,  it  enables  --com-
              plete-graph  mode  whenever a new slot is installed. This option
              is enabled by default.

              NOTE: If you want to skip all rebuilds  involving  slot-operator
              dependecies  (including  those  that  involve  sub-slot  changes
              alone), then --ignore-built-slot-operator-deps=y is  the  option
              that  you  are looking for, since --rebuild-if-new-slot does not
              affect rebuilds triggered by sub-slot changes alone.

       --rebuild-if-new-rev [ y | n ]
              Rebuild packages when build-time  dependencies  are  built  from
              source, if the dependency is not already installed with the same
              version and revision.

       --rebuild-if-new-ver [ y | n ]
              Rebuild packages when build-time  dependencies  are  built  from
              source, if the dependency is not already installed with the same
              version. Revision numbers are ignored.

       --rebuild-if-unbuilt [ y | n ]
              Rebuild packages when build-time  dependencies  are  built  from
              source.

       --rebuilt-binaries [ y | n ]
              Replace  installed  packages with binary packages that have been
              rebuilt. Rebuilds are detected by comparison of BUILD_TIME pack-
              age  metadata.  This  option is enabled automatically when using
              binary packages (--usepkgonly or --getbinpkgonly) together  with
              --update and --deep.

       --rebuilt-binaries-timestamp=TIMESTAMP
              This  option modifies emerge's behaviour only if --rebuilt-bina-
              ries is given. Only binaries that  have  a  BUILD_TIME  that  is
              larger  than the given TIMESTAMP and that is larger than that of
              the installed package will be considered by the rebuilt-binaries
              logic.

       --reinstall changed-use
              This is an alias for --changed-use.

       --reinstall-atoms ATOMS
              A  space  separated  list of package names or slot atoms. Emerge
              will treat matching packages as if they are not  installed,  and
              reinstall them if necessary.

       --root=DIR
              Set the ROOT environment variable.

       --root-deps[=rdeps]
              If no argument is given then build-time dependencies of packages
              for ROOT are installed to ROOT instead of /.  If the rdeps argu-
              ment  is given then discard all build-time dependencies of pack-
              ages for  ROOT.   This  option  is  only  meaningful  when  used
              together  with  ROOT  and  it should not be enabled under normal
              circumstances!

              Does not affect EAPIs that support HDEPEND.   Experimental  EAPI
              5-hdepend provides HDEPEND as a new means to adjust installation
              into "/" and ROOT.  If ebuilds using EAPIs which do not  support
              HDEPEND  are  built  in the same emerge run as those using EAPIs
              which do support HDEPEND, this option affects only the former.

       --search-index < y | n >
              Enable or disable indexed search for search actions. This option
              is  enabled by default. The search index needs to be regenerated
              by egencache(1) after changes are made to a repository (see  the
              --update-pkg-desc-index  action).  This  setting can be added to
              EMERGE_DEFAULT_OPTS (see make.conf(5)) and later overridden  via
              the command line.

       --search-similarity PERCENTAGE
              Set  the  minimum similarity percentage (a floating-point number
              between 0 and 100). Search results with  similarity  percentages
              lower  than  this are discarded (default: '80'). This option has
              no effect unless the --fuzzy-search option is enabled.

       --select [ y | n ] (-w short option)
              Add specified packages to the world set (inverse of  --oneshot).
              This  is  useful  if you want to use EMERGE_DEFAULT_OPTS to make
              --oneshot behavior default.

       --selective [ y | n ]
              This is identical to the --noreplace option.  Some options, such
              as  --update,  imply --selective.  Use --selective=n if you want
              to forcefully disable --selective, regardless  of  options  like
              --changed-use, --newuse, --noreplace, or --update.

       --skipfirst
              This  option  is only valid when used with --resume.  It removes
              the first package in the resume list. Dependencies are  recalcu-
              lated  for  remaining  packages  and  any  that have unsatisfied
              dependencies or are masked will be automatically  dropped.  Also
              see the related --keep-going option.

       --sync-submodule <glsa|news|profiles>
              Restrict  sync to the specified submodule(s). This option may be
              specified multiple times, in order to sync multiple  submodules.
              Currently,  this  option  has no effect for sync protocols other
              than rsync.  (--sync action only)

       --tree (-t)
              Shows the dependency tree for  the  given  target  by  indenting
              dependencies.   This  is  only really useful in combination with
              --emptytree or --update and --deep.

       --unordered-display
              By default the displayed merge list is sorted using the order in
              which  the packages will be merged. When --tree is used together
              with this option, this constraint is removed, hopefully  leading
              to a more readable dependency tree.

       --update (-u)
              Updates  packages  to  the best version available, which may not
              always be the  highest version number due to masking for testing
              and development. Package atoms specified on the command line are
              greedy, meaning that unspecific atoms may  match  multiple  ver-
              sions of slotted packages.

       --use-ebuild-visibility [ y | n ]
              Use unbuilt ebuild metadata for visibility checks on built pack-
              ages.

       --useoldpkg-atoms ATOMS
              A space separated list of package names or  slot  atoms.  Emerge
              will  prefer  matching  binary packages over newer unbuilt pack-
              ages.

       --usepkg [ y | n ] (-k short option)
              Tells emerge to use binary packages (from $PKGDIR) if  they  are
              available,  thus possibly avoiding some time-consuming compiles.
              This  option  is  useful  for  CD  installs;  you   can   export
              PKGDIR=/mnt/cdrom/packages  and  then  use  this  option to have
              emerge "pull" binary packages from the CD in  order  to  satisfy
              dependencies.

       --usepkgonly [ y | n ] (-K short option)
              Tells  emerge  to  only use binary packages (from $PKGDIR).  All
              the binary packages must be available at the time of  dependency
              calculation  or  emerge will simply abort.  Portage does not use
              ebuild repositories when calculating dependency  information  so
              all masking information is ignored.

       --verbose [ y | n ] (-v short option)
              Tell  emerge to run in verbose mode.  Currently this flag causes
              emerge to print out GNU info errors, if any, and to show the USE
              flags  that  will  be used for each package when pretending. The
              following symbols are affixed to USE flags in order to  indicate
              their status:


              Symbol   Location    Meaning
              --------------------------------------------------------------

              -        prefix      not enabled (either disabled or removed)
              *        suffix      transition to or from the enabled state

              %        suffix      newly added or removed
              ()       circumfix   forced, masked, or removed
              {}       circumfix   state is bound to FEATURES settings

       --verbose-conflicts
              Make  slot  conflicts  more  verbose. Note that this may in some
              cases output hundreds of packages for slot conflicts.

       --verbose-slot-rebuilds [ y | n ]
              Turns on/off the extra emerge output to list which packages  are
              causing rebuilds.  The default is set to "y" (on).

       --with-bdeps < y | n >
              In dependency calculations, pull in build time dependencies that
              are not strictly required. This defaults to 'n' for installation
              actions,  meaning  they  will  not be installed, and 'y' for the
              --depclean action, meaning they will not be removed.  This  set-
              ting  can be added to EMERGE_DEFAULT_OPTS (see make.conf(5)) and
              later overridden via the command line.

       --with-test-deps [ y | n ]
              For packages matched by arguments,  this  option  will  pull  in
              dependencies  that  are conditional on the "test" USE flag, even
              if "test" is not enabled in FEATURES for the  matched  packages.
              (see make.conf(5) for more information about FEATURES settings).

ENVIRONMENT OPTIONS
       EPREFIX = [path]
              Use  EPREFIX to specify the target prefix to be used for merging
              packages or ebuilds. This variable can be set via  the  --prefix
              option or in make.conf(5) (the command line overrides other set-
              tings).
              Defaults to the prefix where portage is currently installed.

       ROOT = [path]
              Use ROOT to specify the target root filesystem to  be  used  for
              merging  packages  or  ebuilds. This variable can be set via the
              --root option or in make.conf(5)  (the  command  line  overrides
              other settings).
              Defaults to /.

       PORTAGE_CONFIGROOT = [path]
              Use  PORTAGE_CONFIGROOT  to  specify  the  location  for various
              portage configuration files (see FILES for a  detailed  list  of
              configuration  files).   This variable can be set via the --con-
              fig-root option.
              Defaults to /.

OUTPUT
       When utilizing emerge with the --pretend and --verbose flags, the  out-
       put may be a little hard to understand at first.  This section explains
       the abbreviations.

       [blocks  B  ]  app-text/dos2unix   ("app-text/dos2unix"   is   blocking
       app-text/hd2u-0.8.0)
              Dos2unix  is  Blocking  hd2u  from  being emerged.  Blockers are
              defined when two packages will clobber  each  others  files,  or
              otherwise  cause some form of breakage in your system.  However,
              blockers usually  do  not  need  to  be  simultaneously  emerged
              because they usually provide the same functionality.

       [ebuild N ] app-games/qstat-25c
              Qstat  is  New to your system, and will be emerged for the first
              time.

       [ebuild NS ] dev-libs/glib-2.4.7
              You already have a version of glib installed, but a  'new'  ver-
              sion in a different SLOT is available.

       [ebuild R ] sys-apps/sed-4.0.5
              Sed  4.0.5 has already been emerged, but if you run the command,
              then portage will Re-emerge the specified package (sed  in  this
              case).

       [ebuild F ] media-video/realplayer-8-r6
              The realplayer package requires that you Fetch the sources manu-
              ally.  When you attempt to emerge the package,  if  the  sources
              are  not  found, then portage will halt and you will be provided
              with instructions on how to download the required files.

       [ebuild f ] media-video/realplayer-8-r6
              The realplayer package's files are already downloaded.

       [ebuild U ] net-fs/samba-2.2.8_pre1 [2.2.7a]
              Samba 2.2.7a has already been emerged and can be Updated to ver-
              sion 2.2.8_pre1.

       [ebuild UD] media-libs/libgd-1.8.4 [2.0.11]
              Libgd  2.0.11  is  already  emerged, but if you run the command,
              then portage will Downgrade to version 1.8.4 for you.
              This may occur if a newer version of a package has  been  masked
              because  it is broken or it creates a security risk on your sys-
              tem and a fix has not been released yet.
              Another reason this may occur is if a package you are trying  to
              emerge requires an older version of a package in order to emerge
              successfully.  In this case,  libgd  2.x  is  incompatible  with
              libgd  1.x.   This  means  that  packages that were created with
              libgd 1.x will not compile with 2.x  and  must  downgrade  libgd
              first before they can emerge.

       [ebuild U ] sys-devel/distcc-2.16 [2.13-r1] USE="ipv6* -gtk -qt%"
              Here  we  see  that  the make.conf variable USE affects how this
              package is built.  In this example,  ipv6  optional  support  is
              enabled  and both gtk and qt support are disabled.  The asterisk
              following ipv6 indicates that ipv6 support was disabled the last
              time  this package was installed.  The percent sign following qt
              indicates that the qt option has been added to the package since
              it  was  last installed.  For information about all USE symbols,
              see the --verbose option documentation above.
              *Note: Flags that haven't changed since  the  last  install  are
              only displayed when you use the --pretend and --verbose options.
              Using the --quiet option will prevent all information from being
              displayed.

       [ebuild r U ] dev-libs/icu-50.1.1:0/50.1.1 [50.1-r2:0/50.1]
              Icu  50.1-r2 has already been emerged and can be Updated to ver-
              sion 50.1.1. The r symbol indicates that a sub-slot change (from
              50.1  to  50.1.1  in  this  case)  will  force  packages  having
              slot-operator dependencies on it to be rebuilt (as libxml2  will
              be rebuilt in the next example).

       [ebuild rR ] dev-libs/libxml2-2.9.0-r1:2 USE="icu"
              Libxml2  2.9.0-r1  has  already been emerged, but if you run the
              command, then portage will Re-emerge it in order  to  satisfy  a
              slot-operator  dependency which forces it to be rebuilt when the
              icu sub-slot changes (as it changed in the previous example).

       [ebuild U *] sys-apps/portage-2.2.0_alpha6 [2.1.9.25]
              Portage 2.1.9.25 is installed, but if you run the command,  then
              portage  will upgrade to version 2.2.0_alpha6. In this case, the
              * symbol  is  displayed,  in  order  to  indicate  that  version
              2.2.0_alpha6  is masked by missing keyword. This type of masking
              display is disabled by  the  --quiet  option  if  the  --verbose
              option is not enabled simultaneously.  The following symbols are
              used to indicate various types of masking:

              Symbol   Mask Type
              --------------------------

                #      package.mask
                *      missing keyword
                ~      unstable keyword

              NOTE: The unstable keyword symbol (~) will not be shown in cases
              in  which the corresponding unstable keywords have been accepted
              globally via ACCEPT_KEYWORDS.




       NOTES  You should almost always precede any package install  or  update
              attempt  with  a --pretend install or update.  This lets you see
              how much will be done, and shows you any blocking packages  that
              you  will  have  to rectify.  This goes doubly so for the system
              and world sets, which can update a large number of  packages  if
              the portage tree has been particularly active.

       You  also  want  to typically use --update, which ignores packages that
       are already fully updated but updates those that are not.

       When you install a package with uninstalled  dependencies  and  do  not
       explicitly  state  those  dependencies  in the list of parameters, they
       will not be added to the world file.  If you want them to  be  detected
       for  world  updates, make sure to explicitly list them as parameters to
       emerge.

       USE variables may be specified on the command line  to  override  those
       specified in the default locations, letting you avoid using some depen-
       dencies you may not want to have.  USE flags specified on  the  command
       line  are  NOT  remembered.  For example, env USE="-X -gnome" emerge mc
       will emerge mc with those USE settings (on Bourne-compatible shells you
       may omit the env part).  If you want those USE settings to be more per-
       manent, you can put them in /etc/portage/package.use instead.

       If emerge --update @system or emerge  --update  @world  fails  with  an
       error  message,  it  may  be that an ebuild uses some newer feature not
       present in this version of emerge.  You can use emerge --update portage
       to  upgrade  to the lastest version, which should support any necessary
       new features.

MASKED PACKAGES
       NOTE: Please use caution when using development packages.  Problems and
       bugs  resulting  from  misusing masked packages drains Gentoo developer
       time.  Please be sure you are capable of handling any problems that may
       ensue.

       Masks  in portage have many uses: they allow a testing period where the
       packages can be used in live machines; they prevent the use of a  pack-
       age  when it will fail; and they mask existing packages that are broken
       or could pose a security risk.  Read below to find out how to unmask in
       various  cases.   Also note that if you give emerge an ebuild, then all
       forms of masking will be ignored and emerge will attempt to emerge  the
       package.

       backtracking
              When  packages  are  masked  for backtracking, it means that the
              dependency resolver has temporarily  masked  them  in  order  to
              avoid dependency conflicts and/or unsatisfied dependencies. This
              type of mask is typically  accompanied  by  a  message  about  a
              missed  package  update which has been skipped in order to avoid
              dependency conflicts and/or unsatisfied dependencies.

       package.mask
              The package.mask file primarily blocks the use of packages  that
              cause problems or are known to have issues on different systems.
              It resides in /usr/portage/profiles.

       CHOST  Use the ACCEPT_CHOSTS variable in make.conf(5) to control  CHOST
              acceptance.

       EAPI   The  EAPI variable in an ebuild(5) file is used to mask packages
              that are not supported by the current version of portage.  Pack-
              ages masked by EAPI can only be installed after portage has been
              upgraded.

       KEYWORDS
              The KEYWORDS variable in an ebuild file is also used for masking
              a  package  still  in  testing.  There are architecture-specific
              keywords for each package that let portage  know  which  systems
              are  compatible  with the package.  Packages which compile on an
              architecture, but have not  been  proven  to  be  "stable",  are
              masked  with  a  tilde  (~)  in  front of the architecture name.
              emerge examines  the  ACCEPT_KEYWORDS  environment  variable  to
              allow  or disallow the emerging of a package masked by KEYWORDS.
              To inform emerge that it should build these  'testing'  versions
              of   packages,   you   should   update  your  /etc/portage/pack-
              age.accept_keywords file to  list  the  packages  you  want  the
              'testing' version.  See portage(5) for more information.

       LICENSE
              The LICENSE variable in an ebuild file can be used to mask pack-
              ages  based  on  licensing  restrictions.  emerge  examines  the
              ACCEPT_LICENSE  environment  variable  to  allow or disallow the
              emerging of a package masked by LICENSE.  See  make.conf(5)  for
              information  about ACCEPT_LICENSE, and see portage(5) for infor-
              mation about /etc/portage/package.license.

       PROPERTIES
              The PROPERTIES variable in an ebuild file can be  used  to  mask
              packages  based  on properties restrictions. emerge examines the
              ACCEPT_PROPERTIES environment variable to allow or disallow  the
              emerging of a package masked by PROPERTIES. See make.conf(5) for
              information about  ACCEPT_PROPERTIES,  and  see  portage(5)  for
              information   about   /etc/portage/package.properties.  Use  the
              --accept-properties option to temporarily override  ACCEPT_PROP-
              ERTIES.

       RESTRICT
              The  RESTRICT  variable  in  an  ebuild file can be used to mask
              packages  based  on  RESTRICT  tokens.   emerge   examines   the
              ACCEPT_RESTRICT  environment  variable  to allow or disallow the
              emerging of a package masked by RESTRICT. See  make.conf(5)  for
              information about ACCEPT_RESTRICT, and see portage(5) for infor-
              mation  about  /etc/portage/package.accept_restrict.   Use   the
              --accept-restrict     option     to     temporarily     override
              ACCEPT_RESTRICT.

CONFIGURATION FILES
       Portage has a special feature called "config file protection". The pur-
       pose of this feature is to prevent new package installs from clobbering
       existing configuration files. By default,  config  file  protection  is
       turned on for /etc and the KDE configuration dirs; more may be added in
       the future.

       When Portage installs a file into a protected directory tree like /etc,
       any  existing files will not be overwritten. If a file of the same name
       already exists, Portage will change the  name  of  the  to-be-installed
       file  from 'foo' to '._cfg0000_foo'. If '._cfg0000_foo' already exists,
       this name becomes '._cfg0001_foo', etc. In this way, existing files are
       not  overwritten,  allowing the administrator to manually merge the new
       config files and avoid any unexpected changes.

       In addition to protecting overwritten files, Portage  will  not  delete
       any  files from a protected directory when a package is unmerged. While
       this may be a little bit untidy, it does prevent  potentially  valuable
       config files from being deleted, which is of paramount importance.

       Protected  directories  are set using the CONFIG_PROTECT variable, nor-
       mally defined in make.globals. Directory exceptions to the  CONFIG_PRO-
       TECTed directories can be specified using the CONFIG_PROTECT_MASK vari-
       able.  To find files that need to be updated in /etc,  type  find  /etc
       -name '._cfg????_*'.

       You   can  disable  this  feature  by  setting  CONFIG_PROTECT="-*"  in
       make.conf(5).  Then, Portage will mercilessly auto-update  your  config
       files.  Alternatively, you can leave Config File Protection on but tell
       Portage that it can overwrite files in certain specific /etc  subdirec-
       tories. For example, if you wanted Portage to automatically update your
       rc scripts and your wget  configuration,  but  didn't  want  any  other
       changes  made  without  your  explicit  approval,  you'd  add  this  to
       make.conf(5):

       CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"

CONFIGURATION FILES UPDATE TOOLS
       Tools such as dispatch-conf, cfg-update, and etc-update are also avail-
       able  to  aid  in  the merging of these files. They provide interactive
       merging and can auto-merge trivial changes.

REPORTING BUGS
       Please report any bugs you encounter through our website:

       https://bugs.gentoo.org/

       Please include the output of emerge --info when  you  submit  your  bug
       report.

AUTHORS
       Daniel Robbins <drobbins@gentoo.org>
       Geert Bevin <gbevin@gentoo.org>
       Achim Gottinger <achim@gentoo.org>
       Nicholas Jones <carpaski@gentoo.org>
       Phil Bordelon <phil@thenexusproject.org>
       Mike Frysinger <vapier@gentoo.org>
       Marius Mauch <genone@gentoo.org>
       Jason Stubbs <jstubbs@gentoo.org>
       Brian Harring <ferringb@gmail.com>
       Zac Medico <zmedico@gentoo.org>
       Arfrever Frehtes Taifersar Arahesis <arfrever@apache.org>

FILES
       Here is a common list of files you will probably be interested in.  For
       a complete listing, please refer to the portage(5) man page.

       /usr/share/portage/config/sets/
              Contains the default set configuration.

       /var/lib/portage/world
              Contains a list of all user-specified packages.  You can  safely
              edit  this  file, adding packages that you want to be considered
              in world set updates and removing those that you do not want  to
              be considered.

       /var/lib/portage/world_sets
              This is like the world file but instead of package atoms it con-
              tains packages sets which always begin with the @ character. Use
              /etc/portage/sets/ to define user package sets.

       /etc/portage/make.conf
              Contains  variables  for  the build process, overriding those in
              make.globals.

       /etc/portage/color.map
              Contains variables customizing colors.

       /etc/portage/sets/
              Contains user package set definitions (see portage(5)).

       /etc/dispatch-conf.conf
              Contains settings to handle automatic updates/backups of config-
              uration files.

       /etc/portage/make.profile/make.defaults
              Contains  profile-specific  variables for the build process.  Do
              not edit this file.

       /usr/portage/profiles/use.desc
              Contains the master list of USE flags with descriptions of their
              functions.  Do not edit this file.

       /etc/portage/make.profile/virtuals
              Contains  a  list  of  default  packages used to resolve virtual
              dependencies.  Do not edit this file.

       /etc/portage/make.profile/packages
              Contains a list of packages used for the base system.  The  sys-
              tem and world sets consult this file.  Do not edit this file.

       /usr/share/portage/config/make.globals
              Contains  the  default  variables for the build process.  Do not
              edit this file.

       /var/log/emerge.log
              Contains a log  of  all  emerge  output.  This  file  is  always
              appended to, so if you want to clean it, you need to do so manu-
              ally.

       /var/log/emerge-fetch.log
              Contains a log of all the fetches in the previous emerge invoca-
              tion.

       /var/log/portage/elog/summary.log
              Contains  the  emerge  summaries.  Installs /etc/logrotate/elog-
              save-summary.

SEE ALSO
       emerge  --help,  quickpkg(1),   ebuild(1),   ebuild(5),   make.conf(5),
       color.map(5), portage(5)

       A number of helper applications reside in /usr/lib/portage/bin.

       The  app-portage/gentoolkit  package  contains  useful  scripts such as
       equery (a package query tool).



Portage 2.3.3                      Jul 2016                          EMERGE(1)
comments powered by Disqus