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