diff --git a/man8/prt-auf.8 b/man8/prt-auf.8 index 6370543..33b3a55 100644 --- a/man8/prt-auf.8 +++ b/man8/prt-auf.8 @@ -7,7 +7,7 @@ .TH "prt-auf" "8" "" "" "" .SH "NAME" .LP -prt\-auf \- add/upgrade frontend to the CRUX pkgutils designed to imitate \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) .SH "SYNOPSIS" @@ -91,8 +91,10 @@ run 'prt-auf update' instead. .B update [\-\-margs=] [\-\-aargs=] [ ...] 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 should use 'install' instead if you only want to build -the missing dependencies. +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=] [ ...] @@ -104,8 +106,8 @@ with the '-u' switch, if one of the packages passed as argument is already insta .TP .B remove [\-\-rargs=] [ ...] -remove packages listed in this order. The only relevant option you can might want to pass to -\fBpkgrm\fP(8) is --root (or -r), used when you want to manage a CRUX installation on a temporarily +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 [ ...] @@ -119,7 +121,7 @@ Update all installed packages which are outdated. .B lock and .B unlock -commands to keep the currently installed versions, even if there are +These commands allow you to keep the currently installed versions, even if there are changes in the ports tree. .TP @@ -165,7 +167,9 @@ spend this time once after updating the ports tree has been updated. 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. +*, ., / ), 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 @@ -245,15 +249,14 @@ but looks in all directories specified in the config file. .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. Plus -it is notably faster in my tests. \-v adds version information, \-vv -adds version and description. +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 appears alphabetically separated by newlines, making it -suitable for process substitution as shown in the +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 @@ -261,7 +264,6 @@ for an explanation of this practice. Also remember that this operation does NOT (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 [ ...] Check whether each package given on the command line is installed. Output in the case of multiple @@ -416,25 +418,32 @@ subroutine and customizes the handling of the \fI@results\fP array accordingly. 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. -Here are some of the deliberate deviations from the behaviour of \fBprt\-get\fP(8), the first of -which was on the TODO list in the prt-get source tree. +.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. +\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 install and depinst. While they still retain some distinguishability in how they -treat a given set of targets, both of them now resolve dependencies by default. The old -behaviour of \fBprt\-get install\fP can be approximated by the 'grpinst' action of \fBprt\-auf\fP. +\ \ \ \(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 logging is not handled internally. 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 +\ \ \ \(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) @@ -442,6 +451,34 @@ 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 @@ -471,6 +508,10 @@ Show info about glib-networking (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 diff --git a/scripts/prt-auf b/scripts/prt-auf index 185d7bd..1d9ce7b 100755 --- a/scripts/prt-auf +++ b/scripts/prt-auf @@ -410,11 +410,11 @@ sub find_port_by_name { my $query = shift; my $exact=shift; my $fullpath=shift; my $exhaustive=shift; $query =~ s/\+/\\\+/g unless ($osearch{regex}==1); $query =~ s/\./\\\./g unless ($osearch{regex}==1); - $query =~ s/\^/\// if (($osearch{regex}==1) and ($exact==0)); + # $query =~ s/\^/\// if (($osearch{regex}==1) and ($exact==0)); my $pattern = ($exact==1) ? qr/\/$query$/s : qr/$query/is; - # my @names_only = map { $_ => (split /\//, $_)[-1] } @allports; - my @hits = grep { $_ =~ $pattern } @allports; - @hits = grep { s/^.*\/// } @hits if ($fullpath==0); + my %names_only = map { ($_ => (split /\//, $_)[-1]) } @allports; + my @hits = grep { $names_only{$_} =~ $pattern } @allports; + @hits = map { $names_only{$_} } @hits if $fullpath==0; return @hits if ($exhaustive==1); return $hits[0] if ($exhaustive==0);