jmq/Documentation
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

prt-auf: edit man-page to reflect recent changes in the argument parser

Browse Source
This commit is contained in:
John McQuah 2023-03-14 15:10:16 -04:00
parent 070a91ce7b
commit 038a0ef742
2 changed files with 230 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

427
man8/prt-auf.8
View File

@ -1,5 +1,5 @@
.\" man page for prt-auf .\" man page for prt-auf
.\" last edited June 2022 by John McQuah, jmcquah at disroot dot org .\" last edited March 2023 by John McQuah, jmcquah at disroot dot org
.\" .\"
.\" based on original work by Johannes Winkelmann, jw at tks6 dot net .\" based on original work by Johannes Winkelmann, jw at tks6 dot net
.\" .\"
@ -7,14 +7,14 @@
.TH "prt-auf" "8" "" "" "" .TH "prt-auf" "8" "" "" ""
.SH "NAME" .SH "NAME"
.LP .LP
prt\-auf \- add/upgrade frontend to the CRUX pkgutils, inspired by \fBprt\-get\fP(8). 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) (see http://www.crux.nu for an overview of CRUX ports and pkgutils)
.SH "SYNOPSIS" .SH "SYNOPSIS"
.B prt\-auf subcommand [options] <arguments> .B prt\-auf subcommand [options] <arguments>
.br .br
.SH "DESCRIPTION" .SH "DESCRIPTION"
prt\-auf is a frontend to the CRUX pkgutils, orchestrating their operation 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 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 scans both the local ports tree and the installed package database, to
resolve dependency relationships and to determine which installed packages resolve dependency relationships and to determine which installed packages
@ -54,75 +54,75 @@ offers an essentially identical user experience.
.PP .PP
prt\-auf automates the process of tracking down dependencies of the ports you prt-auf automates the process of tracking down dependencies of the ports you
want to install. The result of these recursive calculations can be printed as want to install. The result of these recursive calculations can be printed as
a space- or newline-separated list, or with indentation to represent the 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 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 accurate list of dependencies; if this list is incomplete for any of the
ports in your collections, the build might fail. ports in your collections, the build might fail.
.PP .PP
prt\-auf has a test mode so you can see what effect an install/update 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 operation would have. Use the --test switch for this (more details in
the \fBOPTIONS\fP section below). the \fBOPTIONS\fP section below).
.SH "RETURN VALUE" .SH "RETURN VALUE"
Calling prt\-auf within a shell script sometimes requires you to check its 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 exit status. Like most Unix tools, prt-auf returns 0 on success and a
non-zero value otherwise. A typical usage is: non-zero value otherwise. A typical usage is:
.B if prt\-auf isinst $SOME_PORT; then $TAKE_THIS_ACTION; fi .B if prt\-auf isinst $SOME_PORT; then $TAKE_THIS_ACTION; fi
.SH "SUBCOMMANDS" .SH "SUBCOMMANDS"
prt\-auf uses so\-called subcommands, which always have to be the first prt-auf uses so-called subcommands, which always have to be the first
non-option argument passed. This is very similar to non-option argument passed. This is very similar to
.B git(1). .B git(1).
\fBsubcommand\fP can be one of the following: \fBsubcommand\fP can be one of the following:
.TP .TP
.B install [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...] .B install [\-\-group] [\-fr] [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
install/update all packages and their dependencies. Any currently-installed install/update all packages in the order given, without resolving
dependency is left at its current version unless explicitly given on the command dependencies. Pass the --group flag to abort the operation if any
line, in which case prt-auf will bring it up to date. If there have been major package fails. Pass the -fr flag to force a rebuild even if a package appears
version changes in shared libraries since your last update, it might be advisable to up to date.
run 'prt-auf update' instead.
.TP .TP
.B depinst [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...] .B depinst [\-\-group] [\-fr] [\-\-softdeps] [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
essentially a synonym for \fBinstall\fP. This subcommand is provided for the calculate the minimal set of packages needed to satisfy the dependencies of
convenience of long-time \fBprt\-get\fP users, who might find it packages passed on the command line, and then run \fBinstall\fP on the
counterintuitive to see automatic dependency resolution with \fBinstall\fP. resulting list. Pass the --softdeps flag if you want optional dependencies to
be considered when sorting the list of targets. The -fr flag (force rebuild)
only applies to packages explicitly given on the command line; the --group
flag applies to the entire set of targets calculated by the dependency
resolver.
.TP .TP
.B update [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...] .B update [\-\-group] [\-fr] [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
bring all the listed packages and their dependencies up to date. Among 'install', 'update', essentially a synonym for \fBinstall\fP. Support for this subcommand is
and 'grpinst', this action is the most permissive, exempting from updates only the locked retained as a convenience for long-time prt-get users, who might not be
ports in the dependency chain. You might use 'install' instead if you want a speedier accustomed to the mixed install/update mode of prt-auf.
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 dependency will provide all the functionality
needed by the 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 .TP
.B remove [\-\-rargs=] <package1> [<package2> ...] .B remove [\-\-rargs=] <package1> [<package2> ...]
remove packages listed in this order. The only relevant option you might want to pass to remove packages listed in this order. The only relevant option you might want
\fBpkgrm\fP(8) is --root (or -r), used when you're managing a CRUX installation on a temporarily to pass to \fBpkgrm\fP(8) is --root (or -r), used when you're managing a CRUX
mounted filesystem. In order not to confuse the argument parser (which splits on whitespace), installation on a temporarily mounted filesystem. In order not to confuse the
you should format such a request as 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> ...] .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. and \fBprt\-auf\fP will clean up the -r switch so that \fBpkgrm\fP(8) does what
you want.
.TP .TP
.B sysup .B sysup [\-\-group] [\-\-softdeps] [\-\-test]
Update all installed packages which are outdated and not locked. Update all installed packages which are outdated and not locked. Essentially
the same as
.B prt\-auf quickdiff | tr ' ' '\n' | grep -v -F -f /etc/prt-get.locker | xargs prt\-auf depinst
but more convenient to type. Pass the --group flag in order to stop the
operation at the first port that fails to update. Pass the --softdeps flag in
order to consider optional dependencies when constructing and sorting the list
of targets.
.TP .TP
.B lock <package1> [<package2>...] .B lock <package1> [<package2>...]
@ -139,7 +139,7 @@ Remove lock from these packages
List names of packages which are locked. List names of packages which are locked.
.TP .TP
.B diff [--all] .B diff [\-\-all]
Show differences between installed packages and ports in the ports Show differences between installed packages and ports in the ports
tree. Locked packages are only displayed if you use the --all switch. tree. Locked packages are only displayed if you use the --all switch.
@ -168,12 +168,14 @@ Search the ports tree for file names that match \fBpattern\fP.
.SH "" .SH ""
When using the --regex switch with 'search', 'dsearch', or 'fsearch', \fIpattern\fP should be a When using the --regex switch with 'search', 'dsearch', or 'fsearch',
Perl-compatible regular expression (e.g. prt-auf fsearch --regex 'liblz(o2|ma).*'). You can omit \fIpattern\fP should be a Perl-compatible regular expression (e.g. prt-auf
the --regex switch if your search pattern contains no metacharacters (such as: +, *, ., / ). Shell fsearch --regex 'liblz(o2|ma).*'). You can omit the --regex switch if your
globbing (with the * and ? wildcards) is \fINOT\fP supported. The 'fsearch' action looks for matches search pattern contains no metacharacters (such as: +, *, ., / ). Shell
against the full path, not just the filename, so if you're looking for a filename that begins globbing (with the * and ? wildcards) is \fINOT\fP supported. The 'fsearch'
with 'liblz', you should use '\\/liblz' rather than '^liblz'. action looks for matches against the full path, not just the filename, so if
you're looking for a filename that begins with 'liblz', you should use
'\\/liblz' rather than '^liblz'.
.TP .TP
.B info <port> .B info <port>
@ -189,62 +191,62 @@ Print the port's README file if it exists
.SH "" .SH ""
The subcommands 'info', 'path', and 'readme' expect as their argument an exact match for one of the The subcommands 'info', 'path', and 'readme' expect as their argument an exact
ports in the active repositories. If you are not sure that a port by that name exists, you should match for one of the ports in the active repositories. If you are not sure that
first use 'search', 'dsearch', or 'fsearch' to generate a list of possible arguments. The info or a port by that name exists, you should first use 'search', 'dsearch', or 'fsearch'
readme will come from the highest-priority port in the active repositories (the same port that would to generate a list of possible arguments. The info or readme will come from the
be built by an 'install' command). highest-priority port in the active repositories (the same port that would be
built by an 'install' command).
.TP .TP
.B depends <package1> [<package2> ...] .B depends [\-\-softdeps] <package1> [<package2> ...]
print a recursive list of dependencies needed to install the packages passed print a sorted list of dependencies needed to install the packages passed
as argument. It shows a list of the dependencies that were found in the as argument. Packages that need to be installed first are listed first. It
ports tree, plus a list of the dependencies that could not be found. shows a list of the dependencies that were found in the ports tree, followed by
a list of the dependencies that could not be found. Pass the --softdeps flag if
you want optional dependencies to be considered when constructing and sorting
the output.
.TP .TP
.B quickdep <package1> [<package2> ...] .B quickdep [\-\-softdeps] <package1> [<package2> ...]
print a simple list of recursive dependencies for all the packages passed mostly the same output as depends, but stripped of the installation status
as argument. The output is formatted to be useful in command substitution, indicator, and separated by spaces rather than newlines. Also, ports that
e.g. instead of running cannot be found in the ports tree are omitted from the results. This formatting
is useful in command substitution, e.g. instead of running
.B prt\-auf depinst xorg-server .B prt\-auf depinst xorg-server
you might obfuscate your intentions with a gratuitous loop: you might micromanage the process with a gratuitous loop:
.B for i in $(prt\-auf quickdep xorg-server); do prt\-auf isinst $i || prt\-auf install $i; done .B for i in $(prt\-auf quickdep xorg-server); do if prt\-auf isinst $i; then prt\-auf install \-fr $i; else prt\-auf install $i; fi; done
Note: output is restricted to those dependencies that can be found in the ports tree. It might be Note: In case there are dependencies not available in your active port
useful to run collections, it might be useful to run
.B prt\-auf depends <package1> | grep \(dq\-\- missing packages\(dq .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 as a first step, in order to ensure that your port collections have everything
builds. needed for successful builds.
.TP .TP
.B deptree <package> .B deptree [\-\-softdeps] <package>
print a tree of the dependencies of print a tree of the dependencies of
.B package. .B <package>.
.SH "" Pass the --softdeps flag if you want optional dependencies to appear in the
resulting tree. Only the optional dependencies that are currently installed will
Note that soft (optional) dependencies are NOT considered when running be shown, allowing you to see at a glance what might have been linked to
prt\-auf depends, prt\-auf quickdep, or prt\-auf deptree. The port maintainer \fB<package>\fP. Because \fBprt\-auf\fP has no mechanism for inspecting the
often provides a README if significant loss of functionality might result from history of the package database (specifically at the moment \fB<package>\fP was
not having an optional dependency present when building, so be sure to interpret the output of built), there is no reliable way to know whether the automagic linking actually
.B prt\-auf <depends|quickdep|deptree> took place. This subcommand should therefore be paired with
in light of the information provided in such a README. .B pkginfo -f <package>
and the build log, if present, in order to ascertain the actual linking that
occurred.
.TP .TP
.B dependent <package> .B dependent [\-\-softdeps] [\-\-all] [\-\-recursive] [\-\-tree] <package>
print a list of ports which have print a list of ports which have
.B package .B <package>
in their "Depends on:" line. As with in their "Depends on:" line. To also search the "Optional:" lines, pass the
.B depends, quickdep, deptree, --softdeps flag. By default, output is restricted to ports that are installed.
the Pkgfile line for soft (optional) dependencies is NOT parsed during this operation, To see all hard dependencies, add the --all switch; use --recursive to get a
so the output might omit some of the ports that were linked against recursive list (without duplication), and --tree to get a nicely indented one.
.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 .TP
.B ls [--path] <port> .B ls [--path] <port>
@ -260,12 +262,13 @@ Edit the file using the editor specified in the $EDITOR environment variable.
If <file> is not specified, 'Pkgfile' is used. If <file> is not specified, 'Pkgfile' is used.
.SH "" .SH ""
Similar to 'info', 'path', and 'readme', a non-exhaustive search is performed to satisfy Similar to 'info', 'path', and 'readme', a non-exhaustive search is performed
an 'edit', 'cat', or 'ls' command. This behaviour ensures that your edits or directory listings to satisfy an 'edit', 'cat', or 'ls' command. This behaviour ensures that your
pertain to the port that would be built by a 'prt-auf install' command. Meanwhile, 'prt-auf dup' edits or directory listings pertain to the port that would be built by
will let you know if any port in the active repositories is hidden by another port of the same name, a 'prt-auf install' command. Meanwhile, 'prt-auf dup' will let you know if any
but the 'dup' command offers convenient access to only some of the fields that 'info' or 'readme' port in the active repositories is hidden by another port of the same name, but
would print. the 'dup' command offers convenient access to only some of the fields
that 'info' or 'readme' would print.
.TP .TP
.B dup [format string] .B dup [format string]
@ -333,7 +336,7 @@ are replaced like this:
.TP .TP
\ \ \ \(bu \ \ \ \(bu
%P -> Packager %P -> optional dependencies
.TP .TP
\ \ \ \(bu \ \ \ \(bu
@ -374,24 +377,24 @@ but omits version when called without verbose (\-v, \-vv) switch.
\-v adds version information, \-vv adds version and description. \-v adds version information, \-vv adds version and description.
.TP .TP
.B listorphans .B listorphans [\-\-softdeps]
List installed ports which do not appear in the "Depends on:" line of 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, any other port currently installed. To also exclude ports that appear in the
so you should pipe it to \fBsort\fP(1) if you plan to use it in a \fBcomm\fP(1) command as in the "Optional:" lines of installed ports, pass the --softdeps flag. Note that some
.B EXAMPLES core ports might be runtime dependencies despite their absence in the "Depends
section below. Note that some core ports might be runtime on:" line; see \fBPkgfile(5)\fP for an explanation of this practice.
dependencies despite their absence in the "Depends on:" line; see \fBPkgfile(5)\fP Removing a non-core package returned by this command might require a
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. rebuild of other packages; use revdep(1) to locate such breakage.
.TP .TP
.B isinst <package1> [<package2> ...] .B isinst <package1> [<package2> ...]
Check whether each package given on the command line is installed. Output in the case of multiple Check whether each package given on the command line is installed. Output in
arguments is separated by newlines, suitable for processing by awk or grep. Similar to 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|...)' .B pkginfo \-i|grep \-E '^(package1|package2|...)'
but does not print the version information. This command has a return value of 0 if but does not print the version information. This command has a return value of
all packages given as argument are installed, otherwise a return value greater than 0. 0 if all packages given as argument are installed, otherwise a return value
greater than 0.
.TP .TP
.B current <package1> [<package2> ...] .B current <package1> [<package2> ...]
@ -416,7 +419,7 @@ you update the ports tree, or automate this step by appending a line to the
in 'cache', \fBprt\-auf\fP will act as if it saw the --cache option on the command 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 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 hassle of typing '--cache' each time. Cache files generated by \fBprt\-auf\fP are
fully compatible with those generated by \fBprt\-get\fP(8). compatible with those generated by the equivalent version of \fBprt\-get\fP(8).
.SH "OPTIONS" .SH "OPTIONS"
@ -424,7 +427,8 @@ The following options are primarily useful for install/update transactions.
.TP .TP
.B \-\-test .B \-\-test
Do not actually run pkgmk/pkgadd/pkgrm, just print the commands that would have run Do not actually run pkgmk/pkgadd/pkgrm, just print the list of ports that would
be affected by the operation.
.TP .TP
.B \-fr .B \-fr
@ -493,102 +497,114 @@ 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 You can also toggle the running of pre-/post-install scripts by editing the
line that contains 'runscripts'. You can specify alternatives to the line that contains 'runscripts'. You can specify alternatives to the
default pkgutils programs ( /usr/bin/pkgmk, /usr/bin/pkgadd, and default pkgutils programs ( /usr/bin/pkgmk, /usr/bin/pkgadd, and
/usr/bin/pkgrm ) /usr/bin/pkgrm ) by editing the lines for 'makecommand', 'addcommand',
by editing the lines for 'makecommand', 'addcommand', and 'removecommand', respectively. and 'removecommand', respectively. Lastly, you can control whether the pkgmk
Lastly, you can control whether the pkgmk output is saved in a log file, using the directives 'writelog output is saved in a log file, using the
<enabled|disabled>', 'logmode <append|overwrite>', and 'logfile <path>'. The <path> in a 'logfile' directives 'writelog <enabled|disabled>', 'logmode <append|overwrite>',
directive can contain any of the variables "%n", "%v", "%r", and "%p", which are automatically and 'logfile <path>'. The <path> in a 'logfile' directive can contain any of
replaced by the port's name, version, release, and full path in the ports tree, respectively. the variables "%n", "%v", "%r", and "%p", which are automatically replaced by
the port's name, version, release, and full path in the ports tree, respectively.
.SH "TECHNICAL DETAILS" .SH "TECHNICAL DETAILS"
\fBprt\-auf\fP aims to recreate the familiar experience of \fBprt\-get\fP(8), in a \fBprt\-auf\fP aims to recreate the familiar experience of \fBprt\-get\fP(8),
tidy Perl program that novice CRUX hackers would find less intimidating. By keeping its in a tidy Perl program that novice CRUX hackers would find less intimidating.
inner workings entirely within one file, \fBprt\-auf\fP makes it easier for CRUX newcomers By keeping its inner workings entirely within one file, \fBprt\-auf\fP makes it
to understand the architecture of the \fBports\fP(8) system and the \fBpkgutils\fP. 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 One intended consequence of the less-intimidating code base is that bug reports
feature requests can receive the attention of more CRUX users, rather than just the and feature requests can receive the attention of more CRUX users, rather than
handful of developers who have C++ experience. In order to facilitate the insertion just the handful of developers who have C++ experience. In order to facilitate
of new code to satisfy any feature requests, this section provides an outline of the the insertion of new code to satisfy any feature requests, this section
\fBprt\-auf\fP design. provides an outline of the \fBprt\-auf\fP design.
The program begins by declaring all the variables that are shared among subroutines. The program begins by declaring all the variables that are shared among
Some of these variables are initialized right away, but other variables are only subroutines. Some of these variables are initialized right away, but other
initialized once the program knows the requested action. 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, After all the arguments are parsed (and screened for validity), the hash maps
\fI%odepends\fP, \fI%osearch\fP, and \fI%olog\fP will retain in memory the user's desired settings. \fI%opkg\fP, \fI%odepends\fP, \fI%osearch\fP, and \fI%olog\fP will
Then the relevant data structures are populated from the files on disk (the cache, if retain in memory the user's desired settings. Then the relevant data structures
\-\-cache was passed on the command line, the database of installed packages in /var/lib/pkg, are populated from the files on disk (the cache, if \-\-cache was passed on the
the list of locked ports, the list of aliases, or each \fBPkgfile\fP(5) found in the ports tree). 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 Control is now passed to the subroutine that satisfies the given request. Many
subroutines return a simple array of strings, most notably the subroutions \fIlist_ports()\fP, of these subroutines return a simple array of strings, most notably the
\fIdeporder()\fP, and \fIport_diff()\fP. But the \fIup_inst()\fP subroutine returns references subroutions \fIlist_ports()\fP, \fIdeporder()\fP, and \fIport_diff()\fP. But
to five different arrays, so that post-processing can provide informative output regarding which the \fIup_inst()\fP subroutine returns references to five different arrays, so
ports were successfully installed, and which ports failed. 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 The final section of the main program (post-processing) considers the
subroutine and customizes the handling of the \fI@results\fP array accordingly. This section is distinctive output of each subroutine and customizes the handling of the
also where the verbose switch (-v|-vv) is taken into account, appending to each element of \fI@results\fP array accordingly. This section is also where the verbose switch
\fI@results\fP the version or description of the ports found in the search. (-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" .SH "CONTRASTS BETWEEN PRT-AUF and PRT-GET"
Although taking inspiration from \fBprt\-get\fP for its interface and configuration, \fBprt\-auf\fP Although taking inspiration from \fBprt\-get\fP for its interface and
diverges from its predecessor in a few notable ways. Some of these differences are mere omissions, configuration, \fBprt\-auf\fP diverges from its predecessor in a few notable
which can easily be incorporated at a later date. Long-time users of \fBprt\-get\fP will quickly 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
observe the following differences: observe the following differences:
.PP .PP
.TP .TP
.B mixed install/update mode. .B mixed install/update mode.
Packages given on the command line can be present or not, and Packages given on the command line can be installed or not, and \fBprt\-auf\fP
\fBprt\-auf\fP will figure out the right way to call \fBpkgadd\fP(8) for each one. The key will figure out the right way to call \fBpkgadd\fP(8) for each one.
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 .TP
.B merged install and depinst. .B new dependencies are automatically handled by sysup.
For the convenience of new users who might find it surprising to have an 'install' command fail due One benefit of the mixed install/update mode is that the sysup operation does
to missing dependencies, the 'install' subcommand now does exactly what 'depinst' used to do in not restrict itself to only those ports currently installed. If the dependency
\fBprt\-get\fP. The original behaviour of \fBprt\-get install\fP can be approximated by resolver finds ports that the maintainer has added as dependencies since the
the 'grpinst' action of \fBprt\-auf\fP, except that a 'grpinst' action will not proceed to the next last update, then sysup will insert them into the list of installation targets
package if a build fails. in the appropriate positions.
.TP .TP
.B no version comparator. .B no version comparator.
One of the main reasons to run CRUX is to stay current with the latest stable versions endorsed by One of the main reasons to run CRUX is to stay current with the latest stable
the port maintainers. (They subscribe to the upstream mailing lists so you don't have to.) If you versions endorsed by the port maintainers. (They subscribe to the upstream
want to keep a particular piece of software at a different version than the one chosen by its mailing lists so you don't have to.) If you want to keep a particular piece of
original maintainer, you can maintain a shadow port in your own overlay (and put that overlay higher software at a different version than the one chosen by its original maintainer,
in the config file). you can maintain a shadow port in your own overlay (and put that overlay
higher in the config file).
.TP .TP
.B no wildcards or shell globbing in the search commands. .B no wildcards or shell globbing in the search commands.
Being written in Perl, \fBprt\-auf\fP automatically inherits a rich set of routines for dealing with Being written in Perl, \fBprt\-auf\fP automatically inherits a rich set of
regular expressions. When paired with the case-insensitive pattern matching of purely-alphanumeric routines for dealing with regular expressions. When paired with the
queries, the Perl regexp engine offers CRUX users enough flexibility to find any port they're case-insensitive pattern matching of purely-alphanumeric queries, the Perl
looking for, without needing to clutter the code base by reimplementing shell wildcards. regexp engine offers CRUX users enough flexibility to find any port they're
looking for, without needing to clutter the code base by reimplementing shell
wildcards.
.TP .TP
.B no "--ignore" switch. .B no "--ignore" switch.
This feature is easy enough to add at a later date, but a newcomer to CRUX will likely be confused This feature is easy enough to add at a later date, but a newcomer to CRUX will
at having such fine-grained control over the automatic dependency resolution. The two main reasons likely be confused at having such fine-grained control over the automatic
to use "--ignore" (an erroneous "Depends on" line, or a satisfaction of the dependency by manual dependency resolution. The two main reasons to use "--ignore" (an erroneous
installations that pkgutils is not aware of), are both more properly addressed by a long-term "Depends on" line, or a satisfaction of the dependency by manual installations
solution rather than a one-time fix. If the "Depends on" line is truly in error, the CRUX user that pkgutils is not aware of), are both more properly addressed by a long-term
should contact the port maintainer and get it fixed for everybody, rather than passing the solution rather than a one-time fix. If the "Depends on" line is truly in
"--ignore" option and letting the error go uncorrected. If the dependency was satisfied by a manual error, the CRUX user should contact the port maintainer and get it fixed for
installation outside of pkgutils, a better response is to make a dummy port and create an entry in everybody, rather than passing the "--ignore" option and letting the error go
the aliases file. That way prt-auf will treat the dependency as satisfied for any subsequent uncorrected. If the dependency was satisfied by a manual installation outside
installations on the same machine, and passing the "--ignore" option will be unnecessary for all of pkgutils, a better response is to make a dummy port and create an entry in
future ports with the same dependency. The canonical example of a line in the aliases file is the aliases file. That way prt-auf will treat the dependency as satisfied for
any subsequent installations on the same machine, and passing the "--ignore"
option will be unnecessary for all future ports with the same dependency. The
canonical example of a line in the aliases file is
\ \ \ \ \ rust-bin: rust \ \ \ \ \ rust-bin: rust
which tells \fBprt\-auf\fP that an installed copy of rust-bin is sufficient to proceed with the which tells \fBprt\-auf\fP that an installed copy of rust-bin is sufficient to
compilation of a port that mentions rust in its "Depends on" line. proceed with the compilation of a port that mentions rust in its "Depends on"
line.
.SH "EXAMPLES" .SH "EXAMPLES"
.TP .TP
@ -596,16 +612,11 @@ compilation of a port that mentions rust in its "Depends on" line.
Download, build and install irssi, with one simple command Download, build and install irssi, with one simple command
.TP .TP
.B prt\-auf install paper yasm .B prt\-auf install \-\-group paper yasm
Install paper and yasm (and any needed dependencies). Install paper and yasm, but abort if paper fails to build or install.
.TP .TP
.B prt\-auf update bmake cmake .B prt\-auf install -fr openssh
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 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 difference is detected. Useful if there was a major version change in one of
its dependencies, and \fBrevdep openssh\fP indicates a broken package. :\-) its dependencies, and \fBrevdep openssh\fP indicates a broken package. :\-)
@ -616,8 +627,9 @@ Show info about glib-networking
.TP .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 .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. (adapted from a script by ppetrov^) Check for the presence of the runtime
If any are absent, search the footprints to determine which ports provide the missing libraries. libraries needed by mpv. If any are absent, search the footprints to determine
which ports provide the missing libraries.
.TP .TP
.B prt\-get search --regex '^(m|n|p)c.*' .B prt\-get search --regex '^(m|n|p)c.*'
@ -629,38 +641,41 @@ Return a list of all ports having "irc" in their name or description
.TP .TP
.B comm -13 <(ls /usr/ports/core) <(prt-auf listorphans) .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 (based on comments from Romster and jue) Filter out the core ports from the
shells (like bash) that support process substitution list of orphans, in shells (like bash) that support process substitution
.TP .TP
.B comm -13 <(cat ~/.keepers <(ls /usr/ports/core) | sort) <(prt\-auf listorphans) | xargs prt\-auf remove .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 (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 and \fBpkgfoster\fP, but without the safeguard of interactivity. \fBDo not try
mission-critical system.\fP this on a mission-critical system.\fP
.TP .TP
.B prt\-auf isinst $(prt\-auf quickdep $(prt\-auf quickdiff)) | awk '/not installed/ {print $2}' .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 (adapted from a comment by Fun) After updating your ports tree, print out a
that were not needed the last time you built your currently-installed ports, but are needed now by list of dependencies that were not needed the last time you built your
the newer versions of these ports. The output of this command is sorted by dependencies, therefore currently-installed ports, but are needed now by the newer versions of these
suitable for piping to \fBxargs prt\-auf install\fP or \fBxargs prt\-auf grpinst\fP. 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 .TP
.B prt\-auf grpinst $(prt\-auf quickdep graphviz) .B prt\-auf install \-\-group $(prt\-auf quickdep graphviz)
Installed all packages needed for graphviz . Remember that grpinst stops Installed all packages needed for graphviz , but abort the operation if
installing when one package installation fails. one package fails.
.TP .TP
.B prt\-auf listinst | xargs prt\-auf depends | xargs prt-auf grpinst \-\-aargs="\-r=/mnt" .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 Sort the list of installed packages by dependencies, and then install all those
those packages onto a backup filesystem (mounted at /mnt). If you have a packages onto a backup filesystem (mounted at /mnt). If you have a customized
customized pkgadd.conf that you want applied to this operation, either copy pkgadd.conf that you want applied to this operation, either copy it to /mnt/etc
it to /mnt/etc where pkgadd will be looking for it, or pass the additional where pkgadd will be looking for it, or pass the additional option
option \-\-aargs=\(dq\-c /etc/pkgadd.conf\(dq to the grpinst command. --aargs=\(dq-c /etc/pkgadd.conf\(dq to the grpinst command.
.TP .TP
.B prt\-auf list --path --regex '^xorg.*' | grep -v "/usr/ports/xorg" .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. 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.) (At the time of writing, this command returned at least two font ports.)
.SH "AUTHORS" .SH "AUTHORS"

16
scripts/prt-auf
View File

@ -109,7 +109,7 @@ if ($action =~ /^(listinst|listorphans)/) {
my $format = "%20s %15s %20s\n"; my $ind = shift(@results); my $format = "%20s %15s %20s\n"; my $ind = shift(@results);
if ($action eq "diff") { printf $format, "Port", "Installed", "Available in Repo"; } if ($action eq "diff") { printf $format, "Port", "Installed", "Available in Repo"; }
foreach my $diffline (@results) { foreach my $diffline (@results) {
if ($action =~ /^(current|isinst)$/) { print $diffline; next; } if ($action =~ /^(current|isinst)$/) { print "$diffline\n"; next; }
my ($diffN, $diffI, $diffR) = split(/ /, $diffline); my ($diffN, $diffI, $diffR) = split(/ /, $diffline);
next if (($osearch{filter}) and ($diffN !~ /$osearch{filter}/)); next if (($osearch{filter}) and ($diffN !~ /$osearch{filter}/));
next if ((grep {$_ eq $diffN} @LOCKED) and ($odepends{all}==0)); next if ((grep {$_ eq $diffN} @LOCKED) and ($odepends{all}==0));
@ -631,11 +631,10 @@ sub port_diff { # returns a list of all the ports with differences
push @outfile, "$p $V_INST{$p} $V_REPO{$p}" if (($V_REPO{$p}) and ($V_INST{$p} ne $V_REPO{$p})); push @outfile, "$p $V_INST{$p} $V_REPO{$p}" if (($V_REPO{$p}) and ($V_INST{$p} ne $V_REPO{$p}));
push @outfile, "$p $V_INST{$p} MISSING" if (! $V_REPO{$p}); push @outfile, "$p $V_INST{$p} MISSING" if (! $V_REPO{$p});
} }
} elsif ($dtype eq "utd") { } elsif ($dtype eq "utd") { my $q=shift(@argq);
while (my $q=shift(@argq) and $retval==0) { if (! $V_INST{$q}) { $retval--;
$retval-- if (! $V_INST{$q}); } elsif (($V_REPO{$q}) and ($V_INST{$q} ne $V_REPO{$q})) { $retval++;
$retval++ if (($V_INST{$q}) and ($V_REPO{$q}) and ($V_INST{$q} ne $V_REPO{$q})); } else {}
}
} elsif ($dtype =~ /^(current|isinst)$/) { } elsif ($dtype =~ /^(current|isinst)$/) {
foreach my $q (@argq) { foreach my $q (@argq) {
if (! $V_INST{$q}) { if (! $V_INST{$q}) {
@ -646,7 +645,8 @@ sub port_diff { # returns a list of all the ports with differences
} }
} }
} else {} } else {}
return $retval, @outfile; return $retval, @outfile unless ($dtype eq "utd");
return $retval if ($dtype eq "utd");
} }
sub deporder { sub deporder {
@ -780,7 +780,7 @@ sub up_inst { # returns scalar references to five arrays
$mkcmd{$t} = "echo \"skipped build ($t up to date)\"" if $mkcmd{$t} = "echo \"skipped build ($t up to date)\"" if
((-f $builtpkg{$t}) and ($opkg{$t} !~ /-f/)) ((-f $builtpkg{$t}) and ($opkg{$t} !~ /-f/))
and ((-M $builtpkg{$t}) < (-M "$pdirs{$t}/Pkgfile")); and ((-M $builtpkg{$t}) < (-M "$pdirs{$t}/Pkgfile"));
$mkcmd{$t} = "" if (($opkg{$t} !~ /-f/) and ($V_REPO{$t} eq $V_INST{$t})); $mkcmd{$t} = "" if (($opkg{$t} !~ /-f/) and (port_diff("utd",$t)==0));
} }
if ($opkg{test} eq "yes") { if ($opkg{test} eq "yes") {