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  .Dd December 12, 2025
 15  .Dt PKG-LUA-SCRIPT 5
 16  .Os
 17  .Sh NAME
 18  .Nm "lua scripts"
 19  .Nd lua scripts that are run by
 20  .Xr pkg 8
 21  .Sh DESCRIPTION
 22  .Xr pkg 8
 23  run scripts at given phases of the process it is running.
 24  .Pp
 25  The phases are the following:
 26  .Bl -tag -width Ds
 27  .It Cm pre-install :
 28  run before installing the files on the system.
 29  .It Cm post-install :
 30  run after installing the files on the system.
 31  .It Cm pre-deinstall :
 32  run before removing the files on the system.
 33  .It Cm post-deinstall :
 34  run after removing the files on the system.
 35  .El
 36  .Pp
 37  A package can contain multiple scripts per phase, they will all be run inside
 38  their own lua VM.
 39  .Pp
 40  In the particular case of an upgrade the scripts are run in the following order:
 41  .Bl -enum -compact
 42  .It
 43  new pre-install
 44  .It
 45  old pre-deinstall
 46  .It
 47  replace binaries
 48  .It
 49  new post-install
 50  .El
 51  .Pp
 52  Lua scripts are always run after shell scripts (of the same phase).
 53  .Sh API
 54  All the regular lua APIs are available with the exception of the following changes:
 55  .Bl -tag -width Ds
 56  .It Fn io.open
 57  has been modified to only open files relatively to the rootdir if specified by
 58  the
 59  .Ar -r
 60  argument passed to
 61  .Xr pkg 8 .
 62  .It Fn os.remove
 63  has been modified to only remove files relatively to the rootdir if specified by
 64  the
 65  .Ar -r
 66  argument passed to
 67  .Xr pkg 8 .
 68  .It Fn os.rename
 69  has been modified to only rename files relatively to the rootdir if specified by
 70  the
 71  .Ar -r
 72  argument passed to
 73  .Xr pkg 8 .
 74  .It Fn os.execute
 75  has been disabled.
 76  .It Fn os.exit
 77  has been disabled.
 78  .El
 79  .Pp
 80  The following variables are available defined to any lua scripts:
 81  .Bl -tag -width Ds
 82  .It Va pkg_name
 83  name of the package.
 84  .It Va pkg_prefix
 85  .Va PREFIX
 86  defined within the package at build time.
 87  .It Va pkg_rootdir
 88  represents the root directory where the package will be installed as specified
 89  by the
 90  .Fl r
 91  arguments passed to
 92  .Xr pkg 8 .
 93  .It Va pkg_metalog
 94  String containing the path to a
 95  .Xr mtree 5
 96  METALOG file in which package file metadata (e.g., ownership, mode) should be
 97  recorded.
 98  This is typically used when installing packages as a non-root user.
 99  If no METALOG is configured, this variable is unset and is equal to nil.
100  .It Va pkg_upgrade
101  Boolean to inform the scripts that it is running or not in the context of an upgrade
102  .It Va arg
103  When the first line of a Lua script starts with
104  .Dq -- args:\&
105  followed by a space-separated list of tokens, those tokens are parsed
106  and made available in the global
107  .Va arg
108  table.
109  This allows passing arguments to Lua scripts, should not be used by regular scripts.
110  This is used internally for deferred triggers.
111  .El
112  .Pp
113  The following functions have been added:
114  .Bl -tag -width Ds
115  .It Ft out Fn pkg.prefixed_path "in"
116  prepend
117  .Va pkg_prefix
118  to
119  .Ar in
120  if needed and returns it as
121  .Ft out .
122  .It Fn pkg.print_msg "msg"
123  send messages to the user that will be shown at the end of the
124  .Xr pkg 8
125  process.
126  .It Fn pkg.filecmp "file1" "file2"
127  Compare 2 files, return
128  .Va 0
129  if the files are identical,
130  .Va 1
131  if the files are different and
132  .Va >1
133  if an error occurred
134  .It Fn pkg.metalog_copy "source" "destination"
135  Will create an entry in the
136  .Qq metalog
137  if one has been defined which will clone the
138  metadata from the
139  .Va source
140  and use it for a new entry for
141  .Va destination
142  path.
143  .It Fn pkg.copy "source" "destination"
144  Copy a file preserving its attributes. return
145  .Va -1
146  if an error occurred
147  .It Ft st Fn pkg.stat "file"
148  return an object table
149  .Ft st
150  with the following fields:
151  .Va type ,
152  .Va size ,
153  .Va uid ,
154  .Va gid
155  .It Fn pkg.symlink "source" "destination"
156  Create a symbolic link
157  .Va destination
158  pointing at
159  .Va source
160  .It Fn pkg.exec arguments
161  Will execute the command
162  .Ar arguments
163  expected in the following form:
164  .So
165  .Bro command, arg1, arg2, arg3, ...
166  .Brc
167  .Sc
168  .It Ft res Fn pkg.readdir path
169  Will return an
170  .Va ipair
171  with the list of elements contained in the directory
172  the special directory
173  .Va So .
174  .Sc
175  and
176  .Va Sq ..
177  are be filtered out.
178  .El
179  .Sh SEE ALSO
180  .Xr pkg_create 3 ,
181  .Xr pkg_printf 3 ,
182  .Xr pkg_repo_create 3 ,
183  .Xr pkg_repos 3 ,
184  .Xr pkg-keywords 5 ,
185  .Xr pkg-repository 5 ,
186  .Xr pkg-script 5 ,
187  .Xr pkg-triggers 5 ,
188  .Xr pkg.conf 5 ,
189  .Xr pkg 8 ,
190  .Xr pkg-add 8 ,
191  .Xr pkg-alias 8 ,
192  .Xr pkg-annotate 8 ,
193  .Xr pkg-audit 8 ,
194  .Xr pkg-autoremove 8 ,
195  .Xr pkg-check 8 ,
196  .Xr pkg-clean 8 ,
197  .Xr pkg-config 8 ,
198  .Xr pkg-create 8 ,
199  .Xr pkg-delete 8 ,
200  .Xr pkg-fetch 8 ,
201  .Xr pkg-help 8 ,
202  .Xr pkg-info 8 ,
203  .Xr pkg-install 8 ,
204  .Xr pkg-key 8 ,
205  .Xr pkg-lock 8 ,
206  .Xr pkg-plugins 8 ,
207  .Xr pkg-query 8 ,
208  .Xr pkg-register 8 ,
209  .Xr pkg-repo 8 ,
210  .Xr pkg-repositories 8 ,
211  .Xr pkg-rquery 8 ,
212  .Xr pkg-search 8 ,
213  .Xr pkg-set 8 ,
214  .Xr pkg-shell 8 ,
215  .Xr pkg-shlib 8 ,
216  .Xr pkg-ssh 8 ,
217  .Xr pkg-stats 8 ,
218  .Xr pkg-triggers 8 ,
219  .Xr pkg-unregister 8 ,
220  .Xr pkg-update 8 ,
221  .Xr pkg-updating 8 ,
222  .Xr pkg-upgrade 8 ,
223  .Xr pkg-version 8 ,
224  .Xr pkg-which 8