1.\" $OpenBSD: update-plist.1,v 1.6 2019/08/08 20:37:08 fcambus 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: August 8 2019 $ 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 Fmnqrvx 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 I Ar var 108Variable 109.Ar var 110may expand to nothing, in which case the variable from 111.Fl c Ar var 112can be used to prevent duplicate entries. 113.It Fl i Ar var 114Ignore variable 115.Ar var 116for new substitutions. 117Only existing substitutions will be considered for the new lists. 118.It Fl j Ar jobs 119Use 120.Ar jobs 121concurrent 122.Xr pkg_locate 1 123pipes. 124Default is 125.Sq hw.ncpuonline . 126.It Fl n 127Do not move the final packing-lists in position. 128Instead, leave the 129.Pa <file>.new 130files for comparison. 131.It Fl q 132Quiet mode. 133Do not display status progress messages. 134Note that this is not the opposite of verbose mode. 135.It Fl r 136Run the 137.Pa fake 138directory scan as root. 139.It Fl S Ar var 140Consider variable for substitution only at the end of paths, 141e.g., for suffixes like 142.Pa .pyc 143or 144.Pa .pyo . 145.It Fl s Ar var 146Consider variable for substitution only at start of paths, 147e.g., for directories like 148.Pa /etc/rc.d 149or 150.Pa /usr/local . 151.It Fl v 152Verbose mode. 153Explain about directories stripped from dependencies. 154Note that this is not the opposite of quiet mode. 155.It Fl w Ar suffix 156Warn about suffixes such as 157.Ar .orig 158that (usually) should not end into packing-lists. 159.It Fl X Ar path 160Exclude file at absolute 161.Ar path 162from the information recorded in the packing-list. 163.El 164.Pp 165.Nm 166assumes all multi-packages live under the same installation directory 167.Po 168.Xr pkg_create 1 Ns 's 169.Fl B 170option 171.Pc , 172and it will scan all paths under that directory and dispatch 173them into corresponding subpackages, using the following heuristics: 174.Bl -bullet 175.It 176files that were in existing packing-list(s) will be kept in the same 177packing-list. 178.It 179new files and directories will be put in the packing-list that owns 180the corresponding directory. 181.It 182baring that, new files will be put into the first packing-list whose PREFIX 183fits. 184.El 185.Pp 186As far as possible, everything that looks like actual files will be sorted 187in alphabetical order, after variable substitutions. 188.Pp 189.Nm 190will warn for a lot of conditions, such as pre-formatted manpages, or files 191ending in pre-patch suffixes. 192Adding a 193.Cm @comment Ar intentional<reason> 194will silence the warning. 195For instance: 196.Bd -literal -offset indent 197@man man/ja_JP.EUC/cat1/kakasi.0 198@comment intentional: mandoc does't handle this locale 199.Ed 200.Pp 201.Nm 202will also scan dependencies, in order to strip common directories. 203.Pp 204If the 205.Ar pkglocatedb 206package is installed, 207.Nm 208will make use of it and report unregistered conflicts. 209This can be disabled with 210.Fl F 211as it is time-consuming. 212.Pp 213Most 214.Ev SUBST_VARS 215variables will be back-substituted into the regenerated packing-lists, 216starting from the longest variable values. 217.Nm 218tries to keep existing substitutions. 219It does not add new substitutions on 220.Ev BASE_PKGPATH 221and 222.Ev BUILD_PKGPATH , 223it does only substitute 224.Ev FULLPKGNAME 225in 226.Pa share/doc/pkg-readmes 227and it currently does not add new substitutions for 228.Ev ARCH 229nor 230.Ev MACHINE_ARCH . 231.Pp 232Some packages (notoriously Python packages) create some directories optionally 233based on flavors. 234Options 235.Fl c 236and 237.Fl I 238can be used to avoid duplicate directory definitions. 239.Pp 240Specifically, a generated packing-list would contain 241.Bd -literal -offset indent -compact 242lib/python${MODPY_VERSION}/site-packages/bpdb/ 243lib/python${MODPY_VERSION}/site-packages/bpdb/${MODPY_PYCACHE}/ 244.Ed 245which expands to 246.Bd -literal -offset indent -compact 247lib/python3.7/site-packages/bpdb/ 248lib/python3.7/site-packages/bpdb/__pycache__/ 249.Ed 250for python3, which is fine. 251.Pp 252But for python2, variable 253.Sq MODPY_PYCACHE 254will be empty, resulting in 255.Bd -literal -offset indent -compact 256lib/python2.7/site-packages/bpdb/ 257lib/python2.7/site-packages/bpdb/ 258.Ed 259thus a duplicate directory, 260.Xr pkg_create 1 261won't be happy. 262.Pp 263Using 264.Ev UPDATE_PLIST_ARGS = Fl c Ar MODPY_COMMENT Fl I Ar MODPY_PYCACHE 265will result in injecting 266.Sq ${MODPY_COMMENT} 267wherever 268.Nm 269finds a duplicate directory by replacing 270.Sq ${MODPY_PYCACHE} 271with nothing. 272.Pp 273This yields 274.Bd -literal -offset indent -compact 275lib/python${MODPY_VERSION}/site-packages/bpdb/ 276${MODPY_COMMENT}lib/python${MODPY_VERSION}/site-packages/bpdb/MODPY_PYCACHE}/ 277.Ed 278and for python2 this expands to 279.Bd -literal -offset indent -compact 280lib/python2.7/site-packages/bpdb/ 281@comment lib/python2.7/site-packages/bpdb/ 282.Ed 283which is exactly what we want. 284.Pp 285Specific items such as shared libraries or binaries will gain annotations 286and special handling, for instance 287.Ev LIBlibname_VERSION . 288.Pp 289Existing packing-lists are scanned for non-file entries, such as 290.Cm newuser , 291.Cm mode , 292or 293.Cm exec 294markers. 295Those will be inserted into the updated packing-lists at the most likely 296position. 297.Pp 298.Nm 299will first write files as 300.Pa <file>.new , 301then it will display which files are new and which files have changed. 302If old packing-lists already exist, it will move old packing lists into 303.Pa <file>.orig 304unless these already exist, then move the new files into position. 305.Sh SEE ALSO 306.Xr pkg_add 1 , 307.Xr pkg_create 1 , 308.Xr bsd.port.mk 5 309.Sh BUGS AND LIMITATIONS 310.Nm 311might be the most complicated piece of the ports infrastructure. 312There will always be cases that require manual intervention. 313. 314Since 315.Ar fake 316is now run as non-root, 317.Nm 318can't figure out users and groups for new files, so these should be 319considered carefully. 320