commit: 692759d4e74b958dff78f86a53a3b56f4920a980
Author: Fabian Groffen <grobian <AT> gentoo <DOT> org>
AuthorDate: Mon Apr 8 08:56:21 2019 +0000
Commit: Fabian Groffen <grobian <AT> gentoo <DOT> org>
CommitDate: Mon Apr 8 08:56:21 2019 +0000
URL: https://gitweb.gentoo.org/proj/portage-utils.git/commit/?id=692759d4
qdepends: update manpage for rewrite
Signed-off-by: Fabian Groffen <grobian <AT> gentoo.org>
man/include/qdepends-05-examples.include | 20 +++-----
man/include/qdepends.desc | 33 ++++++++++----
man/include/qdepends.optdesc.yaml | 11 +++--
man/qdepends.1 | 78 ++++++++++++++++----------------
qdepends.c | 6 +--
5 files changed, 79 insertions(+), 69 deletions(-)
diff --git a/man/include/qdepends-05-examples.include
b/man/include/qdepends-05-examples.include
index 04fb92f..d3eac01 100644
--- a/man/include/qdepends-05-examples.include
+++ b/man/include/qdepends-05-examples.include
@@ -1,25 +1,19 @@
.SH "EXAMPLES"
For finding out what a particular package depends on for building, you could
do:
.nf
- $ \fIqdepends nano\fR
+ $ \fIqdepends -d nano\fR
app-editors/nano-2.3.2: >=sys-libs/ncurses-5.9-r1[unicode]
sys-apps/file ...
.fi
This tells us that we have \fIapp-editors/nano-2.3.2\fR installed and it
depends
on ncurses (among other things).
-
-Searching for packages that actually have nano in their RDEPEND:
+.P
+Searching for packages that actually depend on logrotate:
.nf
- $ \fIqdepends -rQ nano\fR
- virtual/editor-0
+ $ \fIqdepends -qQ logrotate\fR
+ sys-apps/portage-2.3.18: !<app-admin/logrotate-3.8.0
.fi
-Tells us that \fIvirtual/editor\fR depends on nano. However, if we
-wanted to know in what way a package specifically depends on another
-package, one can use \fB\-v\fR.
-.nf
- $ \fIqdepends -vrQ logrotate\fR
- sys-apps/portage-2.3.18: >=app-admin/logrotate-3.8.0
-.fi
-This way we can see there is a specific dependency expressed here. If
+The \fB-q\fR flag suppresses the entire list of dependencies here, so we
+can quickly see what specific dependency is expressed here. If
the above had used \fI<logrotate-3\fR, for example, no matches would be
returned. Not using any specifiers allows to reveal in what way a
dependency is expressed.
diff --git a/man/include/qdepends.desc b/man/include/qdepends.desc
index 0143847..070032e 100644
--- a/man/include/qdepends.desc
+++ b/man/include/qdepends.desc
@@ -1,15 +1,30 @@
The
.I qdepends
-applet has a couple different modes. Normally it is geared towards
-answering the queries "what does package X depend on" and "what packages depend
-on X". Both can further be classified into build, run, and post dependencies.
-
-By default, it will tell you the build time dependencies only (DEPEND).
-
+applet has two different modes, forward and reverse dependency querying.
+Default operation is forward mode, answering the queries "what does
+package X depend on", while reverse mode answers "what packages depend
+on X". Both modes can be further specified into build (DEPEND), run
+(RDEPEND), post (PDEPEND) and EAPI7's BDEPEND dependencies.
+.P
+By default, \fIqdepends\fR returns the unique set of atoms that match
+all dependency variables. To split this out per variable, use \fB-v\fR
+option.
+.P
Currently,
.I qdepends
will only query installed packages. There is no support for
querying packages not yet installed (see \fBequery\fR(1) for that).
-
-If there is no answer to your query (i.e. you've asked for a package that is
not
-installed, or a version that does not match), then you will get back no output.
+.P
+If there is no answer to your query (i.e. you've asked for a package
+that is not installed, or a version that does not match), then you will
+get empty output.
+.P
+After version \fB0.74\fR of portage-utils, \fIqdepends\fR was changed
+considerably to be more consistent and more advanced. Most notably,
+this has changed default output for reverse mode (\fB-Q\fR). Instead of
+just displaying the package name, like for forward mode, all
+dependencies for the package are shown. When colours are enabled, the
+matched atom is highlighted in the list. In addition to just querying
+DEPEND, the default mode changed to query all DEPEND-variables, and
+return the unique atoms found in them. Automatic regular expression
+match support was removed.
diff --git a/man/include/qdepends.optdesc.yaml
b/man/include/qdepends.optdesc.yaml
index 5d786f3..f317227 100644
--- a/man/include/qdepends.optdesc.yaml
+++ b/man/include/qdepends.optdesc.yaml
@@ -16,14 +16,15 @@ format: |
Pretty-print DEPEND declaration to be used in an ebuild. This
option initiates a very different mode of operation. Instead of
printing searching through packages, it constructs a multi-line
- statement in with shell syntax, to be used in an ebuild. Each
+ statement with shell syntax, to be used in an ebuild. Each
argument is turned into a separate DEPEND variable declaration. You
need to quote dependency strings in order for them to be printed as
a single dependency declaration. When used with the \fB\-q\fR
option, only the pretty-printed dependency declaration is printed,
e.g.\ the DEPEND= part is skipped.
verbose: |
- When in reverse dep mode, print the package or packages that matched
- the query from the dependency line being searched. This includes
- specifiers and versions.
-quiet: Suppress DEPEND= output for \fB\-f\fR.
+ Pretty-print atoms output, per DEPEND-variable. This is much like
+ the \fB-f\fR option, but uses as input the dependency info from the
+ matches.
+quiet: Suppress DEPEND= output for \fB\-f\fR. Only print the matching
+ atom for \fB\-Q\fR.
diff --git a/man/qdepends.1 b/man/qdepends.1
index f5c8c01..dcaef0c 100644
--- a/man/qdepends.1
+++ b/man/qdepends.1
@@ -1,5 +1,5 @@
.\" generated by mkman.py, please do NOT edit!
-.TH qdepends "1" "Feb 2019" "Gentoo Foundation" "qdepends"
+.TH qdepends "1" "Apr 2019" "Gentoo Foundation" "qdepends"
.SH NAME
qdepends \- show dependency info
.SH SYNOPSIS
@@ -8,23 +8,38 @@ qdepends \- show dependency info
.SH DESCRIPTION
The
.I qdepends
-applet has a couple different modes. Normally it is geared towards
-answering the queries "what does package X depend on" and "what packages depend
-on X". Both can further be classified into build, run, and post dependencies.
-
-By default, it will tell you the build time dependencies only (DEPEND).
-
+applet has two different modes, forward and reverse dependency querying.
+Default operation is forward mode, answering the queries "what does
+package X depend on", while reverse mode answers "what packages depend
+on X". Both modes can be further specified into build (DEPEND), run
+(RDEPEND), post (PDEPEND) and EAPI7's BDEPEND dependencies.
+.P
+By default, \fIqdepends\fR returns the unique set of atoms that match
+all dependency variables. To split this out per variable, use \fB-v\fR
+option.
+.P
Currently,
.I qdepends
will only query installed packages. There is no support for
querying packages not yet installed (see \fBequery\fR(1) for that).
-
-If there is no answer to your query (i.e. you've asked for a package that is
not
-installed, or a version that does not match), then you will get back no output.
+.P
+If there is no answer to your query (i.e. you've asked for a package
+that is not installed, or a version that does not match), then you will
+get empty output.
+.P
+After version \fB0.74\fR of portage-utils, \fIqdepends\fR was changed
+considerably to be more consistent and more advanced. Most notably,
+this has changed default output for reverse mode (\fB-Q\fR). Instead of
+just displaying the package name, like for forward mode, all
+dependencies for the package are shown. When colours are enabled, the
+matched atom is highlighted in the list. In addition to just querying
+DEPEND, the default mode changed to query all DEPEND-variables, and
+return the unique atoms found in them. Automatic regular expression
+match support was removed.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-depend\fR
-Show DEPEND info (default).
+Show DEPEND info.
.TP
\fB\-r\fR, \fB\-\-rdepend\fR
Show RDEPEND info.
@@ -35,13 +50,7 @@ Show PDEPEND info.
\fB\-b\fR, \fB\-\-bdepend\fR
Show BDEPEND info.
.TP
-\fB\-k\fR \fI<arg>\fR, \fB\-\-key\fR \fI<arg>\fR
-Advanced option to allow querying the VDB. This option overrides
-\fB\-d\fR, \fB\-r\fR, \fB\-p\fR, \fB\-b\fR or \fB\-a\fR.
-\fI<arg>\fR can be any key from Portage's VDB, e.g.\ any file from
-var/db/pkg/<cat>/<pkg>/.
-.TP
-\fB\-Q\fR \fI<arg>\fR, \fB\-\-query\fR \fI<arg>\fR
+\fB\-Q\fR, \fB\-\-query\fR
Query reverse deps. This basically reverses the search to any
package that references \fI<arg>\fR in DEPEND, RDEPEND, PDEPEND or BDEPEND.
This can be useful to find consumers of a given package, e.g.\ to
@@ -50,14 +59,11 @@ search for packages that have \fIlogwatch\fR in their
DEPEND.
\fB\-N\fR, \fB\-\-name\-only\fR
Only show category/package, instead of category/package-version.
.TP
-\fB\-a\fR, \fB\-\-all\fR
-Show *DEPEND, alias for \fB\-drpb\fR.
-.TP
\fB\-f\fR, \fB\-\-format\fR
Pretty-print DEPEND declaration to be used in an ebuild. This
option initiates a very different mode of operation. Instead of
printing searching through packages, it constructs a multi-line
-statement in with shell syntax, to be used in an ebuild. Each
+statement with shell syntax, to be used in an ebuild. Each
argument is turned into a separate DEPEND variable declaration. You
need to quote dependency strings in order for them to be printed as
a single dependency declaration. When used with the \fB\-q\fR
@@ -68,12 +74,12 @@ e.g.\ the DEPEND= part is skipped.
Set the ROOT env var.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
-When in reverse dep mode, print the package or packages that matched
-the query from the dependency line being searched. This includes
-specifiers and versions.
+Pretty-print atoms output, per DEPEND-variable. This is much like
+the \fB-f\fR option, but uses as input the dependency info from the
+matches.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
-Suppress DEPEND= output for \fB\-f\fR.
+Suppress DEPEND= output for \fB\-f\fR. Only print the matching atom for
\fB\-Q\fR.
.TP
\fB\-C\fR, \fB\-\-nocolor\fR
Don't output color.
@@ -86,25 +92,19 @@ Print version and exit.
.SH "EXAMPLES"
For finding out what a particular package depends on for building, you could
do:
.nf
- $ \fIqdepends nano\fR
+ $ \fIqdepends -d nano\fR
app-editors/nano-2.3.2: >=sys-libs/ncurses-5.9-r1[unicode]
sys-apps/file ...
.fi
This tells us that we have \fIapp-editors/nano-2.3.2\fR installed and it
depends
on ncurses (among other things).
-
-Searching for packages that actually have nano in their RDEPEND:
-.nf
- $ \fIqdepends -rQ nano\fR
- virtual/editor-0
-.fi
-Tells us that \fIvirtual/editor\fR depends on nano. However, if we
-wanted to know in what way a package specifically depends on another
-package, one can use \fB\-v\fR.
+.P
+Searching for packages that actually depend on logrotate:
.nf
- $ \fIqdepends -vrQ logrotate\fR
- sys-apps/portage-2.3.18: >=app-admin/logrotate-3.8.0
+ $ \fIqdepends -qQ logrotate\fR
+ sys-apps/portage-2.3.18: !<app-admin/logrotate-3.8.0
.fi
-This way we can see there is a specific dependency expressed here. If
+The \fB-q\fR flag suppresses the entire list of dependencies here, so we
+can quickly see what specific dependency is expressed here. If
the above had used \fI<logrotate-3\fR, for example, no matches would be
returned. Not using any specifiers allows to reveal in what way a
dependency is expressed.
diff --git a/qdepends.c b/qdepends.c
index df3434e..09156f6 100644
--- a/qdepends.c
+++ b/qdepends.c
@@ -210,10 +210,10 @@ qdepends_results_cb(q_vdb_pkg_ctx *pkg_ctx, void *priv)
ret = 1;
if (!firstmatch) {
- printf("%s%s/%s%s%s%s",
+ printf("%s%s/%s%s%s:",
BOLD,
catname, BLUE,
-
qdep_name_only ? datom->PN : pkgname, NORM,
- quiet ?
"" : ":");
+
qdep_name_only ? datom->PN : pkgname,
+ NORM);
}
firstmatch = true;
