1  .Dd December 12, 2025
  2  .Dt PKG_CREATE 3
  3  .Os
  4  .Sh NAME
  5  .Nm pkg_create , pkg_create_i ,
  6  .Nm pkg_create_new , pkg_create_free ,
  7  .Nm pkg_create_set_format , pkg_create_set_overwrite ,
  8  .Nm pkg_create_set_compression_level , pkg_create_set_rootdir ,
  9  .Nm pkg_create_set_output_dir , pkg_create_set_timestamp ,
 10  .Nm pkg_create_set_compression_threads
 11  .Nd create packages
 12  .Sh LIBRARY
 13  .Lb libpkg
 14  .Sh SYNOPSIS
 15  .In pkg.h
 16  .Ft struct pkg_create *
 17  .Fn pkg_create_new
 18  .Ft void
 19  .Fn pkg_create_free "struct pkg_create *"
 20  .Ft bool
 21  .Fn pkg_create_set_format "struct pkg_create *" "const char *"
 22  .Ft void
 23  .Fn pkg_create_set_compression_level "struct pkg_create *" "int"
 24  .Ft void
 25  .Fn pkg_create_set_compression_threads "struct pkg_create *" "int"
 26  .Ft void
 27  .Fn pkg_create_set_overwrite "struct pkg_create *" "bool"
 28  .Ft void
 29  .Fn pkg_create_set_rootdir "struct pkg_create *" "const char *"
 30  .Ft void
 31  .Fn pkg_create_set_output_dir "struct pkg_create *" "const char *"
 32  .Ft void
 33  .Fn pkg_create_set_timestamp "struct pkg_create *" "time_t"
 34  .Ft int
 35  .Fn pkg_create "struct pkg_create *" "const char *" "const char *" "bool"
 36  .Ft int
 37  .Fn pkg_create_i "struct pkg_create *" "struct pkg *" "bool"
 38  .Sh DESCRIPTION
 39  .Fn pkg_create_new
 40  Allocates a new
 41  .Ft struct pkg_create *
 42  which should be freed by the caller using
 43  .Fn pkg_create_free .
 44  .Pp
 45  .Fn pkg_create_set_format
 46  will define the compression format to use.
 47  By default
 48  .Qq txz
 49  except if specified otherwise in
 50  .Xr pkg.conf 5 .
 51  It returns
 52  .Va false
 53  if the compression format is unknown and will fall back to the default format.
 54  .Pp
 55  .Fn pkg_create_set_compression_level
 56  takes an
 57  .Ft int
 58  argument which represents the expected compression level.
 59  3 special values are accepted:
 60  .Bl -tag -width indentation
 61  .It Va INT_MIN
 62  Set the fastest compression format value
 63  .It Va 0
 64  Set the default (as specified in libarchive)
 65  .It Va INT_MAX
 66  Set the best compression ratio
 67  .El
 68  .Pp
 69  .Fn pkg_create_set_compression_threads
 70  takes an
 71  .Ft int
 72  argument which represents the expected number of threads used during
 73  compression.
 74  .Pp
 75  .Fn pkg_create_set_overwrite
 76  Accepts a boolean to define the default behaviour when creating a package if
 77  a local file already exists.
 78  The default behaviour is to overwrite.
 79  .Pp
 80  .Fn pkg_create_set_rootdir
 81  Tells the program where to find the root directory used for packaging (this directory
 82  is also known as the staging area).
 83  If none is provided pkg will consider
 84  .Sq Va / .
 85  .Pp
 86  .Fn pkg_create_set_output_dir
 87  Tells the program where to create the new packages.
 88  By default it will consider the current directory of the running program.
 89  .Pp
 90  .Fn pkg_create_set_timestamp
 91  Define the timestamp to use as the creation and modification time for the files to
 92  be packaged.
 93  By default it will use the timestamp of the files on the filesystem.
 94  .Pp
 95  .Fn pkg_create
 96  create a package from scratch using the
 97  .Va metadata
 98  and
 99  .Va plist
100  as input.
101  The
102  .Va metadata
103  can be either directly a UCL manifest, or a directory containing multiple files:
104  .Bl -tag -width +MANIFEST
105  .It +MANIFEST
106  The UCL manifest
107  .It +DESC
108  A textual description (optional)
109  .It shell scripts (optional):
110  .Bl -tag -width pkg-post-deinstall
111  .It +INSTALL
112  Shell script that will be run during both post and pre install (DEPRECATED)
113  .It +PRE_INSTALL
114  Shell script that will be run during pre install phase
115  .It +POST_INSTALL
116  Shell script that will be run during post install phase
117  .It +DEINSTALL
118  Shell script that will be run during both post and pre deinstall (DEPRECATED)
119  .It +PRE_DEINSTALL
120  Shell script that will be run during pre deinstall phase
121  .It +POST_DEINSTALL
122  Shell script that will be run during post deinstall phase
123  .It pkg-install
124  Shell script that will be run during both post and pre install (DEPRECATED)
125  .It pkg-pre-install
126  Shell script that will be run during pre install phase
127  .It pkg-post-install
128  Shell script that will be run during post install phase
129  .It pkg-deinstall
130  Shell script that will be run during both post and pre deinstall (DEPRECATED)
131  .It pkg-pre-deinstall
132  Shell script that will be run during pre deinstall phase
133  .It pkg-post-deinstall
134  Shell script that will be run during post deinstall phase
135  .El
136  .It lua scripts (optional):
137  .Bl -tag -width pkg-post-deinstall.lua
138  .It pkg-pre-install.lua
139  Lua script that will be run during pre install phase
140  .It pkg-post-install.lua
141  Lua script that will be run during post install phase
142  .It pkg-pre-deinstall.lua
143  Lua script that will be run during pre deinstall phase
144  .It pkg-post-deinstall.lua
145  Lua script that will be run during post deinstall phase
146  .El
147  .El
148  .Pp
149  .Fn pkg_create_i
150  create a package for the provided installed
151  .Ar pkg .
152  If
153  .Ar hash
154  is set to
155  .Va true
156  then the file name will be in the form:
157  <pkgname>-<pkgversion>-<shorthash>.<extention>
158  instead of
159  <pkgname>-<pkgversion>.<extension>.