prt-get/doc/i3-softdeps.test

Thanks to hestia and jaeger for inspiring this hacking session (2023-08-22).
(Update 2023-08-25): see i3-softdeps.md in this directory for more
discussion on the merits of adding new prt-get features.

In light of the recent changes to libxkbcommon, jaeger made the observation
that `prt-get depinst i3` on a core-only system hits an error, as
libxkbcommon will be built without x11 support. To establish a reference point
for subsequent experiments, here is the list of targets that would be selected
by the latest official release of prt-get (5.19.6), in response to the
recommended way of installing a desired port.

All commands were performed on a pkg-cleaned installation of CRUX 3.7, leaving
the ports at whatever outdated version they had when this particular system was
last in daily use.

In[0]: prt-get depinst --test i3
Out[0]:
*** prt-get: test mode

-- Packages installed
fribidi
xorg-util-macros
xorg-libpixman
libev
libpng
libxml2
xorg-xtrans
libxkbcommon
libxslt
xorg-xcb-proto
yajl
xorg-xorgproto
freetype
glib
xorg-libice
xorg-libxau
xorg-libxdmcp
fontconfig
gobject-introspection
xorg-libsm
xorg-libxcb
xorg-libx11
xorg-xcb-util
xorg-xcb-util-renderutil
xorg-xcb-util-keysyms
xorg-xcb-util-wm
xorg-libxext
xorg-libxrender
xorg-libxt
xorg-libxkbfile
xorg-xcb-util-image
xorg-xcb-util-xrm
cairo
startup-notification
xorg-xkbcomp
xorg-xcb-util-cursor
harfbuzz
xkeyboard-config
xorg-libxft
pango
i3

-- installed packages with README files:
fontconfig

prt-get: installed successfully

*** prt-get: test mode end

As seen in the output above, at the time of building libxkbcommon, there are
only 7 non-core ports installed, none of which is xkeyboard-config, 
so the flag '-D enable-x11=false' gets passed to the meson setup command for
libxkbcommon. Thus the necessary linking to x11 libs does not happen, and i3
cannot compile successfully.

Suppose we try to fix this omission in the most natural way: append
xkeyboard-config at the end of i3's dependency list.

 sed -i '/^# Depends on/s/$/ xkeyboard-config/' /usr/ports/opt/i3/Pkgfile

Even this change is not enough! prt-get is not aware of the optional
dependency relationship between libxkbcommon and xkeyboard-config, and so
cannot insist that libxkbcommon comes later in the list of targets. jw
came to a similar conclusion 15 years ago (footnote 1).

Let's see whether farkuhar's softdeps-aware fork can do any better on this
task. The naive approach, prt-get depinst --softdeps i3, still doesn't work
because it will not automagically make two passes through the dependency tree
(the first pass to assemble a minimal installation set, and the second pass to
insert edges in the digraph based on optional dependency relationships among
the targets found). Instead, you have to manually ask for two traversals of the
dependency tree using a command substitution.

In[1]: prt-get isinst $(prt-get quickdep i3) | awk '/not installed/ {print $2}' \
    | xargs prt-get depinst --test --softdeps

(Note that it's also necessary to filter out the already-installed ports before
passing the quickdep output to `prt-get depinst` because this branch still
makes a distinction between install and update transactions.)

Out[1]:
*** prt-get: test mode

-- Packages installed
fribidi
xorg-util-macros
xorg-libpixman
libev
xorg-xtrans
libpng
libxml2
fontconfig
libxslt
xorg-xcb-proto
yajl
xorg-xorgproto
glib [post: deferred]
xorg-libxau
xorg-libxdmcp
xorg-libice
xorg-libxcb
xorg-libsm
xorg-libx11
xorg-xcb-util
xorg-xcb-util-renderutil
xorg-xcb-util-keysyms
xorg-xcb-util-wm
xorg-libxkbfile
xorg-libxext
xorg-libxrender
xorg-libxt
xorg-xcb-util-image
xorg-xcb-util-xrm
xorg-xkbcomp
cairo
startup-notification
xorg-xcb-util-cursor
xkeyboard-config
gobject-introspection
libxkbcommon
harfbuzz
freetype
xorg-libxft
pango
i3

-- installed packages with README files:
/usr/ports/opt/fontconfig

prt-get: installed successfully

*** prt-get: test mode end


