1  .\"
  2  .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3  .\" of non-core utilities.
  4  .\"
  5  .\" Redistribution and use in source and binary forms, with or without
  6  .\" modification, are permitted provided that the following conditions
  7  .\" are met:
  8  .\" 1. Redistributions of source code must retain the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer.
 10  .\" 2. Redistributions in binary form must reproduce the above copyright
 11  .\"    notice, this list of conditions and the following disclaimer in the
 12  .\"    documentation and/or other materials provided with the distribution.
 13  .\"
 14  .\"
 15  .\"     @(#)pkg.8
 16  .\"
 17  .Dd December 13, 2025
 18  .Dt PKG-CREATE 8
 19  .Os
 20  .\" ---------------------------------------------------------------------------
 21  .Sh NAME
 22  .Nm "pkg create"
 23  .Nd a utility for creating software package distributions
 24  .\" ---------------------------------------------------------------------------
 25  .Sh SYNOPSIS
 26  .Nm
 27  .Op Fl enqv
 28  .Op Fl f Ar format
 29  .Op Fl l Ar level
 30  .Op Fl o Ar outdir
 31  .Op Fl p Ar plist
 32  .Op Fl r Ar rootdir
 33  .Op Fl t Ar timestamp
 34  .Op Fl T Ar threads
 35  .Fl m Ar metadatadir
 36  .Nm
 37  .Op Fl enqv
 38  .Op Fl f Ar format
 39  .Op Fl l Ar level
 40  .Op Fl o Ar outdir
 41  .Op Fl r Ar rootdir
 42  .Op Fl t Ar timestamp
 43  .Op Fl T Ar threads
 44  .Fl M Ar manifest
 45  .Nm
 46  .Op Fl egnqvx
 47  .Op Fl f Ar format
 48  .Op Fl l Ar level
 49  .Op Fl o Ar outdir
 50  .Op Fl r Ar rootdir
 51  .Op Fl t Ar timestamp
 52  .Op Fl T Ar threads
 53  .Ar pkg-name ...
 54  .Nm
 55  .Op Fl enqv
 56  .Op Fl f Ar format
 57  .Op Fl l Ar level
 58  .Op Fl o Ar outdir
 59  .Op Fl r Ar rootdir
 60  .Op Fl t Ar timestamp
 61  .Op Fl T Ar threads
 62  .Fl a
 63  .\" ---------------------------------------------------------------------------
 64  .Pp
 65  .Nm
 66  .Op Cm --expand-manifest
 67  .Op Cm --no-clobber
 68  .Op Cm --quiet
 69  .Op Cm --verbose
 70  .Op Cm --format Ar format
 71  .Op Cm --level Ar level
 72  .Op Cm --out-dir Ar outdir
 73  .Op Cm --plist Ar plist
 74  .Op Cm --root-dir Ar rootdir
 75  .Cm --metadata Ar metadatadir
 76  .Nm
 77  .Op Cm --expand-manifest
 78  .Op Cm --no-clobber
 79  .Op Cm --quiet
 80  .Op Cm --verbose
 81  .Op Cm --format Ar format
 82  .Op Cm --level Ar level
 83  .Op Cm --out-dir Ar outdir
 84  .Op Cm --root-dir Ar rootdir
 85  .Cm --manifest Ar manifest
 86  .Nm
 87  .Op Cm --expand-manifest
 88  .Op Cm --{glob,no-clobber,regex}
 89  .Op Cm --quiet
 90  .Op Cm --verbose
 91  .Op Cm --format Ar format
 92  .Op Cm --level Ar level
 93  .Op Cm --out-dir Ar outdir
 94  .Op Cm --root-dir Ar rootdir
 95  .Ar pkg-name ...
 96  .Nm
 97  .Op Cm --expand-manifest
 98  .Op Cm --no-clobber
 99  .Op Cm --quiet
