cave resolve
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).
- -2 , --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'.