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