pkg-get/README

INTRODUCTION
----------------------------------------------------------------------------
pkg-get is a package / repository management tool for CRUX Linux.
Syntax and features are very close to (often a carbon copy of)
the ones found in the port management tool 'prt-get'
by Johannes Winkelmann.
In fact pkg-get was developed as a prt-get/ports drop-in replacement
for systems in which it is preferable to handle binary packages instead
of compiling ports.


ARCHITECTURE
----------------------------------------------------------------------------
The client machines sync metadata files (available packages,
readme files, dependencies, etc) from a remote server (http or ftp)
OR a local path.
Once the metadata files are on the client machine, the usual
operations of installing, removing, getting info on packages
are available.


QUICK START
----------------------------------------------------------------------------
Server:
  A repository can be generated using 'pkg-repgen' in a
  dir containing packages. It will take a while since md5sums
  have to be calculated. Alternatively, you can pass one or 
  more arguments to 'pkg-repgen', indicating the individual
  packages for which metadata will be created.

Client:
  Adjust settings in /etc/pkg-get.conf, then use the 'pkg-get sync' 
  command to gather metadata from the server (if remote). You can now
  use the commands as described in the manual, e.g.:
    
    pkg-get info apache
    pkg-get depinst qt6-base
    pkg-get listinst

See the manual page for a detailed list of commands and options.


REQUIREMENTS
----------------------------------------------------------------------------
For the client, nothing outside the CRUX 'core' collection
For the server, prt-get


LIMITATIONS
----------------------------------------------------------------------------
The client and the server must be configured to use the same
pkgmk compression mode, otherwise the client will try to download
a tarball with the wrong suffix. This is only a problem if you sometimes
compile ports on the client machine and prefer a different compression mode
(better suited to its less-powerful hardware?). By allowing you to maintain
your client machine solely with binary packages, pkg-get makes the contents
of /etc/pkgmk.conf mostly irrelevant, so you can simply put a verbatim copy
of the server's pkgmk.conf on the client machine.

The pkg-get configuration file does not offer as many settings as the one
for prt-get. In particular, you cannot change "addcommand", "rmcommand", or 
"runscriptscommand"; these are hard-coded as /usr/bin/pkgadd, /usr/bin/pkgrm,
and /bin/bash, respectively.

There is also no intelligent version comparator as in prt-get; the
repository and html index are sorted lexographically according to the
current setting for $LANG. When multiple versions of a package are found
within the active collections, pkg-get will install the latest version in
the first collection that contains any such package. This behaviour is akin
to how prt-get handles dups, but with additional logic to account for
different versions of the built package within the same collection.

'pkg-get depends' and 'prt-get quickdep' do not handle more than one port,
unlike the corresponding commands in prt-get. Therefore it is not as
straightforward to preview the list of packages that would be installed,
before running a 'depinst' operation with multiple targets.

The limitation above would have been mitigated by a --test switch.
Alas, such a switch is also absent from the design of pkg-get. Use
the --test switch with prt-get itself, for the closest preview
of what would happen during a 'pkg-get depinst' operation.

'pkg-get dependent' does not support the --recursive option. Other
useful prt-get commands (grpinst, fsearch, deptree, listorphans, ls,
cat, edit, cache) have no counterpart in pkg-get. Of these omissions,
only the 'grpinst' command is of possible interest for binary package
management; the unimplemented commands and options are better handled
by prt-get itself. If you want a Perl implementation that does provide
these missing commands, consider the script written by user farkuhar [1].

pkg-get only makes use of the hard dependencies listed by the port
maintainer, not any of the eager linking that might have occurred on the
build machine. As a result, 'pkg-get depinst $foo' might omit some of the 
packages needed by $foo. User ppetrov^ has contributed some helper scripts 
to facilitate the fixing of these broken binaries; visit the site [2] to
download them.

Further omissions related to dependencies are the absence of any mechanism 
for declaring aliases (e.g., package openjdk16-bin can serve as a drop-in 
replacement for the listed dependency openjdk16), and the lack of an --ignore
switch (to exclude certain packages from being installed in a 'depinst' 
operation). You can work around these omissions by avoiding 'depinst'
entirely, and manually performing the desired 'install' transactions (once
you have a clear sense of what the actual runtime dependencies are).

These gaps in pkg-get's design highlight an awkward fact about trying to 
erect an infrastructure for binary package management upon a foundation 
designed for compiling source code (the ports tree). Inheriting the 
Pkgfile's lack of separation between build-time and runtime dependencies, 
pkg-get will unwittingly recurse through all the dependencies (in a 'depinst'
transaction) and install packages that you might not really need. Hence the
suggestion to consider avoiding 'depinst'. But pairing 'install' with the
helper script written by ppetrov^ [2] might not be enough to ensure zero
breakage, since revdep does not detect every runtime dependency. In the
end, you might have to manually interpolate between the (maximal) footprint
recommended by 'pkg-get depinst' and the (minimal) footprint recommended by
'revlibpkg' [2].

In handling any new hard dependencies added by the maintainer since 
the previous version of a package, pkg-get performs a sysup in the same 
manner as the original prt-get (i.e., new dependencies are not injected 
by default). With binary packages there's no need to carry out the
installation in any particular order, so the lack of dependency injection is
actually less of a problem for pkg-get than it was for prt-get. Combining
'pkg-get depends $foo | grep "\[ \]"' with the output of 'revlibpkg $foo' 
should help identify the packages you will need to install to fix any
breakage in $foo.

[1] https://git.sdf.org/jmq/Documentation/src/branch/master/scripts/prt-auf
[2] https://github.com/slackalaxy/depsck