1.\" $OpenBSD: pkg_create.1,v 1.131 2023/07/05 01:21:51 jsg Exp $ 2.\" 3.\" Documentation and design originally from FreeBSD. All the code has 4.\" been rewritten since. We keep the documentation's notice: 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" Jordan K. Hubbard 16.\" 17.\" 18.\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords, 19.\" added dependency tracking, etc. 20.\" 21.\" [jkh] Took John's changes back and made some additional extensions for 22.\" better integration with FreeBSD's new ports collection. 23.\" 24.Dd $Mdocdate: July 5 2023 $ 25.Dt PKG_CREATE 1 26.Os 27.Sh NAME 28.Nm pkg_create 29.Nd create binary software package for distribution 30.Sh SYNOPSIS 31.Nm pkg_create 32.Bk -words 33.Op Fl mnQqSvx 34.Op Fl A Ar arches 35.Op Fl B Ar pkg-destdir 36.Op Fl D Ar name Ns Op = Ns Ar value 37.Op Fl L Ar localbase 38.Op Fl M Ar displayfile 39.Op Fl P Ar pkgpath : Ns Ar pkgspec : Ns Ar default 40.Op Fl U Ar undisplayfile 41.Op Fl u Ar userlist 42.Op Fl V Ar n 43.Op Fl W Ar libspec 44.Fl d Ar desc 45.Fl D Ar COMMENT Ns = Ns Ar value 46.Fl D Ar FULLPKGPATH Ns = Ns Ar value 47.Fl D Ar PORTSDIR Ns = Ns Ar value 48.Fl f Ar packinglist 49.Fl p Ar prefix 50.Ar pkg-name 51.Ek 52.Nm pkg_create 53.Fl f Ar packinglist 54.Sh DESCRIPTION 55The 56.Nm 57command is normally used to create a binary package named 58.Ar pkg-name , 59for subsequent use with 60.Xr pkg_add 1 , 61.Xr pkg_delete 1 62and 63.Xr pkg_info 1 . 64.Ar pkg-name 65will traditionally have a 66.Dq .tgz 67extension, to denote the underlying binary format. 68.Ar pkg-name 69must follow 70.Xr packages-specs 7 . 71.Pp 72Use of the 73.Xr ports 7 74infrastructure instead of manual 75.Nm 76invocation is strongly recommended. 77.Pp 78.Nm 79can also be used to recreate a binary package from an existing installation. 80.Pp 81During package creation, 82.Nm 83replaces too long file names with smaller equivalents 84.Po 85see 86.Xr package 5 87.Pc , 88records extra information in the packing-list, such as the existence 89of symlinks and hard links, computes and stores file checksums, and 90verifies that all special objects are properly annotated in the packing-list. 91.Pp 92It will also check all required shared libraries 93for reachability, by looking into all installed dependencies. 94It may also ask the ports tree for extra dependencies, 95provided some other dependency refers to the same 96.Ev BASE_PKGPATH 97.Po 98see 99.Xr bsd.port.mk 5 100.Pc . 101The rationale is that those libraries must already be present for 102the package to build correctly, and thus be reachable through the 103subset of dependencies that are not pure 104.Ev RUN_DEPENDS . 105.Pp 106The options are as follows: 107.Bl -tag -width Ds 108.It Fl A Ar arches 109Register a list of architectures for which this package should install. 110.Ar arches 111is a comma-separated list of architectures. 112Use 113.Sq * 114to mean any architecture (e.g., arch-independent packages). 115.It Fl B Ar pkg-destdir 116Set 117.Ar pkg-destdir 118as the prefix to prepend to any file to select for the package. 119.It Fl D Ar name Ns Op = Ns Ar value 120Define 121.Ar name 122to 123.Ar value 124(or just define it) 125for substitution and fragment inclusion purposes. 126Some specific 127.Ar names 128have extra meaning, see 129.Xr bsd.port.mk 5 130and 131.Xr package 5 132for details: 133.Pp 134.Bl -tag -width FULLPKGPATH -compact 135.It Cm CDROM 136Set to the port's Makefile 137.Va PERMIT_PACKAGE_CDROM . 138.It Cm COMMENT 139Set package 140.Dq one line description 141(mandatory). 142.It Cm HISTORY_DIR 143Record checksums of files in permanent location 144.Pa ${HISTORY_DIR}/${FULLPKGPATH:S,/,./g}.lru . 145.It Cm FTP 146Set to the port's Makefile 147.Va PERMIT_PACKAGE_FTP . 148.It Cm FULLPKGPATH 149Location in the ports tree, mandatory for updates to work 150.Po 151see 152.Xr pkg_add 1 153.Pc . 154.It Cm HOMEPAGE 155If defined, appended to the description. 156.It Cm MAINTAINER 157If defined, appended to the description. 158.It Cm NO_TS_IN_PLIST 159If set, disable the 160.Cm @ts 161annotations in the generated package, rely on the normal 162.Xr tar 1 163timestamps instead. 164(Mostly used to create firmware "packages" since 165.Xr fw_update 8 166only handles a very small subset of the 167.Xr package 5 168format.) 169.It Cm USE_GROFF 170Set to 1 to have groff format manpages behind the scenes during 171package creation. 172.It Cm REVISION_CHECK , EPOCH_CHECK , FLAVOR_LIST_CHECK 173Set automatically by 174.Xr bsd.port.mk 5 175to values that help 176.Nm 177catch a few errors in package naming. 178.El 179.It Fl d Oo Fl Oc Ns Ar desc 180Fetch long description for package from file 181.Ar desc 182or, if preceded by 183.Sq - , 184the argument itself. 185.It Fl f Ar packinglist 186Fetch 187.Dq packing-list 188for package from the file 189.Ar packinglist . 190Several packing-lists can be mentioned, in which case they will be 191concatenated together. 192.It Fl L Ar localbase 193Record 194.Ar localbase 195as the localbase used in the package 196.Po 197By default, 198.Pa /usr/local 199.Pc . 200Packages built with another localbase can only be installed by using 201the same localbase in 202.Xr pkg_add 1 , 203to prevent errors. 204.It Fl M Ar displayfile 205Display the file (using 206.Xr more 1 ) 207after installing the package. 208Useful for things like 209legal notices on almost-free software, etc. 210.It Fl m 211Causes 212.Nm 213to always display the progress meter in cases it would not do so by default. 214.It Fl n 215Don't actually create a package. 216.It Fl P Ar pkgpath : Ns Ar pkgspec : Ns Ar default 217Declare a dependency on a package matching 218.Ar pkgspec 219.Pq see Xr packages-specs 7 . 220An appropriate package must be installed before this package may be 221installed, and that package must be deinstalled before this package 222is deinstalled. 223The dependency also contains a 224.Ar pkgpath 225.Po 226see 227.Xr pkgpath 7 228.Pc 229and a 230.Ar default 231package name, in case there is no listing of available packages. 232.Pp 233As a special case, 234.Sq = 235may be used as a 236.Ar pkgspec , 237to match the 238.Ar default 239version exactly. 240.It Fl p Ar prefix 241Set 242.Ar prefix 243as the initial directory 244.Dq base 245to start from in selecting files for 246the package, and to record as the base for installing the package. 247.It Fl Q 248Print out the files in the actual packing-list of the package being 249generated, with explicit typing 250.Pq e.g. Cm @file , @lib , ... . 251.It Fl q 252Print out the actual packing-list of the package being generated 253(query mode). 254Most often used in combination with 255.Fl n . 256.It Fl S 257Print the update signature of the package. 258See 259.Xr pkg_info 1 . 260.It Fl U Ar undisplayfile 261Display the file (using 262.Xr more 1 ) 263when deinstalling the package. 264Useful for reminders about stuff to clean up. 265.It Fl u Ar userlist 266Check all 267.Cm @newuser 268and 269.Cm @newgroup 270statements against a 271.Ar userlist 272file 273.Po 274usually 275.Pa ${PORTSDIR}/infrastructure/db/user.list 276.Pc 277and error out for entries not registered in that file. 278Also error out if the file is incoherent. 279.It Fl V Ar n 280Adds 281.Ar n 282to the 283.Sq global system version 284of the package 285.Po see 286.Xr package 5 287.Pc . 288The default value of 0 is not recorded, thus packages without 289.Cm @version 290have an implicit version of 0. 291.It Fl v 292Turn on verbose output. 293.It Fl W Ar libspec 294Package needs a shared library to work. 295.Ar libspec 296is 297.Sq name.major.minor 298or 299.Sq path/name.major.minor . 300The package won't be installed unless a library with the same name, 301the exact same major number and at least the same minor number can 302be located. 303A library without path is searched through dependent packages under the 304same 305.Ar localbase , 306then in the system libraries under 307.Pa /usr/lib 308and 309.Pa /usr/X11R6/lib . 310A library with a path is only searched through dependent packages, 311that path being relative to 312.Ar localbase . 313.It Fl x 314Disable progress meter. 315.El 316.Pp 317.Nm 318can also be invoked with only the packing-list from an installed package. 319It will recreate the corresponding binary package in the current directory 320from the installation, or error out if any problem is found. 321For example, 322the following will recreate a 323.Pa kdelibs-3.4.3.tgz 324package: 325.Bd -literal -offset indent 326pkg_create -f /var/db/pkg/kdelibs-3.4.3/+CONTENTS 327.Ed 328.Sh PACKING-LIST DETAILS 329The 330.Dq packing-list 331format (see 332.Fl f ) 333is fairly straightforward: basically a list of filenames and directory names 334to include in the package. 335.Pp 336Substitution of variables and inclusion of fragments is documented in the 337next section. 338.Pp 339Directory names are denoted by a trailing slash. 340.Pp 341There are some annotations that can be inserted for better control. 342All these commands start with an 343.Sq @ . 344The following annotations can be inserted manually (but commonly 345.Xr update-plist 1 346is used for creating most packing-list contents): 347.Pp 348.Bl -tag -width Ds -compact 349.It Cm @ask-update Ar pkgspec message 350Mechanism to prevent unwanted updates. 351If the new package is installed as part of an update matching 352.Ar pkgspec , 353the 354.Ar message 355will be displayed to the user. 356In non-interactive mode, the update will abort. 357Otherwise, the user will have a chance to proceed. 358Automated updates can be done by using 359.Fl D Ar update_stem , 360with 361.Ar stem 362the stem of the 363.Ar pkgspec . 364Classical use case for postgresql: 365.Bd -literal -offset 3n 366@ask-update postgresql-server-<8 Make sure your existing database is backed up 367.Ed 368.Pp 369Use very sparingly. 370Most cases that seem to require manual updates just require a bit more thought. 371.Pp 372.It Cm @bin Ar filename 373Describe the file as an 374.Ox 375binary executable (not a script). 376.Pp 377.It Cm @comment Ar string 378Place a comment in the packing-list. 379Useful in trying to document some particularly hairy sequence that 380may trip someone up later. 381Can also be used to comment out elements that update-plist 382.Pq see Xr bsd.port.mk 5 383will insist in inserting in a packing-list. 384.Pp 385The special comment 386.Cm @comment no checksum 387can be used to tag the next file as special: even though its characteristics 388will be recorded in the package, it can be altered after installation, and 389.Xr pkg_delete 1 390will still delete it. 391.Pp 392The special comment 393.Cm @comment no debug 394can be used to tag the next file as special: even though it might be a 395binary, it has no debug info 396.Po 397see 398.Xr build-debug-info 1 399.Pc . 400.Pp 401.It Cm @conflict Ar pkgspec 402Declare a conflict with packages matching 403.Ar pkgspec 404.Pq see Xr packages-specs 7 . 405The 406.Ar pkgname 407package can 408.Em not 409be installed if a package 410matching 411.Ar pkgspec 412has been installed because they install the same files and thus conflict. 413.Pp 414.It Cm @cwd Ar pathname 415Set the package current directory. 416All subsequent filenames will be assumed relative to 417.Ar pathname . 418.Pp 419.It Cm @dir Ar directoryname 420Create directory 421.Ar directoryname 422at 423.Xr pkg_add 1 424time, taking 425.Cm @mode , 426.Cm @group , 427and 428.Cm @owner 429into account, and remove it during 430.Xr pkg_delete 1 . 431Directories to remove can be shared between packages. 432If 433.Ar name 434does not begin with an @, same as 435.Dl name/ 436.Pp 437.It Cm @define-tag Ar tag mode params 438Define a tag of name 439.Ar tag . 440Tags define actions to be performed at specific time during 441.Xr pkg_add 1 442and 443.Xr pkg_delete 1 . 444A given tag may be defined several times with additional properties. 445Currently, the following modes are defined: 446.Bl -tag -width abc -compact 447.It Ar at-end 448if the tag occurs in any dependency, the given command 449.Ar params 450is executed at the end, similar to 451.Cm @exec 452commands. 453.Pp 454The 455.Cm "\&%D" 456escape sequence stands for localbase. 457.Pp 458Actual tags may themselves contain parameters, so the 459.Ar params 460list recognizes two additional escape sequences: 461.Bl -tag -width indent 462.It Cm "\&%l" 463list of tag parameters, in a random order, with duplicates removed. 464.It Cm "\&%u" 465execute the command once for each distinct tag parameter. 466.El 467.Pp 468As a special case, deleting the package that contains the 469.Cm @define-tag 470will work differently: 471If that 472.Cm @tag 473is present in the same package as the 474.Cm @define-tag , 475then it will be run when encountered, presumably before the command itself 476has been deleted. 477If that 478.Cm @tag 479is not present, the command won't be run at all, 480since the package has been deleted from the file system, 481and usually cleaning up only requires removing index files. 482.Pp 483.It Ar supersedes 484If the given tag is found in dependencies, it supersedes the other 485tag given in the same line. 486For instance: 487.Bd -literal -offset indent 488@define-tag mktexlsr at-end mktexlsr 489@define-tag mktexlsr-local at-end mktexlsr texmf-local 490@define-tag mktexlsr supersedes mktexlsr-local 491.Ed 492.Pp 493Here, the tag 494.Ar mktexlsr 495rebuilds every texmf directory index, whereas 496.Ar mktexlsr-local 497only rebuilds the local texmf directory index, 498so if both tags are seen, only the global command will be run. 499.El 500.Pp 501.It Cm @exec Ar command 502Execute 503.Ar command 504during 505.Xr pkg_add 1 . 506Note that 507.Cm @exec 508commands are executed relative to their location in the packing-list, 509so they can rely on any data that have already been extracted, 510but not on anything that is listed after them. 511Some special elements, such as new users and new groups, are always 512created first, so that 513.Cm @exec 514can rely on them. 515.Pp 516.Xr pkg_add 1 517and 518.Xr pkg_delete 1 519set the 520.Ev PATH 521to a predictable value: 522.Bd -literal -offset indent 523/bin:/sbin:/usr/bin:/usr/sbin:/usr/X11R6/bin:${LOCALBASE}/bin:${LOCALBASE}/sbin 524.Ed 525.Pp 526during execution. 527.Pp 528If 529.Ar command 530contains any of the following sequences somewhere in it, they will 531be expanded inline. 532For the following examples, assume that 533.Cm @cwd 534is set to 535.Pa /usr/local 536and the last extracted file was 537.Pa bin/emacs . 538.Bl -tag -width indent 539.It Cm "\&%B" 540Expands to the 541.Dq basename 542of the fully qualified filename, that 543is the current directory prefix, plus the last filespec, minus 544the trailing filename. 545In the example case, that would be 546.Pa /usr/local/bin . 547.It Cm "\&%D" 548Expands to the current directory prefix, as set with 549.Cm @cwd ; 550in the example case 551.Pa /usr/local . 552.It Cm "\&%F" 553Expands to the last filename extracted (as specified); in the example case, 554.Pa bin/emacs . 555.It Cm "\&%f" 556Expands to the 557.Dq filename 558part of the fully qualified name, or 559the converse of 560.Cm \&%B ; 561in the example case, 562.Pa emacs . 563.El 564.Pp 565.It Cm @exec-always Ar command 566Synonym of 567.Cm @exec . 568.Pp 569.It Cm @exec-add Ar command 570Similar to 571.Cm @exec , 572except it only gets executed during new installations, 573and not during updates. 574.Pp 575.It Cm @exec-update Ar command 576Similar to 577.Cm @exec , 578except it only gets executed during updates, 579and not during new installations. 580.Pp 581.It Cm @extra Ar filename 582Declare extra file 583.Ar filename 584to be deleted at deinstall time, if user sets the 585.Fl c 586option. 587Those files are extra configuration files that are normally not deleted. 588.Ar filename 589can be an absolute path. 590If 591.Ar filename 592ends with a slash, it is a directory. 593.Pp 594.It Cm @extraunexec Ar command 595Extra 596.Ar command 597to execute when removing extra files. 598.Pp 599.It Cm @file Ar filename 600Default annotation, to use if 601.Ar filename 602begins with @. 603.Ar filename 604is always a relative path, relative to the current 605.Cm @cwd . 606.Pp 607.It Cm @fontdir Ar directoryname 608Specialized version of 609.Cm @dir , 610to handle font directories: create 611.Pa font.alias 612from 613.Pa font.alias-* 614fragments, execute 615.Xr mkfontdir 1 , 616.Xr mkfontscale 1 617and 618.Xr fc-cache 1 619when needed. 620Delete extra files at 621.Xr pkg_delete 1 622time. 623.Pp 624.It Cm @group Ar group 625Set default group ownership for all subsequently extracted files to 626.Ar group . 627Use without an arg to set back to default (extraction) 628group ownership. 629.Pp 630.It Cm @info Ar filename 631Specialized version of 632.Cm @file , 633to handle GNU info files. 634Automatically grab 635.Ar filename Ns -* 636chapter files, run 637.Xr install-info 1 638as needed. 639.Pp 640.It Cm @lib Ar filename 641Specialized version of 642.Cm @file , 643to handle shared libraries. 644Satisfy LIB_DEPENDS and WANTLIB, 645run 646.Xr ldconfig 8 647as needed. 648See 649.Sq VARIABLE SUBSTITUTION AND FRAGMENT INCLUSION 650for some details. 651.Pp 652.It Cm @man Ar filename 653Specialized version of 654.Cm @file , 655to handle manual pages. 656.Pp 657.It Cm @mandir Ar directoryname 658Specialized version of 659.Cm @dir , 660to handle manual directories: instruct user to add/remove the 661directory to 662.Xr man.conf 5 , 663remove 664.Xr apropos 1 665database when needed. 666.Pp 667.It Cm @mode Ar mode 668Set default permission for all subsequently extracted files to 669.Ar mode . 670Format is the same as that used by the 671.Xr chmod 1 672command. 673Use without an arg to set back to default (extraction) permissions. 674.Pp 675.It Cm @newgroup Ar name : Ns Ar gid 676During 677.Xr pkg_add 1 , 678create a new group, using 679.Xr groupadd 8 . 680Happens before file and user creations. 681.Ar gid 682can be prefixed with a 683.Sq !\& 684to ensure group has the correct GID. 685During 686.Xr pkg_delete 1 , 687groups will be deleted if extra clean-up has been requested, and if 688other installed packages don't list the same group. 689.Pp 690.It Xo 691.Cm @newuser 692.Sm off 693.Ar name : 694.Ar uid : 695.Ar group : 696.Ar loginclass : 697.Ar comment : 698.Ar home : 699.Ar shell 700.Sm on 701.Xc 702During 703.Xr pkg_add 1 , 704create a new user. 705Happens before any file creation. 706All fields correspond to 707.Xr useradd 8 708parameters. 709Some fields are optional and can be left empty. 710If the user already exists, no action is taken. 711Individual fields can be prefixed by a 712.Sq !\& 713to make sure an existing 714user matches. 715For instance, the directive 716.Li @newuser foo:!42 717will make sure user foo has UID 42. 718During 719.Xr pkg_delete 1 , 720users will be deleted if extra clean-up has been requested, and if 721other installed packages don't list the same user. 722.Pp 723.It Cm @option Ar name 724Effects vary depending on 725.Ar name . 726These are the user settable options 727.Bl -tag -width indent 728.It Cm always-update 729By default, 730.Xr pkg_add 1 731uses some simplified information to decide whether an installed package 732needs updating. 733With this option, the package will be updated whenever anything changes. 734.Pp 735This is meant to be used by packages containing information relating to the 736whole ports tree, like sqlports, quirks, pkglocatedb. 737.It Cm is-branch 738Annotate the few rare ports where several branches are present in the 739ports tree (such as autoconf), to help 740.Xr pkg_info 1 741produce 742.Ar stem Ns % Ns Ar branch 743annotations when needed. 744.It Cm no-default-conflict 745By default, a package conflicts with other versions of the same package. 746With this option, the older package version will still be noticed, but the 747installation will proceed anyway. 748.El 749.Pp 750.It Cm @owner Ar user 751Set default ownership for all subsequently extracted files to 752.Ar user . 753Use without an arg to set back to default (extraction) 754ownership. 755.Pp 756.It Cm @pkgpath Ar pkgpath 757Declare a secondary 758.Ar pkgpath 759for the package. 760This is used for updates: 761.Nm pkg_add 762.Fl u 763normally checks that the 764.Ar pkgpath 765embedded in the package corresponds to the old package, 766to solve ambiguities when packages with similar names are involved. 767When ports get renamed, or flavors change, extra 768.Cm @pkgpath 769annotations can help 770.Nm pkg_add 771get a sense of continuity. 772Note that these 773.Ar pkgpath 774can take extra optional components, to allow the matching of several 775flavors at once, and are order independent. 776For instance, 777.Bd -literal -offset indent 778@pkgpath some/dir,f1,f2 779.Ed 780.Pp 781and 782.Bd -literal -offset indent 783@pkgpath some/dir,f2,f2,f1 784.Ed 785.Pp 786are equivalent. 787.Bd -literal -offset indent 788@pkgpath some/dir,f1[,f2,f3][,f4] 789.Ed 790.Pp 791will match all pkgpaths to some/dir with flavor f1, and optionally f4, and 792optionally both f2 and f3, e.g., 793.Ar some/dir,f1,f4 , 794.Ar some/dir,f1,f2,f3 , 795.Ar some/dir,f1,f2,f3,f4 , 796.Ar some/dir,f1 797would match, 798but 799.Ar some/dir,f1,f5 , 800.Ar some/dir,f2,f3 , 801.Ar some/dir,f1,f2,f4 802would not. 803.Pp 804Each binary package contains a set of pkgpaths: the primary pkgpath that 805was used to build the package, recorded as 806.Cm @comment Ar pkgpath=some/path , 807and secondary pkgpaths as recorded through 808.Cm @pkgpath . 809.Pp 810In order for two packages to match, their primary pkgpaths must match, or 811a secondary pkgpath must match the other package's primary pkgpath. 812.Pp 813.It Cm @rcscript Ar filename 814Script for the 815.Pa /etc/rc.d 816framework. 817Contrary to 818.Cm @file , 819absolute paths are okay, e.g., 820.Bd -literal -offset indent 821@rcscript ${RCDIR}/ballsd 822.Ed 823.Pp 824In this case, performs an implicit 825.Cm @cwd 826to 827.Pa ${RCDIR} . 828.Pp 829.It Cm @sample Ar filename 830Last preceding 831.Cm @file 832item is a sample configuration file, to be copied to 833.Ar filename 834at 835.Xr pkg_add 1 836time and to be removed at 837.Xr pkg_delete 1 838time. 839During installation, existing configuration files are untouched. 840During deinstallation, configuration files are only removed if unchanged. 841.Ar filename 842can be an absolute path. 843If 844.Ar filename 845ends with a slash, 846it refers to a configuration directory instead. 847.Pp 848.It Cm @shell Ar filename 849Specialized version of 850.Cm @file , 851to handle shells. 852See 853.Xr shells 5 . 854.Pp 855.It Cm @so Ar filename 856Describe the file as an 857.Ox 858shared object. 859.Pp 860.It Cm @static-lib Ar filename 861Describe the file as a 862.Ox 863static library. 864.Pp 865.It Cm @unexec Ar command 866Execute 867.Ar command 868during 869.Xr pkg_delete 1 . 870.Ev PATH 871and expansion of special 872.Cm \&% 873sequences are the same as for 874.Cm @exec . 875Note that 876.Cm @unexec 877commands are executed relative to their location in the packing-list, 878so they cannot rely on any data that has already been deleted, 879thus they should occur before the files they need to function. 880Some special elements, such as new users and new groups, are always 881deleted last, so that 882.Cm @unexec 883can rely on them. 884.Pp 885.It Cm @tag Ar name Op Ar parameter 886Reference a tag of given 887.Ar name . 888The corresponding 889.Cm @define-tag 890definition must be accessible through the dependency tree. 891.Ar parameter 892is amenable to the same substitutions as 893.Cm @exec . 894.Pp 895.It Cm @unexec-always Ar command 896Synonym of 897.Cm @unexec . 898.Pp 899.It Cm @unexec-delete Ar command 900Similar to 901.Cm @unexec , 902except it only gets executed during true deletions 903and not while removing an old package during updates. 904.Pp 905.It Cm @unexec-update Ar command 906Similar to 907.Cm @unexec , 908except it only gets executed while removing an old package during updates, 909and not during true deletions. 910.El 911.Pp 912The 913.Cm @bin , 914.Cm @lib , 915.Cm @so 916and 917.Cm @static-lib 918annotations are used by the debug packages infrastructure to figure out 919which files may contain debug information. 920.Pp 921Some of these annotations define information that are local to each port 922but global to the package ecosystem in general, and thus make it into 923the package locate database by default 924.Po 925for instance: 926.Cm @define-tag , 927.Cm @newuser 928and 929.Cm @newgroup 930.Pc . 931See 932.Xr pkg_mklocatedb 1 933for details. 934.Pp 935See 936.Xr package 5 937for other internal annotations that are automatically added by the 938package tools. 939.Sh VARIABLE SUBSTITUTION AND FRAGMENT INCLUSION 940In packing-lists, installation, deinstallation and requirement scripts, 941description and message files, 942constructs like 943.Li ${VAR} 944will be replaced with the variable value, according to 945.Fl D Ar name Ns = Ns Ar value 946options. 947.Pp 948In particular, shared library versions should never be mentioned explicitly 949in a packing-list. 950Shared library 951.Sq foo 952will take its version number from 953.Ev LIBfoo_VERSION . 954The ports framework normally takes care of all details, see 955.Ev SHARED_LIBS 956in 957.Xr bsd.port.mk 5 . 958.Pp 959Constructs like 960.Li %%VAR%% 961and 962.Li !%%VAR%% 963trigger fragment inclusion. 964If such a line is encountered in a packing-list, the corresponding variable 965must be defined to 0 or 1. 966If the variable's value is 1, 967.Li %%VAR%% 968will be replaced by the corresponding positive fragment, and 969.Li !%%VAR%% 970will be ignored. 971If the variable's value is 0, 972.Li %%VAR%% 973will be ignored, and 974.Li !%%VAR%% 975will be replaced by the corresponding positive fragment. 976.Pp 977A fragment is an auxiliary packing-list file, whose name is derived from the 978current packing-list, and the variable name 979.Va VAR 980triggering the inclusion: 981.Pa pkg/PLIST 982yields a positive fragment 983.Pa pkg/PFRAG.VAR 984and a negative fragment 985.Pa pkg/PFRAG.no-VAR , 986.Pa pkg/PLIST-FOO 987yields a positive fragment 988.Pa pkg/PFRAG.VAR-foo 989and a negative fragment 990.Pa pkg/PFRAG.no-VAR-foo . 991.Pp 992Fragments can be included inside fragments, so that 993.Li %%VAR2%% 994inside 995.Pa pkg/PFRAG.VAR 996triggers the inclusion of 997.Pa pkg/PFRAG.VAR2-VAR 998and 999.Li !%%VAR2%% 1000triggers the inclusion of 1001.Pa pkg/PFRAG.no-VAR2-VAR . 1002.Pp 1003If a positive or a negative fragment file does not exist, the corresponding 1004inclusion will be ignored. 1005However, if both the positive and negative fragment files do not exist, 1006.Nm 1007will error out, to make it easier to spot fragment names errors. 1008.Sh SEE ALSO 1009.Xr pkg_add 1 , 1010.Xr pkg_delete 1 , 1011.Xr pkg_info 1 , 1012.Xr pkg_sign 1 , 1013.Xr tar 1 , 1014.Xr bsd.port.mk 5 , 1015.Xr package 5 , 1016.Xr packages-specs 7 , 1017.Xr pkgpath 7 , 1018.Xr ports 7 1019.Sh HISTORY 1020The 1021.Nm 1022command first appeared in 1023.Fx . 1024.Sh AUTHORS 1025.Bl -tag -width indent -compact 1026.It An Jordan Hubbard 1027initial design 1028.It An Marc Espie 1029complete rewrite. 1030.El 1031