This output looks more likely to succeed. Note that libxkbcommon would be built
AFTER its optional dependency xkeyboard-config, because when xkeyboard-config
appears among the depinst targets, that dependency relationship gets
incorporated into the sorting algorithm.


The mixed-upinst branch of farkuhar's prt-get goes further. Not only do you 
get the feature of respecting optional dependencies, you can also do the 
command substitution without the awk filter, and the appropriate mode 
(install or update) will be selected for each target.

In[2]: prt-get depinst --softdeps --test $(prt-get quickdep i3)

Out[2]: 
*** prt-get: test mode

-- Successful packages 
fribidi
xz
zlib
ncurses
expat
libffi
libnghttp2
openssl
libuv
lzlib
rhash
xorg-util-macros
libpcre2
xorg-libpixman
libev
libpng
elfutils
libxml2
readline
fontconfig
xorg-xtrans
file
curl
libxslt
sqlite3
libarchive
util-linux
python3
cmake
python3-setuptools
xorg-xcb-proto
yajl
meson
xorg-xorgproto
glib [post: deferred]
xorg-libxau
xorg-libxdmcp
xorg-libice
xorg-libxcb
xorg-libsm
xorg-libx11
xorg-xcb-util
xorg-xcb-util-renderutil
xorg-xcb-util-keysyms
xorg-xcb-util-wm
xorg-libxkbfile
xorg-libxext
xorg-libxrender
xorg-libxt
xorg-xcb-util-image
xorg-xcb-util-xrm
xorg-xkbcomp
cairo
startup-notification
xorg-xcb-util-cursor
xkeyboard-config
gobject-introspection
libxkbcommon
harfbuzz
freetype
xorg-libxft
pango
i3

--  Successful packages with README files:
fontconfig

prt-get: install successful.

*** prt-get: test mode end

The output of the last command reveals why we recommend performing a sysup
before installing new ports. Because dependencies in core are not listed unless
they are dynamically linked in, some of the out-of-date core ports on my test
system would get updated later, possibly leading to breakage (e.g, if the
desired port is relying on a new or backward-incompatible feature in one of
the foundational pieces of the toolchain).

Footnotes:
1. https://lists.crux.nu/pipermail/crux-devel/2008-May/003375.html

2. The more intuitive version of the above commands, `prt-get depinst
   --test --softdeps i3`, currently does NOT consider the dependency 
   relationship "libxkbcommon optionally depends on xkeyboard-config", because
   the latter port is neither currently installed, nor listed explicitly as an
   install target. This safeguard is meant to allow the operation to proceed
   after a SINGLE pass through the deptree, without pulling in ALL the ports
   listed as "Optional:" . In future we might consider letting the more
   intuitive command automatically make TWO passes through the deptree:
   first to pick up all the hard dependencies, and then to insert edges in the
   digraph that encode the optional dependencies among these targets. But such
   "automagic side-effects" (two traversals versus one) are typically frowned
   upon in CRUX, so for now we are happy to employ the command substitution
   $(prt-get quickdep i3) thereby communicating to prt-get our intention for
   two traversals of the deptree.


3. The result of trial 2 would be identical to that of 
   `prt-get install --softdeps $(prt-get quickdep i3)` using the 
   mixed-upinst branch, because 'install' on this branch behaves the same
   as 'depinst'. In https://lists.crux.nu/pipermail/crux/2008-June/001784.html
   jw describes this change as "prt-get no more silently assumes that the user
   didn't want a particular dependency".
   farkuhar's mixed-upinst branch still gives you the option to override this
   dependency-resolution-by-default; you just have to enter 'install --nodeps' 
   instead of simply 'install'.


4. Some maintainers prefer to do a filesystem check to determine whether a
   needed dependency was linked to one of its optional libraries, and then
   exit early with a message alerting the user to rebuild one of the packages
   in the dependency tree. See contrib/libreoffice for an example. This
   preference is arguably more aligned with CRUX's stance against excessively
   "holding the user's hand". The softdeps feature is not intended to supplant
   the user's thinking, but rather to give convenient access to a more versatile
   topological sorting algorithm than the one coded in the official prt-get. The
   toposort algorithm used in the above experiments remains true to the style
   of jw's original code, but you can see another working implementation in
   farkuhar's Perl rewrite
   https://git.sdf.org/jmq/Documentation/src/branch/master/scripts/prt-auf .