gistfile1.txt

CAVE-RESOLVE(1)                                                CAVE-RESOLVE(1)



NAME
       cave-resolve - Display how to resolve one or more targets, and possibly
       then perform that resolution.

SYNOPSIS
       cave resolve [ -x|--execute ] [ -z|--lazy or -c|--complete or
       -e|--everything ] spec ...

       cave resolve [ -x|--execute ] [ -z|--lazy or -c|--complete or
       -e|--everything ] set

       cave resolve [ -x|--execute ] !spec ...

DESCRIPTION
       Displays how to resolve one or more targets. If instructed, then
       executes the relevant install and uninstall actions to perform that
       resolution.

OPTIONS
   Global Options
       Global options, used by every subcommand.

       -h , --help
           display help message

RESOLUTION OPTIONS
   Execution Options
       Control execution.

       -x , --execute (+x , --no-execute)
           Execute the suggested actions

   Convenience Options
       Broad behaviour options. These options are simply a convenient way of
       selecting common groups of other options; see individual option
       descriptions for exact details.

       -z , --lazy (+z , --no-lazy)
           Do as little work as possible. Shorthand for '-Sb -sb -n'.

       -c , --complete (+c , --no-complete)
           Do all optional work. This option is often used when updating
           'world'. Shorthand for '-ks -Rw -Sa -sa -B'.

       -e , --everything (+e , --no-everything)
           Do all optional work, and also always reinstall. Shorthand for '-kt
           -Sa -sa -B'.

   Resolution Options
       Resolution options.

       -U , --permit-uninstall
           Permit uninstallation of packages matching the supplied
           specification, e.g. to resolve blockers. May be specified multiple
           times. Use '*/*' to allow all uninstalls, but note that the
           resolver will sometimes come up with extremely bad solutions to
           fixing blocks and may suggest stupid and dangerous uninstalls.

       -d , --permit-downgrade
           Permit downgrades matching the supplied specification. Use '*/*' to
           allow all downgrades.

       -o , --permit-old-version
           Permit installs of versions matching the supplied specification
           even if those versions are worse than the best visible version in
           the slot. Use '*/*' to allow all worse versions to be installed.

       -P , --purge
           Purge packages matching the given specification, if they will no
           longer be used after a resolution. Use '*/*' to accept all purges,
           but note that by doing so you are putting a great deal of trust in
           package authors to get dependencies right.

       --no-override-masks (--no-no-override-masks)
           If otherwise unable to make a decision, unless this option is
           specified the resolver will try packages that are weakly masked
           too.

       --no-override-flags (--no-no-override-flags)
           If otherwise unable to make a decision, unless this option is
           specified the resolver will try selecting packages using different
           options to the ones specified in the user’s configuration.

       --no-restarts-for
           Do not restart if the problematic package has the specified package
           name. May be specified multiple times. Use '*/*' to avoid all
           restarts.

       --promote-binaries
           Select when to promote packages from binary repositories

           never (n)
               Never (default)

           if-same (s)
               If it has the same version and exactly matching use flags

   Dependent Options
       Dependent options. A package is dependent if it requires (or looks like
       it might require) a package which is being removed. By default,
       dependent packages are treated as errors. These options specify a
       different behaviour.

       -u , --uninstalls-may-break
           Permit uninstalls that might break packages matching the specified
           specification. May be specified multiple times. Use '*/*' to allow
           all packages to be broken. Use 'system' to allow system packages to
           be uninstalled.

       -r , --remove-if-dependent
           Remove dependent packages that might be broken by other changes if
           those packages match the specified specification. May be specified
           multiple times. Use '*/*' to remove all dependent packages that
           might be broken, recursively.

       -l , --less-restrictive-remove-blockers
           Use less restrictive blockers for packages matching the supplied
           specification if that package is to be removed by
           --remove-if-dependent. May be specified multiple times. Normally
           removing dependents is done by a pseudo-block in the form
           '!cat/pkg:slot'. If matched by this option, the block will instead
           only block the installed dependent package, so if reinstalling or
           upgrading the package will make it no longer be dependent then this
           will be done instead.

       -D , --reinstall-dependents-of
           Force any installed package that is dependent upon any installed
           package matching the supplied spec to be reinstalled. May be
           specified multiple times. May be combined with --not-usable to
           obtain a particular ordering. Note that a target must still be
           specified if this option is used, so the 'nothing' set may be
           helpful.

   Reinstall Options
       Control whether installed packages are kept.

       -K , --keep-targets
           Select whether to keep target packages

           auto (a)
               If the target is a set, if-same, otherwise never (default)

           never (n)
               Never

           if-transient (t)
               Only if the installed package is transient (e.g. from 'cave
               import')

           if-same-metadata (m)
               If it is the same as the proposed replacement (that is, if it
               has the same version, and no non-special use flags or choices
               have had their values changed), and if significant metadata has
               not been modified

           if-same (s)
               If it is the same as the proposed replacement (that is, if it
               has the same version, and no non-special use flags or choices
               have had their values changed)

           if-same-version (v)
               If it is the same version as the proposed replacement

           if-possible (p)
               If possible

       -k , --keep
           Select whether to keep installed packages that are not targets

           never (n)
               Never

           if-transient (t)
               Only if the installed package is transient (e.g. from 'cave
               import') (default if --everything)

           if-same-metadata (m)
               If it is the same as the proposed replacement (that is, if it
               has the same version, and no non-special use flags or choices
               have had their values changed), and if significant metadata has
               not been modified

           if-same (s)
               If it is the same as the proposed replacement (that is, if it
               has the same version, and no non-special use flags or choices
               have had their values changed) (default if --complete)

           if-same-version (v)
               If it is the same version as the proposed replacement

           if-possible (p)
               If possible (default)

       -R , --reinstall-scm
           Select whether to reinstall SCM packages that would otherwise be
           kept

           always (a)
               Always

           daily (d)
               If they were installed more than a day ago

           weekly (w)
               If they were installed more than a week ago (default if
               --complete)

           never (n)
               Never (default)

       -w , --with
           Never keep installed packages with the supplied package name. May
           be specified multiple times.

       -W , --without
           Keep installed packages with the supplied package name if possible.
           May be specified multiple times.

   Slot Options
       Control which slots are considered.

       -S , --target-slots
           Which slots to consider for targets

           best-or-installed (x)
               Consider the best slot, if it is not installed, or all
               installed slots otherwise (default)

           installed-or-best (i)
               Consider all installed slots, or the best installable slot if
               nothing is installed

           all (a)
               Consider all installed slots and the best installable slot
               (default if --complete or --everything)

           best (b)
               Consider the best installable slot only (default if --lazy)

       -s , --slots
           Which slots to consider for packages that are not targets

           best-or-installed (x)
               Consider the best slot, if it is not installed, or all
               installed slots otherwise (default)

           installed-or-best (i)
               Consider all installed slots, or the best installable slot if
               nothing is installed

           all (a)
               Consider all installed slots and the best installable slot
               (default if --complete or --everything)

           best (b)
               Consider the best installable slot only (default if --lazy)

   Dependency Options
       Control which dependencies are followed.

       -B , --follow-installed-build-dependencies (+B ,
       --no-follow-installed-build-dependencies)
           Follow build dependencies for installed packages (default if
           --complete or --everything)

       -n , --no-follow-installed-dependencies (+n ,
       --no-no-follow-installed-dependencies)
           Ignore dependencies (except compiled-against dependencies, which
           are always taken) for installed packages. (default if --lazy)

       -0 , --no-dependencies-from
           Ignore dependencies (not blockers) from packages matching the
           supplied specification. May be specified multiple times. Use '*/*'
           to ignore all dependencies. Use of this option can lead to horrible
           breakages.

       -! , --no-blockers-from
           Ignore blockers from packages matching the supplied specification.
           May be specified multiple times. Use '*/*' to ignore all blockers.
           Use of this option can lead to horrible breakages.

   Suggestion Options
       Control whether suggestions are taken. Suggestions that are already
       installed are instead treated as hard dependencies.

       --suggestions
           How to treat suggestions and recommendations

           ignore
               Ignore suggestions

           display
               Display suggestions, but do not take them unless explicitly
               told to do so (default)

           take
               Take all suggestions

       --recommendations
           How to treat recommendations

           ignore
               Ignore recommendations

           display
               Display recommendations, but do not take them unless explicitly
               told to do so

           take
               Take all recommendations (default)

       -t , --take
           Take any suggestion matching the supplied package specification or
           suggestion group name (e.g. --take 'app-vim/securemodelines' or
           --take 'app-vim/*' or --take send-email)

       -T , --take-from
           Take all suggestions made by any package matching the supplied
           package specification

       -i , --ignore
           Discard any suggestion matching the supplied package specification
           or group name

       -I , --ignore-from
           Discard all suggestions made by any package matching the supplied
           package specification

   Package Selection Options
       Control which packages are selected.

       -F , --favour
           If there is a choice (e.g. || ( ) dependencies), favour the
           specified package names

       --favour-matching
           If there is a choice (e.g. || ( ) dependencies), favour specs which
           match all of the packages matching the supplied spec

       -A , --avoid
           If there is a choice (e.g. || ( ) dependencies), avoid the
           specified package names

       --avoid-matching
           If there is a choice (e.g. || ( ) dependencies), avoid specs which
           match any of the packages matching the supplied spec

       -p , --preset
           Preset a given constraint. For example, --preset =cat/pkg-2.1 will
           tell the resolver to use that particular version. Note that this
           may lead to errors, if the specified version does not satisfy other
           constraints. Also note that specifying a preset will not force a
           package to be considered if it would otherwise not be part of the
           resolution set.

       -H , --hide
           When selecting origin ID candidates, pretend that any ID matching
           the specified spec does not exist. For example, --hide */*::foo can
           be used to avoid selecting any ID in the foo repository. May be
           specified multiple times.

   Package Ordering Options
       Control the order in which packages are installed

       -N , --not-usable
           Consider installed packages matching the supplied specification as
           being unusable when breaking dependency cycles. May be specified
           multiple times. Note that this option affects only ordering; it
           does not also force a reinstall of these packages.

       -E , --early
           When given a collection of otherwise equally desirable packages to
           order, order packages matching the supplied spec first.

       -L , --late
           When given a collection of otherwise equally desirable packages to
           order, order packages matching the supplied spec last.

   Destination Options
       Control to which destinations targets are installed. Dependencies will
       always be installed to / as necessary.

       -m , --make
           Specify what to do with targets.

           auto (a)
               'install', or 'chroot' if the preferred root is not / (default)

           install (i)
               Install targets to /

           binaries (b)
               Create binary packages for targets

           chroot (c)
               Install targets to a chroot

       -M , --make-dependencies
           Specify what to do with dependencies of targets. Only useful when
           '--make' is not set to 'install', since dependencies on / are
           considered specially.

           auto
               Select appropriate behaviour based upon --make. For 'install',
               'all', and for 'binaries' and 'chroot', 'runtime'. (default)

           runtime (r)
               Only care about runtime dependencies

           all (a)
               Care about all dependencies

           none (n)
               Don’t care about dependencies at all

       -b , --via-binary
           When building a package matching the supplied spec, create a binary
           package and use that for the install. May be specified multiple
           times. If this option is not specified, a package will be built
           multiple times for multiple destinations

       -/ , --dependencies-to-slash
           Specify what to do with dependencies for the / filesystem when not
           working on /. By default, all dependencies are installed to /.

           all (a)
               Send all dependencies to / (default)

           runtime (r)
               Send only runtime dependencies to /

           build (b)
               Send only build dependencies to /

           none (n)
               Don’t send dependencies to / at all

       --one-binary-per-slot (--no-one-binary-per-slot)
           When building a binary package, remove other versions in the same
           repository and slot (as would be done for non-binary packages).

       --chroot-path
           When making a chroot, only consider destination repositories whose
           root is this value.

   Error-ignoring Options
       Allow certain kinds of resolution errors to be ignored. Highly
       dangerous; using these options will very likely result in your system
       becoming impressively or subtly broken. Note that errors will still be
       shown, but the resolution will be allowed to proceed to execution
       anyway.

       --ignore-unable-decisions (--no-ignore-unable-decisions)
           Ignore any resolvent for which we were unable to make a decision.
           Specifying this will break your system.

       --ignore-unorderable-jobs (--no-ignore-unorderable-jobs)
           Ignore any job we were unable to order. Specifying this will break
           your system.

   Dump Options
       Dump the resolver’s state to stdout after completion, or when an error
       occurs. For debugging purposes; produces rather a lot of noise.

       --dump (--no-dump)
           Dump debug output

       --dump-restarts (--no-dump-restarts)
           Dump restarts

EXECUTION OPTIONS
   World Options
       Options controlling how the 'world' set is modified

       -1 , --preserve-world (+1 , --no-preserve-world)
           Do not modify the 'world' set

   Failure Options
       Failure handling options.

       -C , --continue-on-failure
           Whether to continue after an error occurs

           never (n)
               Never (default)

           if-satisfied (s)
               If remaining packages' dependencies are satisfied

           if-independent (i)
               If remaining packages do not depend upon any failing package

           always (a)
               Always (dangerous)

       --resume-file (--no-resume-file)
           Write resume information to the specified file. If a build fails,
           or if '--execute' is not specified, then 'cave resume' can resume
           execution from this file.

   Jobs Options
       Options controlling jobs and parallelism.

       -f , --fetch (+f , --no-fetch)
           Skip any jobs that are not fetch jobs. Should be combined with
           --continue-on-failure if any of the packages to be merged have
           fetch dependencies.

       -J , --fetch-jobs
           The number of parallel fetch jobs to launch. If set to 0, fetches
           will be carried out sequentially with other jobs. Values higher
           than 1 are currently treated as being 1. Defaults to 1, or if
           --fetch is specified, 0.

   Phase Options
       Options controlling which phases to execute. No sanity checking is
       done, allowing you to shoot as many feet off as you desire. Phase names
       do not have the src_, pkg_ or builtin_ prefix, so 'init', 'preinst',
       'unpack', 'merge', 'strip' etc.

       --skip-phase
           Skip the named phases

       --abort-at-phase
           Abort when a named phase is encountered

       --skip-until-phase
           Skip every phase until a named phase is encountered

       --change-phases-for
           Control to which package or packages these phase options apply

           all
               All packages (default)

           first
               Only the first package on the list

           !first
               Everything except the first package on the list

           last
               Only the last package on the list

           !last
               Everything except the last package on the list

           targets
               Only packages that are targets

           !targets
               Only packages that are not targets

DISPLAY OPTIONS
   Display Options
       Options relating to the resolution display.

       --show-option-descriptions
           Whether to display descriptions for package options

           none
               Don’t show any descriptions

           new
               Show for any new options

           changed
               Show for new or changed options (default)

           all
               Show all options

       --show-descriptions
           Whether to display package descriptions

           none
               Don’t show any descriptions

           new
               Show for new packages (default)

           all
               Show for all packages

   Explanations
       Options requesting the resolver explain a particular decision that it
       made

       -X , --explain
           Explain why the resolver made a particular decision. The argument
           is a package dependency specification, so --explain dev-libs/boost
           or --explain qt:3 or even --explain '*/*' (although --dump is a
           better way of getting highly noisy debug output).

GRAPH JOBS OPTIONS
   Graph Jobs Options
       Options relating to creating graphs for jobs. If --graph-jobs-basename
       is specified, a Graphviz graph will be created for the jobs in the
       resolution.

       --graph-jobs-basename
           Specify the basename (filename without extension) to be used when
           creating job graphs. If unspecified, no jobs graph will be created.

       --graph-jobs-format
           Specifies the desired output format for the Graphviz graph. The
           argument must be a valid value for the '-T' option for Graphviz.
           Also determines the file extension of the generated graph. If
           unspecified, only a raw graph file will be created, and it will not
           be processed using Graphviz.

   Graph Jobs Format Options
       Options relating to the format of created graphs.

       --graph-jobs-all-arrows (--no-graph-jobs-all-arrows)
           Show all arrows. By default dependencies required only for
           if-independent are not shown, since for non-trivial resolutions
           Graphviz will otherwise require obscene amounts of memory.

       --graph-jobs-full-names (--no-graph-jobs-full-names)
           Show full names for graph jobs.

PROGRAM OPTIONS
   Program Options
       Options controlling which programs are used to carry out various tasks.
       Any replacement to the standard program must provide exactly the same
       interface. In all cases, $CAVE can be used to get the path of the main
       'cave' executable. Note that unless an option is explicitly specified,
       an internal implementation of the default command might be used instead
       of spawning a new process.

       --display-resolution-program
           The program used to display the resolution. Defaults to '$CAVE
           display-resolution'.

       --graph-jobs-resolution-program
           The program used to graph jobs. Defaults to '$CAVE graph-jobs'.

       --execute-resolution-program
           The program used to execute the resolution. Defaults to '$CAVE
           execute-resolution'.

       --perform-program
           The program used to perform actions. Defaults to '$CAVE perform'.

       --update-world-program
           The program used to perform world updates. Defaults to '$CAVE
           update-world'.

       --graph-program
           The program used to create Graphviz graphs. Defaults to 'dot'.



                                  11/22/2014                   CAVE-RESOLVE(1)