xref: /openbsd-src/usr.sbin/pkg_add/pkg_create.1 (revision a56012defa044d9777450baea50ab6f3745ec883)
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