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

prt-auf.8: moved the discussion of 'dup' closer to related commands

Browse Source
This commit is contained in:
John McQuah 2022-06-15 17:39:59 -04:00
parent 7e03c42638
commit d8bd1bc39f
1 changed files with 103 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
man8/prt-auf.8
View File

@ -54,10 +54,10 @@ 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
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
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
ports in your collections, the build might fail.
@ -88,6 +88,12 @@ 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 depinst [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
essentially a synonym for \fBinstall\fP. This subcommand is provided for the
convenience of long-time \fBprt\-get\fP users, who might find it
counterintuitive to see automatic dependency resolution with \fBinstall\fP.
.TP
.B update [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
bring all the listed packages and their dependencies up to date. Among 'install', 'update',
@ -116,20 +122,13 @@ and \fBprt\-auf\fP will clean up the -r switch so that \fBpkgrm\fP(8) does what
.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.
Update all installed packages which are outdated and not locked.
.TP
.B lock <package1> [<package2>...]
Do not update these packages in a
Exempt these packages from any subsequent
.B sysup
operation
operation (i.e., keep them at their currently-installed version)
.TP
.B unlock <package1> [<package2>...]
@ -141,12 +140,12 @@ List names of packages which are locked.
.TP
.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.
.TP
.B quickdiff
prints a simple list of packages which have a different version in the
Print a simple list of packages which have a different version in the
ports tree than what is installed.
.TP
@ -188,6 +187,14 @@ Print the path of a port
.B readme <port>
Print the port's README file if it exists
.SH ""
The subcommands 'info', 'path', and 'readme' expect as their argument an exact match for one of the
ports in the active repositories. If you are not sure that a port by that name exists, you should
first use 'search', 'dsearch', or 'fsearch' to generate a list of possible arguments. The info or
readme will come from the highest-priority port in the active repositories (the same port that would
be built by an 'install' command).
.TP
.B depends <package1> [<package2> ...]
print a recursive list of dependencies needed to install the packages passed
@ -211,7 +218,7 @@ builds.
.TP
.B deptree <package>
print a tree of the dependencies of the package
print a tree of the dependencies of
.B package.
.SH ""
@ -239,6 +246,27 @@ add the --all switch; use --recursive to get a recursive list (without duplicati
and --tree to get a nicely indented one (note that --tree implies
--recursive).
.TP
.B ls [--path] <port>
Prints out a listing of the port's directory
.TP
.B cat <port> [<file>]
Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used.
.TP
.B edit <port> [<file>]
Edit the file using the editor specified in the $EDITOR environment variable.
If <file> is not specified, 'Pkgfile' is used.
.SH ""
Similar to 'info', 'path', and 'readme', a non-exhaustive search is performed to satisfy
an 'edit', 'cat', or 'ls' command. This behaviour ensures that your edits or directory listings
pertain to the port that would be built by a 'prt-auf install' command. Meanwhile, 'prt-auf dup'
will let you know if any port in the active repositories is hidden by another port of the same name,
but the 'dup' command offers convenient access to only some of the fields that 'info' or 'readme'
would print.
.TP
.B dup [format string]
List ports which can be found in multiple directories configured in
@ -333,10 +361,8 @@ are replaced like this:
up to date and "diff" if it's installed and a new version is in the
ports tree.
Use "\\n" and "\\t" to format your output (note that "\\n" is appended to your
format specifier automatically). To restrict the list to package names
matching a desired pattern, you can specify
.B filter
Use "\\n" and "\\t" to format your output. To restrict the list to package names
matching a desired pattern, you can specify \fB<filter>\fP.
Metacharacters in the filter are only respected if you pass the --regex option,
in which case your filter should be a Perl-compatible regular expression.
@ -369,34 +395,21 @@ all packages given as argument are installed, otherwise a return value greater t
.TP
.B current <package1> [<package2> ...]
Shows the currently-installed version of <package1>, or a message
Show 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] <port>
Prints out a listing of the port's directory
.TP
.B cat <port> [<file>]
Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.
.TP
.B edit <port> [<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
Show a help screen
.TP
.B version
Shows the current version of prt\-auf
Show 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
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
@ -410,45 +423,49 @@ fully compatible with those generated by \fBprt\-get\fP(8).
The following options are primarily useful for install/update transactions.
.TP
.B -fr
.B \-\-test
Do not actually run pkgmk/pkgadd/pkgrm, just print the commands that would have run
.TP
.B \-fr
Force rebuild, Implies 'pkgmk -f'; same as --margs=-f
.TP
.B -us
.B \-us
Update signature, implies 'pkgmk -us'; same as --margs=-us
.TP
.B -is
.B \-is
Ignore signature, implies 'pkgmk -is'; same as --margs=-is
.TP
.B -uf
.B \-uf
Update footprint, implies 'pkgmk -uf'; same as --margs=-uf
.TP
.B -if
.B \-if
Ignore footprint, implies 'pkgmk -if'; same as --margs=-if
.TP
.B -ns
.B \-ns
No stripping, implies 'pkgmk -ns'; same as --margs=-ns
.TP
.B -kw
.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
Pass these additional arguments 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
Pass these additional arguments to pkgadd
.TP
.B \-\-cache
Use cache file for this command.
Use cache file for this command
.SH ""
@ -472,12 +489,16 @@ Interpret filter and search pattern as regular expression
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 '.
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.
Lastly, you can control whether the pkgmk output is saved in a log file, using the directives 'writelog
<enabled|disabled>', 'logmode <append|overwrite>', and 'logfile <path>'. The <path> in a 'logfile'
directive can contain any of 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"
@ -497,8 +518,8 @@ 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
\fI%odepends\fP, \fI%osearch\fP, and \fI%olog\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).
@ -521,52 +542,49 @@ which can easily be incorporated at a later date. Long-time users of \fBprt\-get
observe the following differences:
.PP
.TP
\ \ \ \(bu mixed install/update mode. Packages given on the command line can be present or not, and
.B 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
.B merged install and depinst.
For the convenience of new users who might find it surprising to have an 'install' command fail due
to missing dependencies, the 'install' subcommand now does exactly what 'depinst' used to do in
\fBprt\-get\fP. 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. This omission will be sorely missed by
administrators of remote CRUX installations, who are unlikely to want to write their own
non-interactive script for cleaning up the redirected stdout of \fBprt\-auf\fP and organizing the
build logs that way. Once \fBprt\-auf\fP sees wider adoption beyond the handful of early testers who
find value in its approach to package management, the internal handling of build logs will be added.
.TP
.B 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 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).
.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
regular expressions. When paired with the case-insensitive pattern matching of purely-alphanumeric
queries, the Perl 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
\ \ \ \(bu 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 regular expressions.
When paired with the case-insensitive pattern matching of purely-alphanumeric queries, the Perl 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.
.B 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. The two main reasons
to use "--ignore" (an erroneous "Depends on" line, or a satisfaction of the dependency by manual
installations that pkgutils is not aware of), are both more properly addressed by a long-term
solution rather than a one-time fix. If the "Depends on" line is truly in error, the CRUX user
should contact the port maintainer and get it fixed for everybody, rather than passing the
"--ignore" option and letting the error go uncorrected. If the dependency was satisfied by a manual
installation outside of pkgutils, a better response is to make a dummy port and create an entry in
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
.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. The two main reasons to use "--ignore" (an erroneous "Depends on" line, or a
satisfaction of the dependency by manual installations that pkgutils is not aware of), are both more
properly addressed by a long-term solution rather than a one-time fix. If the "Depends on" line is
truly in error, the CRUX user should contact the port maintainer and get it fixed for everybody,
rather than passing the "--ignore" option and letting the error go uncorrected. If the dependency
was satisfied by a manual installation outside of pkgutils, a better response is to make a dummy
port and create an entry in 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
.TP
\ \ \ \ \ rust-bin: rust
which tells \fBprt\-auf\fP that an installed copy of rust-bin is sufficient to proceed with the