////
Copyright (c) 2017-2025  Christoph Willing, Brisbane Australia
SPDX-License-Identifier: GPL-3.0-or-later
////

HooRex(1)
=========
:doctype: manpage
:man version: Version '0.10.0'


NAME
----
hoorex - shows which other packages in a SlackBuilds.org (SBo) repository
	depend on a given package(s). The result list of packages is
	ordered such that build dependencies are given before dependent
	packages.


SYNOPSIS
--------
*hoorex* ['OPTIONS'] PKG [PKG ...]


DESCRIPTION
-----------
The hoorex(1) command outputs the names of packages in the SBo repository
tree which depend on the target PKG(s) given on the command line.
Alternatively, using the *-r* (*--reverse*) option, hoorex outputs the
complete dependency tree for the target PKG(s). In both these modes,
output packages are shown in "build order" i.e. any packages which are
build dependencies of others in the result list are output before those
which depend on them.

Dependencies additional to those contained in a package's .info file may
be specified in a quirks file. A default, empty, quirks file is created
at ~/.local/share/hoorex/quirks which may be populated according to the
expected format (see quirks.example in the documentation). An alternative
quirks file may be specified using the *-q* (*--quirkFile*) option.

HooRex displays its output to tty devices with target packages shown in
bold text and dependent packages in plain text; no formatting is applied
to non-tty devices e.g. pipes.

The main purpose of HooRex is to show all other packages which depend
on the target(s) and which might therefore be affected by some change in
the target. Combining this standard mode with the reverse mode results in
an exhaustive listing of all packages that might need to be (re)built in
such a situation.


OPTIONS
-------
*-c, --config*::
    Display contents of the *configuration* file

*-d, --debug*::
    Show additional informational and *debugging* output.

*-f, --force*::
    *Force* reconstruction of the internal cross reference index, taking
    into account any individual package quirks contained in the current
    quirks file (see *-q* (*--quirkFile*) option). It is recommended to
    run with the *-f* (*--force*) option after every update of the local
    repository from the master SBo repository (in case of new dependency
    relationships).

*-g, --group* 'SBO_GROUP [SBO_GROUP ...]'::
    Use a known *group* of packages as input. Groups that HooRex knows
    about include the SBo categories (academic, accessibility, ...,
    system). Another is the "all" group.

*-h, --help*::
    Show HooRex *help* message.

*-1, --column*::
    Show output as a single column i.e. newline separated rather than
    space separated

*-i, --installed*::
    Restrict output to those packages already installed, with the
    exception of the target package(s) which are included.

*-I, --installed_strict*::
    Strictly restrict output to those packages already installed,
    not even the original target packages.

*-l, --long*::
    Show category of each resulting package as well as the package
    e.g. libraries/json-c

*-m, --multilevel*::
    Normally, hoorex outputs the names of packages which directly
    depend on the target PKG(s). In *multilevel* mode, these
    directly depending packages are also processed to find which
    packages depend on them; this process is continued until no
    further depending packages are found.

*-p, --dataPath* 'DATA_PATH'::
    Specify an alternate directory in which to store the package index
    file. The default location is ~/.local/share/hoorex

*-q, --quirkFile* 'QUIRKFILE_PATH'::
    Specify the full path to a quirks file, recalculate the
    dependency tree for future instances of HooRex and then exit.
    The specified quirks file (possibly empty) must already exist.
    The quirks file contains quirks for individual packages, in
    particular *additional* required packages desired to be installed
    prior to building. In effect, such additional packages are
    notionally added to the REQUIRES field of a target package's .info
    file (which itself remains untouched). Run with *-q /dev/null* to
    ignore quirks altogether.

*-r, --reverse*::
    *Reverse* the default calculation of dependency tree i.e. instead of
    determining which other packages require the target package(s),
    calculate which packages are required to build the target package(s).

*-R, --restricted*::
    *Restrict* the output list to those packages named in the input list.

*-s, --slackbuilds* 'SBO_DIRECTORY'::
    Specify full path to the *slackbuilds* directory containing
    the full SlackBuilds.org repository tree.

*-U, --unknown_strict*::
    Unknown packages will normally be quietly ignored and HooRex will
    continue if possible. The previous behaviour, to announce the
    unknown package and exit, is invoked with this flag.

*--version*::
    Show program version number and exit immediately.


