diff options
author | 2011-03-12 22:24:17 +0000 | |
---|---|---|
committer | 2011-03-12 22:26:19 +0000 | |
commit | 820339f780d0d648db831289b9d8a14b74a87f34 (patch) | |
tree | f35f52448de670f274c5d280f2dcddbf75c52e42 | |
parent | 76aad4b12cfe9ad580e49929d1adcf111f52451c (diff) | |
download | paludis-820339f780d0d648db831289b9d8a14b74a87f34.tar.gz paludis-820339f780d0d648db831289b9d8a14b74a87f34.tar.xz |
Maintain cave.txt manually for now
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | src/clients/cave/Makefile.am | 8 | ||||
-rw-r--r-- | src/clients/cave/cave.txt | 391 |
3 files changed, 398 insertions, 2 deletions
diff --git a/.gitignore b/.gitignore index b527f8415..1ac1260b0 100644 --- a/.gitignore +++ b/.gitignore @@ -498,6 +498,7 @@ paludis-*.*.*.tar.bz2 /src/clients/appareo/*.xml /src/clients/cave/cave /src/clients/cave/*.txt +!/src/clients/cave/cave.txt /src/clients/cave/*.xml /src/clients/instruo/instruo /src/clients/instruo/*.txt diff --git a/src/clients/cave/Makefile.am b/src/clients/cave/Makefile.am index 0dfc9e543..b4aada099 100644 --- a/src/clients/cave/Makefile.am +++ b/src/clients/cave/Makefile.am @@ -86,9 +86,12 @@ man_MANS = \ man_MANS_txts = $(man_MANS:.1=.txt) man_MANS_xmls = $(man_MANS_txts:.txt=.xml) +command_MANS_txts = $(command_MANS:.1=.txt) +command_MANS_xmls = $(command_MANS_txts:.txt=.xml) + SUFFIXES = .1 .txt .xml -$(man_MANS_txts) : man-cave +$(command_MANS_txts) : man-cave if ! env \ CAVE_FORMATS_CONF="/dev/null" \ CAVE_COMMANDS_PATH="" \ @@ -211,6 +214,7 @@ TESTS = \ continue_on_failure_TEST EXTRA_DIST = \ + cave.txt \ $(man_MANS) \ $(TESTS) \ continue_on_failure_TEST_setup.sh continue_on_failure_TEST_cleanup.sh \ @@ -219,7 +223,7 @@ EXTRA_DIST = \ DISTCLEANFILES = \ $(man_MANS) \ $(noinst_DATA) \ - $(man_MANS_txts) \ + $(command_MANS_txts) \ $(man_MANS_xmls) lib_LTLIBRARIES = diff --git a/src/clients/cave/cave.txt b/src/clients/cave/cave.txt new file mode 100644 index 000000000..05c64a367 --- /dev/null +++ b/src/clients/cave/cave.txt @@ -0,0 +1,391 @@ +cave(1) +======= + + +NAME +---- + +cave - A commandline client for the other package mangler. + +SYNOPSIS +-------- + +*cave [ --environment class:suffix ] [ --log-level level ] COMMAND [ARGS...]* + +*cave help [ --all ]* + +DESCRIPTION +----------- +The front-end to a number of commands. + +For the COMMAND argument, see \'cave help' for a list of common commands, or +\'cave help --all' for all commands. To see documentation for a command named +\'foo', use \'man cave-foo'. + + +In addition to built-in commands, cave will also look in the directories named +in the colon-separated CAVE_COMMANDS_PATH environment variable, or, if unset, +\'/usr/libexec/cave/commands'. Any executables in this path will also be +available as commands (with any file extension stripped); these executables +may use the $CAVE environment variable to get access to the main cave program. + + +Arguments specified after the COMMAND are handled by the individual commands. +Arguments before the COMMAND are global arguments shared by all commands. + + +OPTIONS +------- +Global Options +~~~~~~~~~~~~~~ +Global options, used by every subcommand. + +*-E , --environment*:: + Environment specification (class:suffix, both parts optional) + +*-L , --log-level*:: + Specify the log level + + *debug (d)*;; + Show debug output (noisy) + + *qa (q)*;; + Show QA messages and warnings only (default) + + *warning (w)*;; + Show warnings only + + *silent (s)*;; + Suppress all log messages (UNSAFE) + + +*-c , --colour*:: + Specify whether to use colour + + *auto (a)*;; + Yes if stdout is connected to a terminal (default) + + *yes (y)*;; + Yes + + *no (n)*;; + No + + +*-h , --help*:: + display help message + +*-v , --version*:: + display version information + +CORE COMMANDS +------------- + +config:: +Perform post-install configuration on a package. Note that most packages do +not provide a post-install configuration script. + +contents:: +Display the contents of (files installed by) a given package ID. + +fix-linkage:: +Identifies packages with broken linkage that can be fixed by rebuilds. If +instructed, then executes the relevant install and uninstall actions to do +said fixing. + +help:: +Display help information for a particular command. + +import:: +Import a package from a directory containing its image. A named directory is +treated as holding the contents to install, and a dummy package name is +provided on the command line. Safe merge, unmerge, upgrade and replace support +is provided, as is content tracking for installed files. + +info:: +Displays a formatted summary of configuration and package information, e.g. +for use when submitting bug reports. The package names of any relevant +packages for bug reports should be passed as parameters. + +owner:: +Shows package IDs owning a given file. + +purge:: +Uninstalls any package that is not either in \'world' or a dependency of a +package in \'world'. + +report:: +Displays a formatted summary of potential problems with installed packages. + +resolve:: +Displays how to resolve one or more targets. If instructed, then executes the +relevant install and uninstall actions to perform that resolution. + +resume:: +Resumes a failed resultion from \'cave resolve'. To enable resumes, use \'cave +resolve --resume-file state --execute', and then if errors occur, use \'cave +resume --resume-file state [ --retry-failed ] [ --retry-skipped ]' to try +again. + +search:: +Searches for packages with particular characteristics. + +show:: +Displays a formatted summary of a given object. If the object is a set, the +set's contents are listed. If the object is a repository name, information +about the repository is displayed. If the object is a package dep spec with +wildcards, possible expansions are shown. If the object is a package dep spec +without wildcards, information about matching IDs are shown. + +sync:: +Syncs repositories. If any repository names are specified, these repositories +are synced. Otherwise, all syncable repositories are synced. + +uninstall:: +Uninstalls one or more packages. Note that \'cave uninstall' simply rewrites +the supplied dependency specifications and then uses \'cave resolve' to do the +work; \'cave uninstall foo' is the same as \'cave resolve !foo'. + +SUPPLEMENTAL COMMANDS +--------------------- + +dump-cave-formats-conf:: +Outputs suitable contents for ~/.cave/formats.conf. This file can be used to +customise the output format for many cave commands (although not commands +designed for script use, such as print-*). + +executables:: +Display executables belonging to an ID. + +fix-cache:: +Fixes on-disk caches. Normally this is handled automatically when needed (e.g. +after a sync, or when a package is installed), but a forced fix-cache is +required after a different package manager has been used, or if a repository +is modified without a sync. + +generate-metadata:: +Pregenerates metadata for a set of IDs. + +manage-search-index:: +Manages a search index for use by cave search. A search index is only valid +until a package is installed or uninstalled, or a sync is performed, or +configuration is changed. + +size:: +Shows the size of files installed by a package. + +sync-protocol-options:: +Displays options for a given sync protocol. + +update-world:: +Adds or removes items from the world set. This command is only for changing +the contents of the world set; it does not install or uninstall anything. + +verify:: +Verify than an installed package's files haven't changed. Note that there are +legitimate reasons for some files (such as configuration files) to have been +changed after a merge, and that some packages may install files that are not +directly tracked by the package manager. + +DEVELOPMENT COMMANDS +-------------------- + +digest:: +Generates a digest file for a particular package in a particular repository. + +mirror:: +Fetches files for a set of IDs. + +SCRIPTING COMMANDS +------------------ + +has-version:: +Returns success if there is an installed package matching a particular spec. +Suitable for use in scripts. + +print-best-version:: +Prints the best installed version matching a particular spec. No formatting is +used, making the output suitable for parsing by scripts. + +print-categories:: +Prints a list of known categories. No formatting is used, making the output +suitable for parsing by scripts. + +print-commands:: +Prints a list of known cave commands. No formatting is used, making the output +suitable for parsing by scripts. + +print-dependent-ids:: +Prints a list of installed IDs that are dependent upon another installed ID. +No formatting is used, making the output suitable for parsing by scripts. + +print-environment-metadata:: +Prints environment metadata. No formatting is used, making the output suitable +for parsing by scripts. + +print-id-actions:: +Prints ID actions. No formatting is used, making the output suitable for +parsing by scripts. + +print-id-contents:: +Prints a list of the contents of a given ID. No formatting is used, making the +output suitable for parsing by scripts. + +print-id-environment-variable:: +Prints ID environment variables. No formatting is used, making the output +suitable for parsing by scripts. + +print-id-executables:: +Prints a list of executables belonging to an ID. No formating is used, making +the script suitable for parsing by scripts. + +print-id-masks:: +Prints ID masks. No formatting is used, making the output suitable for parsing +by scripts. + +print-id-metadata:: +Prints ID metadata. No formatting is used, making the output suitable for +parsing by scripts. + +print-id-size:: +Prints the size of files installed by a package. No formatting is used, making +the output suitable for parsing by scripts. + +print-ids:: +Prints a list of known IDs. No formatting is used, making the output suitable +for parsing by scripts. + +print-owners:: +Prints a list of package IDs owning a given file. No formatting is used, +making the output suitable for parsing by scripts. + +print-packages:: +Prints a list of package names. No formatting is used, making the output +suitable for parsing by scripts. + +print-repositories:: +Prints a list of repositories. No formatting is used, making the output +suitable for parsing by scripts. + +print-repository-formats:: +Prints a list of available repository formats. No formatting is used, making +the output suitable for parsing by scripts. + +print-repository-metadata:: +Prints repository metadata. No formatting is used, making the output suitable +for parsing by scripts. + +print-set:: +Prints the contents (packages or other sets) of a given set. + +print-sets:: +Prints a list of sets. No formatting is used, making the output suitable for +parsing by scripts. + +print-spec:: +Parses a dependency spec and prints it out, possibly after applying certain +modifications. No formatting is used, making the output suitable for parsing +by scripts. + +print-sync-protocols:: +Prints a list of sync protocols. No formatting is used, making the output +suitable for parsing by scripts. + +print-unused-distfiles:: +Prints all distfiles not used by any installed package. No formatting is used, +making the output suitable for parsing by scripts. + +INTERNAL COMMANDS +----------------- + +display-resolution:: +Displays a dependency resolution created using \'cave resolve'. Mostly for +internal use; most users will not use this command directly. + +execute-resolution:: +Execute a dependency resolution created using \'cave resolve'. Mostly for +internal use; most users will not use this command directly. + +find-candidates:: +Finds a list of candidate packages for a search. Used by \'cave search'; not +generally called directly by end users. Note that this command will often +select candidates that do not actually match some of the supplied +restrictions; use \'cave match' to obtain accurate results. + +graph-jobs:: +Creates a Graphviz graph for jobs in a resolution created using \'cave +resolve'. Mostly for internal use; most users will not use this command +directly. + +match:: +Determines whether a particular package version has certain properties. Mostly +for use by \'cave search'; not generally for use by end users. + +perform:: +Perform an action upon a package. Not suitable for direct use, although it may +be useful in some more complex scripts. + +ENVIRONMENT +----------- +CAVE_COMMANDS_PATH:: +Colon-separated paths in which to look for additional commands. + +SEE ALSO +-------- +*cave-config*(1) +*cave-contents*(1) +*cave-fix-linkage*(1) +*cave-help*(1) +*cave-import*(1) +*cave-info*(1) +*cave-owner*(1) +*cave-purge*(1) +*cave-report*(1) +*cave-resolve*(1) +*cave-resume*(1) +*cave-search*(1) +*cave-show*(1) +*cave-sync*(1) +*cave-uninstall*(1) +*cave-dump-cave-formats-conf*(1) +*cave-executables*(1) +*cave-fix-cache*(1) +*cave-generate-metadata*(1) +*cave-manage-search-index*(1) +*cave-size*(1) +*cave-sync-protocol-options*(1) +*cave-update-world*(1) +*cave-verify*(1) +*cave-digest*(1) +*cave-mirror*(1) +*cave-has-version*(1) +*cave-print-best-version*(1) +*cave-print-categories*(1) +*cave-print-commands*(1) +*cave-print-dependent-ids*(1) +*cave-print-environment-metadata*(1) +*cave-print-id-actions*(1) +*cave-print-id-contents*(1) +*cave-print-id-environment-variable*(1) +*cave-print-id-executables*(1) +*cave-print-id-masks*(1) +*cave-print-id-metadata*(1) +*cave-print-id-size*(1) +*cave-print-ids*(1) +*cave-print-owners*(1) +*cave-print-packages*(1) +*cave-print-repositories*(1) +*cave-print-repository-formats*(1) +*cave-print-repository-metadata*(1) +*cave-print-set*(1) +*cave-print-sets*(1) +*cave-print-spec*(1) +*cave-print-sync-protocols*(1) +*cave-print-unused-distfiles*(1) +*cave-display-resolution*(1) +*cave-execute-resolution*(1) +*cave-find-candidates*(1) +*cave-graph-jobs*(1) +*cave-match*(1) +*cave-perform*(1) + |