100  .Op Cm --verbose
101  .Op Cm --format Ar format
102  .Op Cm --level Ar level
103  .Op Cm --out-dir Ar outdir
104  .Op Cm --root-dir Ar rootdir
105  .Cm --all
106  .\" ---------------------------------------------------------------------------
107  .Sh DESCRIPTION
108  .Nm
109  is used to create packages from binaries or other files installed on
110  your computer.
111  Package tarballs can be created from the files of a previously installed
112  package using metadata from the local package database.
113  Any number of packages may be created in one invocation of this style.
114  .Pp
115  Alternatively, a single package can be created from an arbitrary
116  selection of files on your system, but this requires a
117  .Ar metadatadir
118  and optionally
119  .Ar plist
120  to be supplied.
121  The package name will be derived from the
122  .Pa +MANIFEST
123  file which must be contained within the
124  .Ar metadatadir ,
125  or passed as the argument to
126  .Fl M .
127  .Pp
128  Packages thus created can be distributed and subsequently installed on
129  other machines using the
130  .Cm pkg add
131  command.
132  .\" ---------------------------------------------------------------------------
133  .Sh OPTIONS
134  The following options are supported by
135  .Nm :
136  .Bl -tag -width ".Fl m Ar metadatadir"
137  .It Fl M Ar manifest , Cm --manifest Ar manifest
138  Read all of the package metadata from the
139  .Ar manifest
140  file.
141  This is exactly the same format as
142  .Pa +MANIFEST
143  mentioned above, but any file name can be used, and no
144  other file will be used to read package metadata from.
145  If specified, only a single package will be created.
146  This option is incompatible with the
147  .Fl m , a , g
148  or
149  .Fl x
150  options.
151  .It Fl T Ar threads
152  .Ar threads
153  represents the number of threads to use during the compression of the archive.
154  Set it to
155  .Qq 0
156  or
157  .Qq auto
158  to have
159  .Nm
160  detect the number of CPUs and use one thread per CPU.
161  .It Fl a , Cm --all
162  Create package tarballs from all packages installed on your system.
163  This option is incompatible with the
164  .Fl g , x
165  or
166  .Fl m Ar metadatadir
167  options.
168  .It Fl e , Cm --expand-manifest
169  The manifest contained in pkg will be expanded to readable UCL format.
170  .It Fl f Ar format , Cm --format Ar format
171  Set
172  .Ar format
173  as the package compression format.
174  It can be one of
175  .Ar tzst, txz , tbz , tgz
176  or
177  .Ar tar
178  which are currently the only supported formats.
179  If an invalid format, or no format, is specified then
180  .Ar tzst
181  is assumed.
182  .Po The
183  .Pa .pkg
184  extension is used for all compression types.
185  .Pc
186  .It Fl h , Cm --hash
187  Append a short hash of the package contents to the package filename.
188  This can be used in combination with
189  .Fl s
190  to create symlinks between the hashed and regular filenames.
191  .It Fl g , Cm --glob
192  Interpret
193  .Ar pkg-name
194  as a shell glob pattern and create package only for installed binaries whose
195  name match this pattern.
196  This option is incompatible with the
197  .Fl a , x
198  or
199  .Fl m Ar metadatadir
200  options.
201  .It Fl l Ar level , Cm --level Ar level
202  Set the compression
203  .Ar level
204  for created packages.
205  It can be any valid numeric compression level you might specify to the
206  underlying compression
207  .Ar format .
208  Additionally,
209  .Ar level
210  may be one of the special words
211  .Dv Dq fast
212  or
213  .Dv Dq best .
214  If
215  .Ar level
216  is one of these special words, the fastest or slowest compression level,
217  respectively, for the specified compression format, is used.
218  .It Fl m Ar metadatadir , Cm --metadata Ar metadatadir
219  Specify the directory containing the package manifest,
220  .Pa +MANIFEST
221  and optionally two other files; one containing a message to be
222  displayed on package installation,
223  .Pa +DISPLAY ,
224  and another containing the description for the package,
225  .Pa +DESC .
226  If specified, only a single package will be created.
227  .Pa +DISPLAY
228  and
229  .Pa +DESC
230  are not required; the
231  .Pa +MANIFEST
232  file can contain all the required information needed to build a
233  package.
234  This option is incompatible with the
235  .Fl M , a , g
236  or
237  .Fl x
238  options.
239  .It Fl n , Cm --no-clobber
240  Do not overwrite already existing packages.
241  .It Fl o Ar outdir , Cm --out-dir Ar outdir
242  Set
243  .Ar outdir
244  as the output directory.
245  If this option is not given, all created packages will
246  be saved in the current directory.
247  .It Fl p Ar plist , Cm --plist Ar plist
248  Specify some package metadata using the legacy plist format from
249  .Xr pkg_add 1 ,
250  commonly found in
251  .Pa pkg-plist
252  files in the ports tree.
253  Metadata from the
254  .Ar plist
255  file, if specified, will take precedence over any equivalents from
256  the
257  .Ar metadatadir .
258  Only has any effect when used with
259  .Ar metadatadir .
260  See
261  .Sx "PLIST FORMAT"
262  for details.
263  .It Fl q , Cm --quiet
264  Force quiet output.
265  This is the default, unless
266  .Cm PKG_CREATE_VERBOSE
267  is set to
268  .Ar yes
269  in
270  .Pa pkg.conf .
271  .It Fl r Ar rootdir , Cm --root-dir Ar rootdir
272  .Ar rootdir
273  specifies the top-level directory to be treated as the root of the
274  filesystem hierarchy containing the package files.
275  File paths in generated packages will be relative to
276  .Ar rootdir .
277  This allows a package to be generated from content offset from its
278  intended final location, which allows a package building without
279  disturbing similar content already on the system.
280  If unspecified, the default is effectively
281  .Pa / ,
282  the actual root directory.
283  .It Fl t Ar timestamp , Cm --timestamp
284  Set the timestamp of the files within the archive.
285  .It Fl v , Cm --verbose
286  Force verbose output, the opposite of
287  .Cm --quiet .
288  .It Fl x , Cm --regex
289  Like
290  .Fl g ,
291  but interpret
292  .Ar pkg-name
293  as a regular expression using the "modern" or "extended" syntax described in
294  .Xr re_format 7 .
295  This option is incompatible with the
296  .Fl a , g
297  or
298  .Fl m Ar metadatadir
299  options.
300  .El
301  .\" ---------------------------------------------------------------------------
302  .Sh MANIFEST FILE DETAILS
303  .Bl -tag -width ".Cm www"
304  .It Cm name Ar pkg-name
305  This entry sets the package's name to
306  .Ar pkg-name . \" TODO: Find out why there is a space after the ``.''
307  Among other things, this name is used - with the version and the origin of the
308  concerned package - to identify a dependency.
309  .It Cm version Ar pkg-version
310  This entry sets the package's version to
311  .Ar pkg-version .
312  .It Cm origin Ar pkg-origin
313  This entry sets the package's origin to
314  .Ar pkg-origin .
315  This is a string of the form
316  .Pa category/port-dir
317  which designates the port this package was built from.
318  .It Cm comment Ar comment-string
319  .Ar comment-string
320  is a one-line description of this package.
321  It is the equivalent of the
322  .Dv COMMENT
323  variable for a port, not a way to put comments in a
324  .Pa +MANIFEST
325  file.
326  .It Cm desc Ar description
327  .Ar description
328  is a longer description of the package.
329  It is the equivalent of the
330  .Pa pkg-descr
331  file for a port.
332  It may be one to a few paragraphs.
333  For example:
334  .Bd -literal -offset indent
335  desc = <<EOD
336     This is a longer description of the package.
337     It can span multiple lines.
338  
339     It can also span multiple paragraphs.
340  EOD
341  .Ed
342  .It Cm arch Ar cpu-type
343  The architecture of the machine the package was built on.
344  .Ar cpu-type
345  takes values like x86, amd64...
346  .It Cm www Ar url
347  The software's official website.
348  .It Cm maintainer Ar mail-address
349  The maintainer's mail address.
350  .It Cm prefix Ar path-prefix
351  The path where the files contained in this package are installed
352  .Pq usually Pa /usr/local .
353  .It Cm flatsize Ar size
354  The size that the files contained in this package will occupy on your system
355  once uncompressed.
356  This value does not take into account files stored in the
357  package database.
358  .It Cm deps Ar dep-name dep-origin dep-version
359  Associative array of package dependencies, keyed on
360  .Ar dep-name
361  and with values
362  .Cm version Ar dep-version
363  and
364  .Cm origin Ar dep-origin .
365  For example:
366  .Bd -literal -offset indent
367  "deps" : {
368     "pstree" : {
369        "version" : "2.36",
370        "origin" : "sysutils/pstree"
371     },
372     "cdiff" : {
373        "version" : "0.9.6.20140711,1",
374        "origin" : "textproc/cdiff"
375     },
376  },
377  .Ed
378  .It Cm conflict Ar pkg-glob
379  Flag this package as incompatible with the one designated by
380  .Ar pkg-glob .
381  Conflicting packages cannot be installed on the same system as they may contain
382  references to the same files.
383  .It Cm option Ar option-name option-value
384  Set the option
385  .Ar option-name
386  to the value
387  .Ar option-value .
388  .It Cm file Ar sha256-hash path
389  .Cm file
390  entries list files included in the package.
391  If the file is a regular one, such
392  an entry contains its sha256 digest along with its path.
393  If a packaged file is
394  a link, you must use this entry's other form, as described below.
395  .It Cm file Ar - path
396  Same as above but for file links.
397  The sha256 hash is replaced with a
398  .Ar -
399  (dash).
400  .It Cm dir Ar path
401  Mimics the
402  .Cm file
403  entry but for directories.
404  .El
405  .Sh PLIST FORMAT
406  The following describes the plist format:
407  .Pp
408  The plist is a sequential list of lines which can have keywords prepended.
409  A keyword starts with an
410  .Sq @ .
411  Lines not starting with a keyword are considered as paths to a file.
412  If started with a
413  .Sq /
414  then it is considered an absolute path.
415  Otherwise the file is considered as relative to
416  .Ev PREFIX .
417  .Pp
418  Keyword lines are formed as follows:
419  .Ar @keyword
420  .Ar line
421  .Pp
422  Available keywords are the following:
423  .Pp
424  .Bl -tag -width indent -compact
425  .It Cm @cwd Op Ar directory
426  Set the internal directory pointer to point to
427  .Ar directory .
428  All subsequent filenames will be assumed relative to this directory.
429  .It Cm @mode Ar mode
430  Set default permission for all subsequently extracted files to
431  .Ar mode .
432  Format is the same as that used by the
433  .Cm chmod
434  command.
435  Use without an arg to set back to default (mode of the file while being packed)
436  permissions.
437  .It Cm @owner Ar user
438  Set default ownership for all subsequent files to
439  .Ar user .
440  Use without an arg to set back to default (root)
441  ownership.
442  .It Cm @group Ar group
443  Set default group ownership for all subsequent files to
444  .Ar group .
445  Use without an arg to set back to default (wheel)
446  group ownership.
447  .It Cm @comment Ar string
448  The line will be ignored when packing.
449  .It Cm @dir Ar name
450  Declare directory
451  .Pa name
452  to be deleted at deinstall time.
453  By default, most directories created by a package installation are
454  deleted automatically when the package is deinstalled, so this directive is
455  only needed for empty directories or directories outside of
456  .Ev PREFIX .
457  These directives should appear at the end of the package list.
458  If the directory is not empty a warning will be printed, and the
459  directory will not be removed.
460  (Subdirectories should be listed before parent directories.)
461  .It Cm @include Ar name
462  Include the
463  .Pa name
464  plist file to the plist currently being parsed. the
465  .Pa name
466  will be opened relatively to the main plist file being parsed.
467  Note: only one level of
468  .Cm @include
469  is allowed
470  .El
471  .Sh ESCAPE SEQUENCES
472  .\" ---------------------------------------------------------------------------
473  .Sh ENVIRONMENT
474  The following environment variables affect the execution of
475  .Nm .
476  See
477  .Xr pkg.conf 5
478  for further description.
479  .Bl -tag -width ".Ev NO_DESCRIPTIONS"
480  .It Ev PKG_DBDIR
481  .It Ev PLIST_KEYWORDS_DIR
482  .It Ev PORTSDIR
483  .It Ev SOURCE_DATE_EPOCH
484  Set the timestamp for every single file in the archive to the one
485  specified in the environment variable
486  .El
487  .\" ---------------------------------------------------------------------------
488  .Sh FILES
489  See
490  .Xr pkg.conf 5 .
491  .\" ---------------------------------------------------------------------------
492  .Sh EXAMPLES
493  Create package files for installed packages:
494  .Dl % pkg create -a -o /usr/ports/packages/All
495  .Pp
496  Create package file for pkg:
497  .Dl % pkg create -o /usr/ports/packages/All pkg
498  .\" ---------------------------------------------------------------------------
499  .Sh SEE ALSO
500  .Xr pkg_create 3 ,
501  .Xr pkg_printf 3 ,
502  .Xr pkg_repo_create 3 ,
503  .Xr pkg_repos 3 ,
504  .Xr pkg-keywords 5 ,
505  .Xr pkg-lua-script 5 ,
506  .Xr pkg-repository 5 ,
507  .Xr pkg-script 5 ,
508  .Xr pkg-triggers 5 ,
509  .Xr pkg.conf 5 ,
510  .Xr pkg 8 ,
511  .Xr pkg-add 8 ,
512  .Xr pkg-alias 8 ,
513  .Xr pkg-annotate 8 ,
514  .Xr pkg-audit 8 ,
515  .Xr pkg-autoremove 8 ,
516  .Xr pkg-check 8 ,
517  .Xr pkg-clean 8 ,
518  .Xr pkg-config 8 ,
519  .Xr pkg-delete 8 ,
520  .Xr pkg-fetch 8 ,
521  .Xr pkg-help 8 ,
522  .Xr pkg-info 8 ,
523  .Xr pkg-install 8 ,
524  .Xr pkg-key 8 ,
525  .Xr pkg-lock 8 ,
526  .Xr pkg-plugins 8 ,
527  .Xr pkg-query 8 ,
528  .Xr pkg-register 8 ,
529  .Xr pkg-repo 8 ,
530  .Xr pkg-repositories 8 ,
531  .Xr pkg-rquery 8 ,
532  .Xr pkg-search 8 ,
533  .Xr pkg-set 8 ,
534  .Xr pkg-shell 8 ,
535  .Xr pkg-shlib 8 ,
536  .Xr pkg-ssh 8 ,
537  .Xr pkg-stats 8 ,
538  .Xr pkg-triggers 8 ,
539  .Xr pkg-unregister 8 ,
540  .Xr pkg-update 8 ,
541  .Xr pkg-updating 8 ,
542  .Xr pkg-upgrade 8 ,
543  .Xr pkg-version 8 ,
544  .Xr pkg-which 8