Documentation/man8/prt-auf.8

.\" man page for prt-auf
.\" last edited June 2022 by John McQuah, jmcquah at disroot dot org
.\" 
.\" based on original work by Johannes Winkelmann, jw at tks6 dot net
.\" 
.\" .PU
.TH "prt-auf" "8" "" "" ""
.SH "NAME"
.LP 
prt\-auf \- add/upgrade frontend to the CRUX pkgutils, inspired by \fBprt\-get\fP(8).

(see http://www.crux.nu for an overview of CRUX ports and pkgutils)
.SH "SYNOPSIS"
.B prt\-auf subcommand [options] <arguments>
.br 
.SH "DESCRIPTION"
prt\-auf is a frontend to the CRUX pkgutils, orchestrating their operation
behind the scenes and letting the user focus on higher-level objectives. It
scans both the local ports tree and the installed package database, to
resolve dependency relationships and to determine which installed packages
are out of date. \fBprt\-auf\fP is especially relevant when you want to:

.PP
.TP 
\ \ \ \(bu
add/update a package without first determining where in the ports tree
its build instructions and dependencies are located

.TP 
\ \ \ \(bu
pass multiple packages on one command line for an add/update operation

.TP 
\ \ \ \(bu
show all the dependencies that would be needed by a set of packages

.TP 
\ \ \ \(bu
search for ports by name, by description, or by the files they provide

.TP 
\ \ \ \(bu
show the upstream url or the maintainer contact information

.PP 

\fBprt\-auf\fP basically serves as an intermediary between your high-level
objectives and the specific calls to pkgmk, pkgadd, and pkgrm that would
achieve them. prt\-auf will search for the necessary information itself in
all the port collections specified in its config file. This allows you to
just request a package for installation, without caring where it actually is
located on your file system. prt\-auf was inspired by \fBprt\-get\fP(8) and
offers an essentially identical user experience.

.PP 

prt\-auf lets you search for ports by name, find information about ports
(without installing them of course), or print the dependencies of a port (as
a space- or newline-separated list, or with indentation to represent the
tree structure). Note that prt\-auf trusts the port maintainer to provide an
accurate list of dependencies; if this list is incomplete for any of the
ports in your collections, the build might fail.

.PP 

prt\-auf has a test mode so you can see what effect an install/update
operation would have. Use the \-\-test switch for this (more details in
the \fBOPTIONS\fP section below).

.SH "RETURN VALUE"
Calling prt\-auf within a shell script sometimes requires you to check its
exit status. Like most Unix tools, prt\-auf returns 0 on success and a
non-zero value otherwise. A typical usage is:
.B if prt\-auf isinst $SOME_PORT; then $TAKE_THIS_ACTION; fi

.SH "SUBCOMMANDS"
prt\-auf uses so\-called subcommands, which always have to be the first 
non-option argument passed. This is very similar to
.B git(1).
[subcommand] can be one of the following:

.TP 
.B install [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
install/update all packages and their dependencies. Any currently-installed
dependency is left at its current version unless explicitly given on the command
line, in which case prt-auf will bring it up to date. If there have been major
version changes in shared libraries since your last update, it might be advisable to
run 'prt-auf update' instead.

.TP 
.B update [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
bring all the listed packages and their dependencies up to date. Among 'install', 'update',
and 'grpinst', this action is the most permissive, exempting from updates only the locked
ports in the dependency chain. You might use 'install' instead if you want a speedier
compilation time, but if any dependencies have a rapid release cycle and you haven't updated in a
while, there is no guarantee that your old installed version will work when building your desired
package.

.TP 
.B grpinst [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
install/update all packages in the listed order, but stop if pkgmk or pkgadd was
unsuccessful. 'prt-auf grpinst' can be used to override the automatic dependency resolution.
Among 'install', 'update', and 'grpinst', this action is the most literal, building only the
requested packages and no others. Yet 'grpinst' is still smart enough to call \fBpkgadd\fP(8)
with the '-u' switch, if one of the packages passed as argument is already installed.

.TP 
.B remove [\-\-rargs=] <package1> [<package2> ...]
remove packages listed in this order. The only relevant option you might want to pass to
\fBpkgrm\fP(8) is --root (or -r), used when you're managing a CRUX installation on a temporarily
mounted filesystem. In order not to confuse the argument parser (which splits on whitespace),
you should format such a request as
.B prt\-auf remove \-\-rargs=\-\-root=/path/to/mounted/crux <package1> [<package2> ...]
and \fBprt\-auf\fP will clean up the -r switch so that \fBpkgrm\fP(8) does what you want.

.TP 
.B sysup
Update all installed packages which are outdated.

.TP
.B lock
and
.B unlock
These commands allow you to keep the currently installed versions, even if there are
changes in the ports tree.

.TP 
.B lock <package1> [<package2>...]
Do not update these packages in a
.B sysup
operation

.TP 
.B unlock <package1> [<package2>...] 
Remove lock from these packages

.TP 
.B listlocked
List names of packages which are locked.

.TP 
.B diff [--all]
show differences between installed packages and ports in the ports
tree. Locked packages are only displayed if you use the --all switch.

.TP 
.B quickdiff
prints a simple list of packages which have a different version in the
ports tree than what is installed.

.TP 
.B search [\-\-path] [\-\-regex] <expr>
Search the ports tree for
.B expr
in their name

.TP 
.B dsearch [\-\-path] [\-\-regex] <expr>
Search the ports tree (both name and description) for the pattern
\fBexpr\fP. The search in the description is not case sensitive. Note that
this requires prt\-auf to read every Pkgfile, which makes it rather slow; if
you like this, consider using the cache functionality, so you only have to
spend this time once after updating the ports tree has been updated.

.TP 
.B fsearch [\-\-path] [\-\-regex] <pattern>
Search the ports tree for file names that match \fBpattern\fP.
Pattern should be a Perl-compatible regular expression (e.g. prt-auf fsearch
--regex 'liblz(o2|ma).*') unless it contains no metacharacters (such as: +,
*, ., / ), in which case you can omit the \-\-regex switch. The full path is
\fInot\fP stripped from the footprint before matching, so if you're looking for
a filename that begins with 'liblz', you should use '\\/liblz' rather than '^liblz'.

.TP 
.B info <port>
Print available info for a port 

.TP 
.B path <port>
Print the path of a port

.TP 
.B readme <port>
Print the port's README file if it exists

.TP 
.B depends <package1> [<package2> ...]
print a recursive list of dependencies needed to install the packages passed
as argument. It shows a list of the dependencies that were found in the
ports tree, plus a list of the dependencies that could not be found.

.TP 
.B quickdep <package1> [<package2> ...]
print a simple list of recursive dependencies for all the packages passed
as argument. The output is formatted to be useful in command substitution,
e.g. instead of running
.B prt\-auf depinst xorg-server
you might obfuscate your intentions with a gratuitous loop:
.B for i in $(prt\-auf quickdep xorg-server); do prt\-auf isinst $i || prt\-auf install $i; done

Note: output is restricted to those dependencies that can be found in the ports tree. It might be
useful to run
.B prt\-auf depends <package1> | grep \(dq\-\- missing packages\(dq
as a first step, in order to ensure that your ports tree has everything needed for successful
builds.

.TP 
.B deptree <package>
print a tree of the dependencies of the package
.B package. 

.SH ""

Note that soft (optional) dependencies are NOT considered when running
prt\-auf depends, prt\-auf quickdep, or prt\-auf deptree. The port maintainer
often provides a README if significant loss of functionality might result from
not having an optional dependency present when building, so be sure to interpret the output of
.B prt\-auf <depends|quickdep|deptree>
in light of the information provided in such a README.

.TP 
.B dependent <package>
print a list of ports which have
.B package
in their "Depends on:" line. As with
.B depends, quickdep, deptree,
the Pkgfile line for soft (optional) dependencies is NOT parsed during this operation,
so the output might omit some of the ports that were linked against
.B package
during compilation.
 
By default, output is restricted to ports that are installed. To see all hard dependencies,
add the --all switch; use --recursive to get a recursive list (without duplication),
and --tree to get a nicely indented one (note that --tree implies
--recursive).

.TP 
.B dup
List ports which can be found in multiple directories configured in
.B /etc/prt-get.conf

.TP 
.B list [\-v|\-vv]
List ports available in the ports tree. It's basically the same as
.B ports \-l
but looks in all directories specified in the config file.

.TP 
.B listinst [\-v|\-vv]
List installed ports. It's basically the same as
.B pkginfo \-i,
but omits version when called without verbose (\-v, \-vv) switch.
\-v adds version information, \-vv adds version and description.

.TP 
.B listorphans
List installed ports which do not appear in the "Depends on:" line of
any other port currently installed. Output is sorted first by repository and then alphabetically,
so you should pipe it to \fBsort\fP(1) if you plan to use it in a \fBcomm\fP(1) command as in the
.B EXAMPLES
section below. Note that some core ports might be runtime
dependencies despite their absence in the "Depends on:" line; see \fBPkgfile(5)\fP
for an explanation of this practice. Also remember that this operation does NOT account for soft
(optional) dependencies. Removing a non-core package returned by this command might require a
rebuild of other packages; use revdep(1) to locate such breakage.

.TP 
.B isinst <package1> [<package2> ...]
Check whether each package given on the command line is installed. Output in the case of multiple
arguments is separated by newlines, suitable for processing by awk or grep. Similar to
.B pkginfo \-i|grep \-E '^(package1|package2|...)'
but does not print the version information. This command has a return value of 0 if
all packages given as argument are installed, otherwise a return value greater than 0.

.TP
.B current <package1> [<package2> ...]
Shows the currently-installed version of <package1>, or a message
that <package1> is not installed. Also takes more than one package as
argument.

.TP
.B ls [--path] <package>
Prints out a listing of the port's directory

.TP
.B cat <package> [<file>]
Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.

.TP
.B edit <package> [<file>]
Edit the file using the editor specified in the $EDITOR environment variable.
If <file> is not specified, 'Pkgfile' is used.

.TP 
.B help
Shows a help screen

.TP 
.B version 
Shows the current version of prt\-auf

.TP 
.B cache
create a cache file from the ports tree, which will be used whenever \fBprt\-auf\fP
is invoked with the --cache option. Remember to run \fBprt\-auf cache\fP each time
you update the ports tree, or automate this step by appending a line to the
\fBports\fP(8) script. If you invoke \fBprt\-auf\fP from a symbolic link that ends
in 'cache', \fBprt\-auf\fP will act as if it saw the --cache option on the command
line, so the symbolic link \fBprt\-cache\fP -> \fBprt\-auf\fP will save you the
hassle of typing '--cache' each time. Cache files generated by \fBprt\-auf\fP are
fully compatible with those generated by \fBprt\-get\fP(8).

.SH "OPTIONS"

The following options are primarily useful for install/update transactions.

.TP
.B -fr
Force rebuild, Implies 'pkgmk -f'; same as --margs=-f

.TP
.B -us
Update signature, implies 'pkgmk -us'; same as --margs=-us

.TP
.B -is
Ignore signature, implies 'pkgmk -is'; same as --margs=-is

.TP
.B -uf
Update footprint, implies 'pkgmk -uf'; same as --margs=-uf

.TP
.B -if
Ignore footprint, implies 'pkgmk -if'; same as --margs=-if

.TP
.B -ns
No stripping, implies 'pkgmk -ns'; same as --margs=-ns

.TP
.B -kw
Keep working directory, implies 'pkgmk -kw'; same as --margs=-kw

.TP 
.B \-\-margs="...", e.g. \-\-margs="\-im"
additional arguments to be passed to pkgmk;
note that \-d is already passed to pkgmk anyway

.TP 
.B \-\-aargs="...", e.g. \-\-aargs="\-f"
additional arguments to be passed to pkgadd

.TP 
.B \-\-cache
Use cache file for this command.

.SH ""

The following options affect the output of non-install (information-seeking) transactions.

.TP 
.B \-v, \-vv
(verbosity level) Show version of a port (\-v), or show both version
and description (\-vv). Passing more than one of these options is equivalent to \-vv.

.TP
.B \-\-path
Show path info for the ports found by a search or a dependency calculation

.TP
.B \-\-regex
Interpret filter and search pattern as regular expression


.SH "CONFIGURATION"

Most of the directives available in prt\-get.conf(5) are also recognized and
respected by \fBprt\-auf\fP. Notably, you can specify the active port
collections by ensuring that they appear on lines beginning with 'prtdir '.
You can also toggle the running of pre-/post-install scripts by editing the
line that contains 'runscripts'. You can specify alternatives to the
default pkgutils programs ( /usr/bin/pkgmk, /usr/bin/pkgadd, and
/usr/bin/pkgrm )
by editing the lines for 'makecommand', 'addcommand', and 'removecommand', respectively.

.SH "TECHNICAL DETAILS"

\fBprt\-auf\fP aims to recreate the familiar experience of \fBprt\-get\fP(8), in a
tidy Perl program that novice CRUX hackers would find less intimidating. By keeping its
inner workings entirely within one file, \fBprt\-auf\fP makes it easier for CRUX newcomers
to understand the architecture of the \fBports\fP(8) system and the \fBpkgutils\fP.

One intended consequence of the less-intimidating code base is that bug reports and
feature requests can receive the attention of more CRUX users, rather than just the
handful of developers who have C++ experience. In order to facilitate the insertion
of new code to satisfy any feature requests, this section provides an outline of the
\fBprt\-auf\fP design.

The program begins by declaring all the variables that are shared among subroutines.
Some of these variables are initialized right away, but other variables are only
initialized once the program knows the requested action.

After all the arguments are parsed (and screened for validity), the hash maps \fI%opkg\fP,
\fI%odepends\fP, and \fI%osearch\fP will retain in memory the user's desired settings. Then the
relevant data structures are populated from the files on disk (the cache, if
\-\-cache was passed on the command line, the database of installed packages in /var/lib/pkg,
the list of locked ports, the list of aliases, or each \fBPkgfile\fP(5) found in the ports tree).

Control is now passed to the subroutine that satisfies the given request. Many of these
subroutines return a simple array of strings, most notably the subroutions \fIlist_ports()\fP,
\fIdeporder()\fP, and \fIport_diff()\fP. But the \fIup_inst()\fP subroutine returns references
to five different arrays, so that post-processing can provide informative output regarding which
ports were successfully installed, and which ports failed.

The final section of the main program (post-processing) considers the distinctive output of each
subroutine and customizes the handling of the \fI@results\fP array accordingly. This section is
also where the verbose switch (-v|-vv) is taken into account, appending to each element of
\fI@results\fP the version or description of the ports found in the search.

.SH "CONTRASTS BETWEEN PRT-AUF and PRT-GET"

Although taking inspiration from \fBprt\-get\fP for its interface and configuration, \fBprt\-auf\fP
diverges from its predecessor in a few notable ways. Some of these differences are mere omissions,
which can easily be incorporated at a later date. Long-time users of \fBprt\-get\fP will quickly
notice the following differences:
.PP
.TP 
\ \ \ \(bu mixed install/update mode. Packages given on the command line can be present or not, and
\fBprt\-auf\fP will figure out the right way to call \fBpkgadd\fP(8) for each one. The key
distinction is that 'install' mode will not try to update an out-of-date package found in the
dependency chain unless that package also appears on the command line.

.TP 
\ \ \ \(bu merged update and depinst. Both of these now resolve dependencies by default, as does
 'install'. The original behaviour of \fBprt\-get install\fP can be approximated by the
 'grpinst' action of \fBprt\-auf\fP, except that a 'grpinst' action will not proceed to the next
package if a build fails.

.TP 
\ \ \ \(bu no internal handling of build/install logs. In the event that stdout is \fInot\fP
redirected to a file, consider using the 'grpinst' action so that error messages remain in the
scrollback buffer. If \fBprt\-auf\fP is used non-interactively (say, in a cron job), then another
non-interactive process can take care of renaming the file where the stdout of \fBprt\-auf\fP was
dumped. This design decision is closer to the spirit of "do one thing and do it well", although
\fBprt\-auf\fP ignores this advice elsewhere by implementing such luxuries as
.B prt\-auf ls, prt\-auf edit, prt\-auf readme
when command substitutions like
.B ls $(prt\-auf path $desired_port)
or
.B vim $(prt\-auf path $desired_port)/Pkgfile
are perfectly cromulent ways to do the same thing.

.TP
\ \ \ \(bu no 'printf' action (yet). This subcommand is needed by some of the \fBprt\-utils\fP
scripts, so it might be one of the first features to come back in the next version of
\fBprt\-auf\fP. The subroutine \fIdump_flat_db()\fP already loads most of the data structures
needed to generate formatted output; the missing component is a new code block in the argument
parser that will translate user requests into the variables used internally by \fBprt\-auf\fP.

.TP
\ \ \ \(bu no "filter" arguments recognized by 'diff', 'list', etc. There is no plan to add such a
feature in a later version of \fBprt\-auf\fP, because the newline-separated output of 'diff' and
 'list' is easily piped to awk or grep for any desired filtering.

.TP
\ \ \ \(bu no version comparator. One of the main reasons to run CRUX is to stay current with the
latest stable versions endorsed by the port maintainers. (They subscribe to the upstream mailing
lists so you don't have to.) If you want to keep a particular piece of software at a different
version than the one chosen by its original maintainer, you can maintain a shadow port in your own
overlay (and put that overlay higher in the config file).

.TP
\ \ \ \(bu no "--ignore" switch. This feature is easy enough to add at a later date, but a newcomer
to CRUX will likely be confused at having such fine-grained control over the automatic dependency
resolution. Getting into the habit of using "--ignore" for any port with a questionable
"Depends on" line will discourage the CRUX newcomer from providing valuable feedback to the port
maintainers. Reporting the erroneous "Depends on" line will make the port collection better for
everyone, while a one-time use of "--ignore" will keep those improvements from reaching a wider
audience.

.SH "EXAMPLES"
.TP 
.B prt\-auf install irssi
Download, build and install irssi, with one simple command

.TP 
.B prt\-auf install paper yasm
Install paper and yasm (and any needed dependencies).

.TP
.B prt\-auf update bmake cmake
Update bmake and cmake. Abort with an informative error message if either package is not yet
installed, allowing you to issue a revised command.

.TP 
.B prt\-auf update -fr openssh
Update your current version of openssh, forcing a rebuild even if no version
difference is detected. Useful if there was a major version change in one of
its dependencies, and \fBrevdep openssh\fP indicates a broken package. :\-)

.TP 
.B prt\-auf info glib-networking
Show info about glib-networking

.TP
.B MISSLIBS=$(revdep -vvv mpv | awk -F ':' '/(missing library)/ {print $3}'); [ -n \(dq${MISSLIBS[@]}\(dq ] && for i in ${MISSLIBS[@]}; do prt\-auf fsearch $i; done
(adapted from a script by ppetrov^) Check for the presence of the runtime libraries needed by mpv.
If any are absent, search the footprints to determine which ports provide the missing libraries.

.TP 
.B prt\-get search --regex '^(m|n|p)c.*'
Return a list of all ports whose names start with "mc", "nc", or "pc"

.TP
.B prt\-auf dsearch irc
Return a list of all ports having "irc" in their name or description

.TP
.B comm -13 <(ls /usr/ports/core) <(prt-auf listorphans)
(based on comments from Romster and jue) Filter out the core ports from the list of orphans, in
shells (like bash) that support process substitution

.TP
.B comm -13 <(cat ~/.keepers <(ls /usr/ports/core) | sort) <(prt\-auf listorphans) | xargs prt\-auf remove
(system-hosing extension of the above) A one-liner inspired by \fBpkg\-clean\fP
and \fBpkgfoster\fP, but without the safeguard of interactivity. \fBDo not try this on a
mission-critical system.\fP

.TP
.B prt\-auf isinst $(prt\-auf quickdep $(prt\-auf quickdiff)) | awk '/not installed/ {print $2}'
(adapted from a comment by Fun) After updating your ports tree, print out a list of dependencies
that were not needed the last time you built your currently-installed ports, but are needed now by
the newer versions of these ports. The output of this command is sorted by dependencies, therefore
suitable for piping to \fBxargs prt\-auf install\fP or \fBxargs prt\-auf grpinst\fP.

.TP 
.B prt\-auf grpinst $(prt\-auf quickdep graphviz)
Installed all packages needed for graphviz . Remember that grpinst stops
installing when one package installation fails.

.TP
.B prt\-auf listinst | xargs prt\-auf depends | xargs prt-auf grpinst \-\-aargs="\-r=/mnt"
Sort the list of installed packages by dependencies, and then install all
those packages onto a backup filesystem (mounted at /mnt). If you have a
customized pkgadd.conf that you want applied to this operation, either copy
it to /mnt/etc where pkgadd will be looking for it, or pass the additional
option \-\-aargs=\(dq\-c /etc/pkgadd.conf\(dq to the grpinst command.

.TP
.B  prt\-auf list --path --regex '^xorg.*' | grep -v "/usr/ports/xorg"
Show the ports whose names begin with xorg, but which appear outside the xorg port collection.
(At the time of writing, this command returned at least two font ports.)

.SH "AUTHORS"
John McQuah <jmcquah at disroot dot org>, based on the prt\-get manpage by
Johannes Winkelmann, and other sources cited inline.
.SH "SEE ALSO"
prt\-get.conf(5), Pkgfile(5), pkgmk(8), pkgadd(8), pkgrm(8), ports(8)