Paludis Logo Introduction cave  
Bugs, Requests, Support    
Overview    
FAQ    
Clients    
Configuration    
API    

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'.