| blob | 1463152c5e414392d194800369e5a0e80ddc01ee |
1 .\" $NetBSD: pkg_create.1,v 1.2 2015/10/10 10:08:12 mbalmer Exp $
2 .\"
3 .\" FreeBSD install - a package for the installation and maintenance
4 .\" of non-core utilities.
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 .\" @(#)pkg_create.1
19 .\" from FreeBSD Id: pkg_create.1,v 1.19 1997/05/02 22:00:05 max Exp
20 .\"
21 .\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
22 .\" added dependency tracking, etc.
23 .\"
24 .\" [jkh] Took John's changes back and made some additional extensions for
25 .\" better integration with FreeBSD's new ports collection.
26 .\"
27 .Dd October 10, 2015
28 .Dt PKG_CREATE 1
29 .Os
30 .Sh NAME
31 .Nm pkg_create
32 .Nd a utility for creating software package distributions
33 .Sh SYNOPSIS
34 .Nm
35 .Op Fl ElOUVv
36 .Bk -words
37 .Op Fl B Ar build-info-file
38 .Ek
39 .Bk -words
40 .Op Fl b Ar build-version-file
41 .Ek
42 .Bk -words
43 .Op Fl C Ar cpkgs
44 .Ek
45 .Bk -words
46 .Op Fl D Ar displayfile
47 .Ek
48 .Bk -words
49 .Op Fl F Ar compression
50 .Ek
51 .Bk -words
52 .Op Fl g Ar group
53 .Ek
54 .Bk -words
55 .Op Fl I Ar realprefix
56 .Ek
57 .Bk -words
58 .Op Fl i Ar iscript
59 .Ek
60 .Bk -words
61 .Op Fl K Ar pkg_dbdir
62 .Ek
63 .Bk -words
64 .Op Fl k Ar dscript
65 .Ek
66 .Bk -words
67 .Op Fl n Ar preserve-file
68 .Ek
69 .Bk -words
70 .Op Fl P Ar dpkgs
71 .Ek
72 .Bk -words
73 .Op Fl T Ar buildpkgs
74 .Ek
75 .Bk -words
76 .Op Fl p Ar prefix
77 .Ek
78 .Bk -words
79 .Op Fl S Ar size-all-file
80 .Ek
81 .Bk -words
82 .Op Fl s Ar size-pkg-file
83 .Ek
84 .Bk -words
85 .Op Fl t Ar template
86 .Ek
87 .Bk -words
88 .Op Fl u Ar owner
89 .Ek
90 .Bk -words
91 .Fl c Ar comment
92 .Ek
93 .Bk -words
94 .Fl d Ar description
95 .Ek
96 .Bk -words
97 .Fl f Ar packlist
98 .Ek
99 .Ar pkg-name
100 .Sh DESCRIPTION
101 The
102 .Nm
103 command is used to create packages that will subsequently be fed to
104 one of the package extraction/info utilities.
105 The input description and command line arguments for the creation of a
106 package are not really meant to be human-generated, though it is easy
107 enough to do so.
108 It is more expected that you will use a front-end tool for
109 the job rather than muddling through it yourself.
110 Nonetheless, a short description of the input syntax is included in this
111 document.
112 .Sh OPTIONS
113 The following command line options are supported:
114 .Bl -tag -width indent
115 .It Fl B Ar build-info-file
116 Install the file
117 .Ar build-info-file
118 so that users of binary packages can see what
119 .Xr make 1
120 definitions
121 were used to control the build when creating the
122 binary package.
123 This allows various build definitions to be retained in a binary package
124 and viewed wherever it is installed, using
125 .Xr pkg_info 1 .
126 .It Fl b Ar build-version-file
127 Install the file
128 .Ar build-version-file
129 so that users of binary packages can see what versions of
130 the files used to control the build were used when creating the
131 binary package.
132 This allows some fine-grained version control information to be retained
133 in a binary package and viewed wherever it is installed, using
134 .Xr pkg_info 1 .
135 .It Fl C Ar cpkgs
136 Set the initial package conflict list to
137 .Ar cpkgs .
138 This is assumed to be a whitespace separated list of package names
139 and is meant as a convenient shorthand for specifying multiple
140 .Cm @pkgcfl
141 directives in the packing list (see PACKING LIST DETAILS section below).
142 .It Fl c Ar [-]desc
143 Fetch package
144 .Pq one line description
145 from file
146 .Ar desc
147 or, if preceded by
148 .Cm - ,
149 the argument itself.
150 This string should also give some idea of which version of the product
151 (if any) the package represents.
152 .It Fl D Ar displayfile
153 Display the file after installing the package.
154 Useful for things like legal notices on almost-free software, etc.
155 .It Fl d Ar [-]desc
156 Fetch long description for package from file
157 .Ar desc
158 or, if preceded by
159 .Cm - ,
160 the argument itself.
161 .It Fl E
162 Add an empty views file to the package.
163 .It Fl F Ar compression
164 Use
165 .Ar compression
166 as compression algorithm.
167 This overrides the heuristic to guess the compression type from the
168 output name.
169 Currently supported values are bzip2, gzip, none and xz.
170 .It Fl f Ar packlist
171 Fetch
172 .Pq packing list
173 for package from the file
174 .Ar packlist
175 or
176 .Cm stdin
177 if
178 .Ar packlist
179 is a
180 .Cm -
181 (dash).
182 .It Fl g Ar group
183 Make
184 .Ar group
185 the default group ownership instead of extracting it from the file system.
186 .It Fl I Ar realprefix
187 Provide the real prefix, as opposed to the staging prefix, for use in
188 staged installations of packages.
189 .It Fl i Ar iscript
190 Set
191 .Ar iscript
192 to be the install procedure for the package.
193 This can be any executable program (or shell script).
194 It will be invoked automatically when the package is later installed.
195 .It Fl K Ar pkg_dbdir
196 Override the value of the
197 .Dv PKG_DBDIR
198 configuration option with the value
199 .Ar pkg_dbdir .
200 .It Fl k Ar dscript
201 Set
202 .Ar dscript
203 to be the de-install procedure for the package.
204 This can be any executable program (or shell script).
205 It will be invoked automatically
206 when the package is later (if ever) de-installed.
207 .It Fl l
208 Check that any symbolic links which are to be placed in the package are
209 relative to the current prefix.
210 This means using
211 .Xr unlink 2
212 and
213 .Xr symlink 2
214 to remove and re-link
215 any symbolic links which are targeted at full path names.
216 .It Fl n Ar preserve-file
217 The file is used to denote that the package should not be deleted.
218 This is intended for use where the deletion of packages may present
219 a bootstrap problem.
220 .It Fl O
221 Go into a
222 .Pq packing list only
223 mode.
224 This is used to do
225 .Pq fake pkg_add
226 operations when a package is installed.
227 In such cases, it is necessary to know what the final, adjusted packing
228 list will look like.
229 .It Fl P Ar dpkgs
230 Set the initial package dependency list to
231 .Ar dpkgs .
232 This is assumed to be a whitespace separated list of package names
233 and is meant as a convenient shorthand for specifying multiple
234 .Cm @pkgdep
235 directives in the packing list (see PACKING LIST DETAILS section below).
236 In addition, the exact versions of the packages referred to in the
237 .Ar dpkgs
238 list will be added to the packing list in the form of
239 .Cm @blddep
240 directives.
241 .It Fl T Ar buildpkgs
242 The exact versions of the packages referred to in the
243 .Ar buildpkgs
244 list will be added to the packing list in the form of
245 .Cm @blddep
246 directives.
247 This directives are stored after those created by the
248 .Fl P
249 option.
250 .Ar buildpkgs
251 is assumed to be a whitespace separated list of package names.
252 .It Fl p Ar prefix
253 Set
254 .Ar prefix
255 as the initial directory
256 .Pq base
257 to start from in selecting files for
258 the package.
259 .It Fl S Ar size-all-file
260 Store the given file for later querying with the
261 .Xr pkg_info 1
262 .Fl S
263 flag.
264 The file is expected to contain the size (in bytes) of all files of
265 this package plus any required packages added up and stored as a
266 ASCII string, terminated by a newline.
267 .It Fl s Ar size-pkg-file
268 Store the given file for later querying with the
269 .Xr pkg_info 1
270 .Fl s
271 flag.
272 The file is expected to contain the size (in bytes) of all files of
273 this package added up and stored as a ASCII string, terminated by a newline.
274 .It Fl t Ar template
275 Use
276 .Ar template
277 as the input to
278 .Xr mktemp 3 .
279 By default, this is the string
280 .Pa /tmp/instmp.XXXXXX ,
281 but it may be necessary to override it in the situation where
282 space in your
283 .Pa /tmp
284 directory is limited.
285 Be sure to leave some number of
286 .Sq X
287 characters for
288 .Xr mktemp 3
289 to fill in with a unique ID.
290 .It Fl U
291 Do not update the package file database with any file information.
292 .It Fl u Ar owner
293 Make
294 .Ar owner
295 the default owner instead of extracting it from the file system.
296 .It Fl V
297 Print version number and exit.
298 .It Fl v
299 Turn on verbose output.
300 .El
301 .Sh PACKING LIST DETAILS
302 The
303 .Pq packing list
304 format (see
305 .Fl f )
306 is fairly simple, being
307 nothing more than a single column of filenames to include in the
308 package.
309 However, since absolute pathnames are generally a bad idea
310 for a package that could be installed potentially anywhere, there is
311 another method of specifying where things are supposed to go
312 and, optionally, what ownership and mode information they should be
313 installed with.
314 This is done by embedding specialized command sequences
315 in the packing list.
316 Briefly described, these sequences are:
317 .Bl -tag -width indent -compact
318 .It Cm @cwd Ar directory
319 Set the internal directory pointer to point to
320 .Ar directory .
321 All subsequent filenames will be assumed relative to this directory.
322 Note:
323 .Cm @cd
324 is also an alias for this command.
325 .It Cm @src Ar directory
326 This command is supported for compatibility only.
327 It was formerly used to override
328 .Cm @cwd
329 during package creation.
330 .It Cm @exec Ar command
331 Execute
332 .Ar command
333 as part of the unpacking process.
334 If
335 .Ar command
336 contains any of the following sequences somewhere in it, they will
337 be expanded inline.
338 For the following examples, assume that
339 .Cm @cwd
340 is set to
341 .Pa /usr/local
342 and the last extracted file was
343 .Pa bin/emacs .
344 .Bl -tag -width indent -compact
345 .It Cm "\&%F"
346 Expands to the last filename extracted (as specified), in the example case
347 .Pa bin/emacs
348 .It Cm "\&%D"
349 Expand to the current directory prefix, as set with
350 .Cm @cwd ,
351 in the example case
352 .Pa /usr/local .
353 .It Cm "\&%B"
354 Expand to the
355 .Pq basename
356 of the fully qualified filename, that
357 is the current directory prefix, plus the last filespec, minus
358 the trailing filename.
359 In the example case, that would be
360 .Pa /usr/local/bin .
361 .It Cm "\&%f"
362 Expand to the
363 .Pq filename
364 part of the fully qualified name, or
365 the converse of
366 .Cm \&%B ,
367 being in the example case,
368 .Pa emacs .
369 .El
370 .It Cm @unexec Ar command
371 Execute
372 .Ar command
373 as part of the deinstallation process.
374 Expansion of special
375 .Cm \&%
376 sequences is the same as for
377 .Cm @exec .
378 This command is not executed during the package add, as
379 .Cm @exec
380 is, but rather when the package is deleted.
381 This is useful for deleting links and other ancillary files that were created
382 as a result of adding the package, but not directly known to the package's
383 table of contents (and hence not automatically removable).
384 The advantage of using
385 .Cm @unexec
386 over a deinstallation script is that you can use the
387 .Pq special sequence expansion
388 to get at files regardless of where they've
389 been potentially redirected (see
390 .Fl p ) .
391 .It Cm @mode Ar mode
392 Set default permission for all subsequently extracted files to
393 .Ar mode .
394 Format is the same as that used by the
395 .Cm chmod
396 command (well, considering that it's later handed off to it, that's
397 no surprise).
398 Use without an arg to set back to default (extraction) permissions.
399 .It Cm @option Ar option
400 Set internal package options, the only currently supported one
401 being
402 .Ar preserve ,
403 which tells pkg_add to move any existing files out of the way,
404 preserving the previous contents (which are also resurrected on
405 pkg_delete, so caveat emptor).
406 .It Cm @owner Ar user
407 Set default ownership for all subsequently extracted files to
408 .Ar user .
409 Use without an arg to set back to default (extraction)
410 ownership.
411 .It Cm @group Ar group
412 Set default group ownership for all subsequently extracted files to
413 .Ar group .
414 Use without an arg to set back to default (extraction)
415 group ownership.
416 .It Cm @comment Ar string
417 Embed a comment in the packing list.
418 Useful in trying to document some particularly hairy sequence that
419 may trip someone up later.
420 .It Cm @ignore
421 Used internally to tell extraction to ignore the next file (don't
422 copy it anywhere), as it's used for some special purpose.
423 .It Cm @name Ar name
424 Set the name of the package.
425 This is mandatory and is usually put at the top.
426 This name is potentially different than the name of the file it came in,
427 and is used when keeping track of the package for later deinstallation.
428 Note that
429 .Nm
430 will derive this field from the
431 .Ar pkg-name
432 and add it automatically if none is given.
433 .It Cm @pkgdir Ar name
434 Declare directory
435 .Pa name
436 as managed.
437 If it does not exist at installation time, it is created.
438 If this directory is no longer referenced by packages and the last
439 file or directory in it is deleted, the directory is removed as well.
440 .It Cm @dirrm Ar name
441 This command is supported for compatibility only.
442 If directory
443 .Pa name
444 exists, it will be deleted at deinstall time.
445 .It Cm @display Ar name
446 Declare
447 .Pa name
448 as the file to be displayed at install time (see
449 .Fl D
450 above).
451 .It Cm @pkgdep Ar pkgname
452 Declare a dependency on the
453 .Ar pkgname
454 package.
455 The
456 .Ar pkgname
457 package must be installed before this package may be
458 installed, and this package must be deinstalled before the
459 .Ar pkgname
460 package is deinstalled.
461 Multiple
462 .Cm @pkgdep
463 directives may be used if the package depends on multiple other packages.
464 .It Cm @blddep Ar pkgname
465 Declare that this package was built with the exact version
466 of
467 .Ar pkgname
468 (since the
469 .Cm @pkgdep
470 directive may contain wildcards or relational
471 package version information).
472 .It Cm @pkgcfl Ar pkgcflname
473 Declare a conflict with the
474 .Ar pkgcflname
475 package, as the two packages contain references to the same files,
476 and so cannot co-exist on the same system.
477 .El
478 .Sh ENVIRONMENT
479 See
480 .Xr pkg_install.conf 5
481 for options, that can also be specified using the environment.
482 .Sh SEE ALSO
483 .Xr pkg_add 1 ,
484 .Xr pkg_admin 1 ,
485 .Xr pkg_delete 1 ,
486 .Xr pkg_info 1 ,
487 .Xr pkg_install.conf 5
488 .Xr pkgsrc 7
489 .Sh HISTORY
490 The
491 .Nm
492 command first appeared in
493 .Fx .
494 .Sh AUTHORS
495 .Bl -tag -width indent -compact
496 .It Jordan Hubbard
497 did most of the work.
498 .It John Kohl
499 refined it for
500 .Nx .
501 .It Hubert Feyrer
502 added
503 .Nx
504 wildcard dependency processing, pkgdb, pkg size recording etc.
505 .El