UPDATE-PLIST(1) - General Commands Manual #
UPDATE-PLIST(1) - General Commands Manual
NAME #
update-plist - create or update packing-list(s) for a given port
SYNOPSIS #
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 #
update-plist is a helper script for the target update-plist in bsd.port.mk(5).
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.
update-plist
may need to know the
PORTSDIR
location in order to scan dependencies to trim common directories.
The options are as follows:
-C dir
Use a cache directory dir for scanning dependencies. Beware that this 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.
-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.
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 (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 unless these already exist, then move the new files into position.
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.
OpenBSD 7.5 - May 28, 2021