UPDATE-PLIST(1)

okay bestie, welcome to UPDATE-PLIST(1) — the General Commands Manual page for the helper that creates or updates packing-list(s) for a given port, and she is that girl 💅✨

🌸 NAME 🌸

update-plist — create or update packing-list(s) for a given port. That's the whole vibe, periodt 💖

✨ SYNOPSIS ✨

she takes env vars up front, then her own flags, then a --, then the pkg_create args — iconic layered look, ngl:

PORTSDIR=path [FAKE_TREE_OWNER=user PORTS_TREE_OWNER=user doas]
update-plist [-Ffmnqrvx] [-C dir] [-c var] [-E ext] [-e ext] [-I var]
             [-i var] [-j jobs] [-S var] [-s var] [-X path] [-w suffix]
             -- pkg_create_args ...

💖 DESCRIPTION 💖

okay so update-plist is a helper script for the update-plist target in bsd.port.mk(5). Not me explaining the same name twice — that's literally the target, bestie 🫶

Along with options and environment variables, update-plist uses the exact same options and arguments that would be passed to pkg_create(1). Since pkg_create(1) normally takes one single actual pkgname, there is no ambiguity in MULTI_PACKAGES situations. The first set of arguments correspond to the ‘default package’.

If PORTS_PRIVSEP is in effect, update-plist is run as root, but will switch back to FAKE_TREE_OWNER for scanning the installation directory and to PORTS_TREE_OWNER for writing packing-lists. Root for a sec, then back to your assigned besties, iykyk 👑

update-plist may need to know the PORTSDIR location in order to scan dependencies to trim common directories.

okay, options buffet time — here's every flag, no skips:

🎀 OPTIONS 🎀

• -C dir — use a cache directory dir for scanning dependencies. Beware: that directory should then be cleaned manually if the dependencies's packing-lists change. But this will speed up packing-list regeneration for ports with lots of dependencies significantly. highkey worth it for big ports 🔥
• -c var — variable var may be used as a way to insert @comment when other variables vanish.
• -E ext — write new files with ext extension instead of the default .new.
• -e ext — preserve old files as ext extension instead of the default .orig.
• -F — do not try to run pkg_locate(1).
• -f — force pkg_locate(1) to look up every file for conflicts instead of just the new ones.
• -I var — variable var may expand to nothing, in which case the variable from -c var can be used to prevent duplicate entries.
• -i var — ignore variable var for new substitutions. Only existing substitutions will be considered for the new lists.
• -j jobs — use jobs concurrent pkg_locate(1) pipes. Default is hw.ncpuonline.
• -n — do not move the final packing-lists in position. Instead, leave the <file>.new files for comparison.
• -q — quiet mode. Do not display status progress messages. Note that this is not the opposite of verbose mode.
• -r — run the fake directory scan as root.
• -S var — consider variable for substitution only at the end of paths, e.g., for suffixes like .pyc or .pyo.
• -s var — consider variable for substitution only at start of paths, e.g., for directories like /etc/rc.d or /usr/local.
• -v — verbose mode. Explain about directories stripped from dependencies. Note that this is not the opposite of quiet mode.
• -w suffix — warn about suffixes such as .orig that (usually) should not end into packing-lists.
• -X path — exclude file at absolute path from the information recorded in the packing-list.

---

okay now the heuristics, because this is where the main character energy really kicks in 🌈

update-plist assumes all multi-packages live under the same installation directory (pkg_create(1)'s -B option), and it will scan all paths under that directory and dispatch them into corresponding subpackages, using the following heuristics:

• files that were in existing packing-list(s) will be kept in the same packing-list.
• new files and directories will be put in the packing-list that owns the corresponding directory.
• barring that, new files will be put into the first packing-list whose PREFIX fits.

As far as possible, everything that looks like actual files will be sorted in alphabetical order, after variable substitutions ✨

update-plist will warn for a lot of conditions, such as pre-formatted manpages, or files ending in pre-patch suffixes. Adding a @comment intentional<reason> will silence the warning. For instance:

@man man/ja_JP.EUC/cat1/kakasi.0
@comment intentional: mandoc doesn't handle this locale

update-plist will also scan dependencies, in order to strip common directories.

If the pkglocatedb package is installed, update-plist will make use of it and report unregistered conflicts. This can be disabled with -F as it is time-consuming.

Most SUBST_VARS variables will be back-substituted into the regenerated packing-lists, starting from the longest variable values. update-plist tries to keep existing substitutions. It does not add new substitutions on BASE_PKGPATH and BUILD_PKGPATH, it does only substitute FULLPKGNAME in share/doc/pkg-readmes and it currently does not add new substitutions for ARCH nor MACHINE_ARCH.

Some packages — and yes, notoriously Python packages — create some directories optionally based on flavors. Options -c and -I can be used to avoid duplicate directory definitions.

Specifically, a generated packing-list would contain:

lib/python${MODPY_VERSION}/site-packages/bpdb/
lib/python${MODPY_VERSION}/site-packages/bpdb/${MODPY_PYCACHE}/

which expands to:

lib/python3.7/site-packages/bpdb/
lib/python3.7/site-packages/bpdb/__pycache__/

for python3, which is fine 🌸

But for python2, variable ‘MODPY_PYCACHE’ will be empty, resulting in:

lib/python2.7/site-packages/bpdb/
lib/python2.7/site-packages/bpdb/

thus a duplicate directory, pkg_create(1) won't be happy 😭

Using UPDATE_PLIST_ARGS = -c MODPY_COMMENT -I MODPY_PYCACHE will result in injecting ${MODPY_COMMENT} wherever update-plist finds a duplicate directory by replacing ${MODPY_PYCACHE} with nothing.

This yields:

lib/python${MODPY_VERSION}/site-packages/bpdb/
${MODPY_COMMENT}lib/python${MODPY_VERSION}/site-packages/bpdb/MODPY_PYCACHE}/

and for python2 this expands to:

lib/python2.7/site-packages/bpdb/
@comment lib/python2.7/site-packages/bpdb/

which is exactly what we want 💅

Specific items such as shared libraries or binaries will gain annotations and special handling, for instance LIBlibname_VERSION.

Existing packing-lists are scanned for non-file entries, such as newuser, mode, or exec markers. Those will be inserted into the updated packing-lists at the most likely position.

update-plist will first write files as <file>.new, then it will display which files are new and which files have changed. If old packing-lists already exist, it will move old packing lists into <file>.orig, then move the new files into position. iconic cleanup behavior, honestly 🧚

🦋 SEE ALSO 🦋

• pkg_add(1)
• pkg_create(1)
• bsd.port.mk(5)

💀 BUGS AND LIMITATIONS 💀

update-plist might be the most complicated piece of the ports infrastructure. There will always be cases that require manual intervention. Since fake is now run as non-root, update-plist can't figure out users and groups for new files, so these should be considered carefully. no cap, read that part twice 🫶

---

mwah 💋 this page is from the Debian build, dated April 14, 2024, and the manual is UPDATE-PLIST(1) — go slay your packing-lists, bestie 🌈👑