1.\" $OpenBSD: update-plist.1,v 1.10 2024/04/14 17:24:15 phessler Exp $ 2.\" 3.\" Copyright (c) 2018 Marc Espie <espie@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 14 2024 $ 18.Dt UPDATE-PLIST 1 19.Os 20.Sh NAME 21.Nm update-plist 22.Nd create or update packing-list(s) for a given port 23.Sh SYNOPSIS 24.Ev PORTSDIR Ns = Ns Ar path 25.Op Ev FAKE_TREE_OWNER Ns = Ns Ar user Ev PORTS_TREE_OWNER Ns = Ns Ar user Nm doas 26.Nm 27.Op Fl Ffmnqrvx 28.Op Fl C Ar dir 29.Op Fl c Ar var 30.Op Fl E Ar ext 31.Op Fl e Ar ext 32.Op Fl I Ar var 33.Op Fl i Ar var 34.Op Fl j Ar jobs 35.Op Fl S Ar var 36.Op Fl s Ar var 37.Op Fl X Ar path 38.Op Fl w Ar suffix 39.Fl - 40.Ar pkg_create_args ... 41.Sh DESCRIPTION 42.Nm 43is a helper script for the target 44.Ar update-plist 45in 46.Xr bsd.port.mk 5 . 47.Pp 48Along with options and environment variables, 49.Nm 50uses the exact same options and arguments that would be passed to 51.Xr pkg_create 1 . 52Since 53.Xr pkg_create 1 54normally takes one single actual 55.Ar pkgname , 56there is no ambiguity in 57.Ev MULTI_PACKAGES 58situations. 59.Pp 60The first set of arguments correspond to the 61.Sq default package . 62.Pp 63If 64.Ev PORTS_PRIVSEP 65is in effect, 66.Nm 67is run as root, but will switch back to 68.Ev FAKE_TREE_OWNER 69for scanning the installation directory and to 70.Ev PORTS_TREE_OWNER 71for writing packing-lists. 72.Pp 73.Nm 74may need to know the 75.Ev PORTSDIR 76location in order to scan dependencies to trim common directories. 77.Pp 78The options are as follows: 79.Bl -tag -width Ds 80.It Fl C Ar dir 81Use a cache directory 82.Ar dir 83for scanning dependencies. 84Beware that this directory should then be cleaned manually if the 85dependencies's packing-lists change. 86But this will speed up packing-list regeneration for ports with 87lots of dependencies significantly. 88.It Fl c Ar var 89Variable 90.Ar var 91may be used as a way to insert 92.Cm @ Ns comment 93when other variables vanish. 94.It Fl E Ar ext 95Write new files with 96.Ar ext 97extension instead of the default 98.Pa .new . 99.It Fl e Ar ext 100Preserve old files as 101.Ar ext 102extension instead of the default 103.Pa .orig . 104.It Fl F 105Do not try to run 106.Xr pkg_locate 1 . 107.It Fl f 108Force 109.Xr pkg_locate 1 110to look up every file for conflicts instead of just the new ones. 111.It Fl I Ar var 112Variable 113.Ar var 114may expand to nothing, in which case the variable from 115.Fl c Ar var 116can be used to prevent duplicate entries. 117.It Fl i Ar var 118Ignore variable 119.Ar var 120for new substitutions. 121Only existing substitutions will be considered for the new lists. 122.It Fl j Ar jobs 123Use 124.Ar jobs 125concurrent 126.Xr pkg_locate 1 127pipes. 128Default is 129.Sq hw.ncpuonline . 130.It Fl n 131Do not move the final packing-lists in position. 132Instead, leave the 133.Pa <file>.new 134files for comparison. 135.It Fl q 136Quiet mode. 137Do not display status progress messages. 138Note that this is not the opposite of verbose mode. 139.It Fl r 140Run the 141.Pa fake 142directory scan as root. 143.It Fl S Ar var 144Consider variable for substitution only at the end of paths, 145e.g., for suffixes like 146.Pa .pyc 147or 148.Pa .pyo . 149.It Fl s Ar var 150Consider variable for substitution only at start of paths, 151e.g., for directories like 152.Pa /etc/rc.d 153or 154.Pa /usr/local . 155.It Fl v 156Verbose mode. 157Explain about directories stripped from dependencies. 158Note that this is not the opposite of quiet mode. 159.It Fl w Ar suffix 160Warn about suffixes such as 161.Ar .orig 162that (usually) should not end into packing-lists. 163.It Fl X Ar path 164Exclude file at absolute 165.Ar path 166from the information recorded in the packing-list. 167.El 168.Pp 169.Nm 170assumes all multi-packages live under the same installation directory 171.Po 172.Xr pkg_create 1 Ns 's 173.Fl B 174option 175.Pc , 176and it will scan all paths under that directory and dispatch 177them into corresponding subpackages, using the following heuristics: 178.Bl -bullet 179.It 180files that were in existing packing-list(s) will be kept in the same 181packing-list. 182.It 183new files and directories will be put in the packing-list that owns 184the corresponding directory. 185.It 186barring that, new files will be put into the first packing-list whose PREFIX 187fits. 188.El 189.Pp 190As far as possible, everything that looks like actual files will be sorted 191in alphabetical order, after variable substitutions. 192.Pp 193.Nm 194will warn for a lot of conditions, such as pre-formatted manpages, or files 195ending in pre-patch suffixes. 196Adding a 197.Cm @comment Ar intentional<reason> 198will silence the warning. 199For instance: 200.Bd -literal -offset indent 201@man man/ja_JP.EUC/cat1/kakasi.0 202@comment intentional: mandoc doesn't handle this locale 203.Ed 204.Pp 205.Nm 206will also scan dependencies, in order to strip common directories. 207.Pp 208If the 209.Ar pkglocatedb 210package is installed, 211.Nm 212will make use of it and report unregistered conflicts. 213This can be disabled with 214.Fl F 215as it is time-consuming. 216.Pp 217Most 218.Ev SUBST_VARS 219variables will be back-substituted into the regenerated packing-lists, 220starting from the longest variable values. 221.Nm 222tries to keep existing substitutions. 223It does not add new substitutions on 224.Ev BASE_PKGPATH 225and 226.Ev BUILD_PKGPATH , 227it does only substitute 228.Ev FULLPKGNAME 229in 230.Pa share/doc/pkg-readmes 231and it currently does not add new substitutions for 232.Ev ARCH 233nor 234.Ev MACHINE_ARCH . 235.Pp 236Some packages (notoriously Python packages) create some directories optionally 237based on flavors. 238Options 239.Fl c 240and 241.Fl I 242can be used to avoid duplicate directory definitions. 243.Pp 244Specifically, a generated packing-list would contain 245.Bd -literal -offset indent -compact 246lib/python${MODPY_VERSION}/site-packages/bpdb/ 247lib/python${MODPY_VERSION}/site-packages/bpdb/${MODPY_PYCACHE}/ 248.Ed 249which expands to 250.Bd -literal -offset indent -compact 251lib/python3.7/site-packages/bpdb/ 252lib/python3.7/site-packages/bpdb/__pycache__/ 253.Ed 254for python3, which is fine. 255.Pp 256But for python2, variable 257.Sq MODPY_PYCACHE 258will be empty, resulting in 259.Bd -literal -offset indent -compact 260lib/python2.7/site-packages/bpdb/ 261lib/python2.7/site-packages/bpdb/ 262.Ed 263thus a duplicate directory, 264.Xr pkg_create 1 265won't be happy. 266.Pp 267Using 268.Ev UPDATE_PLIST_ARGS = Fl c Ar MODPY_COMMENT Fl I Ar MODPY_PYCACHE 269will result in injecting 270.Sq ${MODPY_COMMENT} 271wherever 272.Nm 273finds a duplicate directory by replacing 274.Sq ${MODPY_PYCACHE} 275with nothing. 276.Pp 277This yields 278.Bd -literal -offset indent -compact 279lib/python${MODPY_VERSION}/site-packages/bpdb/ 280${MODPY_COMMENT}lib/python${MODPY_VERSION}/site-packages/bpdb/MODPY_PYCACHE}/ 281.Ed 282and for python2 this expands to 283.Bd -literal -offset indent -compact 284lib/python2.7/site-packages/bpdb/ 285@comment lib/python2.7/site-packages/bpdb/ 286.Ed 287which is exactly what we want. 288.Pp 289Specific items such as shared libraries or binaries will gain annotations 290and special handling, for instance 291.Ev LIBlibname_VERSION . 292.Pp 293Existing packing-lists are scanned for non-file entries, such as 294.Cm newuser , 295.Cm mode , 296or 297.Cm exec 298markers. 299Those will be inserted into the updated packing-lists at the most likely 300position. 301.Pp 302.Nm 303will first write files as 304.Pa <file>.new , 305then it will display which files are new and which files have changed. 306If old packing-lists already exist, it will move old packing lists into 307.Pa <file>.orig , 308then move the new files into position. 309.Sh SEE ALSO 310.Xr pkg_add 1 , 311.Xr pkg_create 1 , 312.Xr bsd.port.mk 5 313.Sh BUGS AND LIMITATIONS 314.Nm 315might be the most complicated piece of the ports infrastructure. 316There will always be cases that require manual intervention. 317. 318Since 319.Ar fake 320is now run as non-root, 321.Nm 322can't figure out users and groups for new files, so these should be 323considered carefully. 324