USAGE
-----
When hoorex is run for the first time it will attempt to scan the local
slackbuilds directory tree and create an internal index of the dependency
relationships between all the packages found there. Since it will have
no idea where the slackbuilds directory tree is located, hoorex must be
run again, this time with the *-s* (*--slackbuilds*) option e.g.

	hoorex -s /home/kim/slackbuilds

Now, when run again, hoorex will proceed with creating its dependency
index. This can take up to 15sec., depending on the target filesystem
e.g. an nfs mounted filesystem takes longer than a local filesystem.
However this is nominally a once only operation
since the result is saved for future use. After the index is created
and saved, queries are close to instantaneous. The indexing procedure
may be forced at any time using the *-f* (*--force*) option. This is
only required if there is some change in the slackbuilds repository,
such as an update from the master SBo repository or change to a
different git branch with local changes.

Running hoorex with some target package name(s) as argument(s) returns
the names of those packages which directly depend on the target
package(s).  If package A is directly depended on by packages B, C and
D, then running 'hoorex A' will return A B C D.

It may be that any of the depending packages B, C or D may be depended
on by some other package(s). In turn, these may themselves be depended
on by further packages. The full chain of depending packages can be
seen by running hoorex with the *-m* (*--multilievel*) option e.g.

	hoorex -m json-c

Package names may also be passed to hoorex from stdin using a pipe.
Package names input via a pipe are added to any named as an argument i.e.

        echo jason-c | hoorex speex

is equivalent to

        hoorex json-c speex

or

        echo json-c speex | hoorex

A typical use of this ability is to pipe the output of a normal hoorex
instance into a second *-r* (*--reverse*) instance e.g.

	hoorex -m speex | hoorex -r

which first determines all the packages which somehow depend on speex
and then calculates all the packages required to build them.

Care should be taken when restricting output to those packages already
installed
(using *-i* (*--installed*) and *-I* (*--installed_strict*) options).
In particular, these options should probably never be used at the same
time as the *-r* (*--reverse*) option; in this case you need to know
which packages will be needed regardless of whether they're already
installed or not.

Specifying a known group or multiple groups to HooRex enables painless
querying of large numbers of packages. For instance, to use all the
packages in SBo's network and ruby categories as input to HooRex, run:

	hoorex -g network ruby

A special group is the *all* group which consists of all packages known
to HooRex. To generate a build order for the entire SBo repository,
run:

	hoorex -g all -r

Additional packages can be specified as required for specific individual
packages via the use of a .INI format quirks file with entries such as:

        [python-requests]
        QK_REQUIRES = python3

To include the information from such a quirks file, use the *-q*
(*--quirkFile*) option, which rebuilds the dependency tree taking the
quirks from the specified quirks file into account e.g.

        hoorex -q /var/cache/vmbuilder/quirks


EXIT STATUS
-----------
*0*	All OK

*1*	Path to SBo repository is not available

*2*	Package name supplied to HooRex is unknown in the SBo repository
        (only when *-U* (*--unknown_strict*) flag is invoked)

*3*	Path to repo data cache storage directory (specified with
        *-p* (*--dataPath*) option), can't be created

*4*	Path to quirk file (specified with *-q* (*--quirkFile*) option)
        doesn't exist


FILES
-----
*~/.config/hoorex/defaults.cfg*::
    Contains user defaults and preferences
*~/.local/share/hoorex/repoData.pkl*::
    Contains the hoorex cross reference index of repo information.
    It is generated automatically if it doesn't already exist
    or whenever the -f option is invoked. The directory containing
    the repoData.pkl file can be manually specified with the
    *-p* (*--dataPath*) option.
*~/.local/share/hoorex/quirks*::
    Default quirks file location, contains quirks for individual
    packages, although initially empty. This default location may
    be changed with the *-q* (*--quirkFile*) option. Use /dev/null
    as the location to ignore quirks files.


BUGS
----
See the HooRex distribution BUGS file.


AUTHOR
------
HooRex was originally written by Christoph Willing.


RESOURCES
---------
GitLab: <https://gitlab.com/chris.willing/hoorex>


COPYING
-------
Copyright \(C) 2015-2021 Christoph Willing. Free use of this software is
granted under the terms of Version 3 of the GNU General Public
License (GPL). See the HooRex distribution LICENSE.md file for details.
