| blob | ea11998e761f1d2473d968fe4bac3076a41ed01a |
1 .\" $NetBSD: pkg_create.1,v 1.21 2009/11/05 16:22:32 joerg 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 November 15, 2009
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 and none.
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 Set
197 .Ar pkg_dbdir
198 as the package database directory.
199 If this option isn't specified, then the package database directory is
200 taken from the value of the environment variable
201 .Ev PKG_DBDIR
202 if it's set, otherwise it defaults to
203 .Pa /var/db/pkg .
204 .It Fl k Ar dscript
205 Set
206 .Ar dscript
207 to be the de-install procedure for the package.
208 This can be any executable program (or shell script).
209 It will be invoked automatically
210 when the package is later (if ever) de-installed.
211 .It Fl l
212 Check that any symbolic links which are to be placed in the package are
213 relative to the current prefix.
214 This means using
215 .Xr unlink 2
216 and
217 .Xr symlink 2
218 to remove and re-link
219 any symbolic links which are targeted at full path names.
220 .It Fl n Ar preserve-file
221 The file is used to denote that the package should not be deleted.
222 This is intended for use where the deletion of packages may present
223 a bootstrap problem.
224 .It Fl O
225 Go into a
226 .Pq packing list only
227 mode.
228 This is used to do
229 .Pq fake pkg_add
230 operations when a package is installed.
231 In such cases, it is necessary to know what the final, adjusted packing
232 list will look like.
233 .It Fl P Ar dpkgs
234 Set the initial package dependency list to
235 .Ar dpkgs .
236 This is assumed to be a whitespace separated list of package names
237 and is meant as a convenient shorthand for specifying multiple
238 .Cm @pkgdep
239 directives in the packing list (see PACKING LIST DETAILS section below).
240 In addition, the exact versions of the packages referred to in the
241 .Ar dpkgs
242 list will be added to the packing list in the form of
243 .Cm @blddep
244 directives.
245 .It Fl T Ar buildpkgs
246 The exact versions of the packages referred to in the
247 .Ar buildpkgs
248 list will be added to the packing list in the form of
249 .Cm @blddep
250 directives.
251 This directives are stored after those created by the
252 .Fl P
253 option.
254 .Ar buildpkgs
255 is assumed to be a whitespace separated list of package names.
256 .It Fl p Ar prefix
257 Set
258 .Ar prefix
259 as the initial directory
260 .Pq base
261 to start from in selecting files for
262 the package.
263 .It Fl S Ar size-all-file
264 Store the given file for later querying with the
265 .Xr pkg_info 1
266 .Fl S
267 flag.
268 The file is expected to contain the size (in bytes) of all files of
269 this package plus any required packages added up and stored as a
270 ASCII string, terminated by a newline.
271 .It Fl s Ar size-pkg-file
272 Store the given file for later querying with the
273 .Xr pkg_info 1
274 .Fl s
275 flag.
276 The file is expected to contain the size (in bytes) of all files of
277 this package added up and stored as a ASCII string, terminated by a newline.
278 .It Fl t Ar template
279 Use
280 .Ar template
281 as the input to
282 .Xr mktemp 3 .
283 By default, this is the string
284 .Pa /tmp/instmp.XXXXXX ,
285 but it may be necessary to override it in the situation where
286 space in your
287 .Pa /tmp
288 directory is limited.
289 Be sure to leave some number of
290 .Sq X
291 characters for
292 .Xr mktemp 3
293 to fill in with a unique ID.
294 .It Fl U
295 Do not update the package file database with any file information.
296 .It Fl u Ar owner
297 Make
298 .Ar owner
299 the default owner instead of extracting it from the file system.
300 .It Fl V
301 Print version number and exit.
302 .It Fl v
303 Turn on verbose output.
304 .El
305 .Sh PACKING LIST DETAILS
306 The
307 .Pq packing list
308 format (see
309 .Fl f )
310 is fairly simple, being
311 nothing more than a single column of filenames to include in the
312 package.
313 However, since absolute pathnames are generally a bad idea
314 for a package that could be installed potentially anywhere, there is
315 another method of specifying where things are supposed to go
316 and, optionally, what ownership and mode information they should be
317 installed with.
318 This is done by embedding specialized command sequences
319 in the packing list.
320 Briefly described, these sequences are:
321 .Bl -tag -width indent -compact
322 .It Cm @cwd Ar directory
323 Set the internal directory pointer to point to
324 .Ar directory .
325 All subsequent filenames will be assumed relative to this directory.
326 Note:
327 .Cm @cd
328 is also an alias for this command.
329 .It Cm @src Ar directory
330 This command is supported for compatibility only.
331 It was formerly used to override
332 .Cm @cwd
333 during package creation.
334 .It Cm @exec Ar command
335 Execute
336 .Ar command
337 as part of the unpacking process.
338 If
339 .Ar command
340 contains any of the following sequences somewhere in it, they will
341 be expanded inline.
342 For the following examples, assume that
343 .Cm @cwd
344 is set to
345 .Pa /usr/local
346 and the last extracted file was
347 .Pa bin/emacs .
348 .Bl -tag -width indent -compact
349 .It Cm "\&%F"
350 Expands to the last filename extracted (as specified), in the example case
351 .Pa bin/emacs
352 .It Cm "\&%D"
353 Expand to the current directory prefix, as set with
354 .Cm @cwd ,
355 in the example case
356 .Pa /usr/local .
357 .It Cm "\&%B"
358 Expand to the
359 .Pq basename
360 of the fully qualified filename, that
361 is the current directory prefix, plus the last filespec, minus
362 the trailing filename.
363 In the example case, that would be
364 .Pa /usr/local/bin .
365 .It Cm "\&%f"
366 Expand to the
367 .Pq filename
368 part of the fully qualified name, or
369 the converse of
370 .Cm \&%B ,
371 being in the example case,
372 .Pa emacs .
373 .El
374 .It Cm @unexec Ar command
375 Execute
376 .Ar command
377 as part of the deinstallation process.
378 Expansion of special
379 .Cm \&%
380 sequences is the same as for
381 .Cm @exec .
382 This command is not executed during the package add, as
383 .Cm @exec
384 is, but rather when the package is deleted.
385 This is useful for deleting links and other ancillary files that were created
386 as a result of adding the package, but not directly known to the package's
387 table of contents (and hence not automatically removable).
388 The advantage of using
389 .Cm @unexec
390 over a deinstallation script is that you can use the
391 .Pq special sequence expansion
392 to get at files regardless of where they've
393 been potentially redirected (see
394 .Fl p ) .
395 .It Cm @mode Ar mode
396 Set default permission for all subsequently extracted files to
397 .Ar mode .
398 Format is the same as that used by the
399 .Cm chmod
400 command (well, considering that it's later handed off to it, that's
401 no surprise).
402 Use without an arg to set back to default (extraction) permissions.
403 .It Cm @option Ar option
404 Set internal package options, the only currently supported one
405 being
406 .Ar preserve ,
407 which tells pkg_add to move any existing files out of the way,
408 preserving the previous contents (which are also resurrected on
409 pkg_delete, so caveat emptor).
410 .It Cm @owner Ar user
411 Set default ownership for all subsequently extracted files to
412 .Ar user .
413 Use without an arg to set back to default (extraction)
414 ownership.
415 .It Cm @group Ar group
416 Set default group ownership for all subsequently extracted files to
417 .Ar group .
418 Use without an arg to set back to default (extraction)
419 group ownership.
420 .It Cm @comment Ar string
421 Embed a comment in the packing list.
422 Useful in trying to document some particularly hairy sequence that
423 may trip someone up later.
424 .It Cm @ignore
425 Used internally to tell extraction to ignore the next file (don't
426 copy it anywhere), as it's used for some special purpose.
427 .It Cm @name Ar name
428 Set the name of the package.
429 This is mandatory and is usually put at the top.
430 This name is potentially different than the name of the file it came in,
431 and is used when keeping track of the package for later deinstallation.
432 Note that
433 .Nm
434 will derive this field from the
435 .Ar pkg-name
436 and add it automatically if none is given.
437 .It Cm @pkgdir Ar name
438 Declare directory
439 .Pa name
440 as managed.
441 If it does not exist at installation time, it is created.
442 If this directory is no longer referenced by packages and the last
443 file or directory in it is deleted, the directory is removed as well.
444 .It Cm @dirrm Ar name
445 This command is supported for compatibility only.
446 If directory
447 .Pa name
448 exists, it will be deleted at deinstall time.
449 .It Cm @display Ar name
450 Declare
451 .Pa name
452 as the file to be displayed at install time (see
453 .Fl D
454 above).
455 .It Cm @pkgdep Ar pkgname
456 Declare a dependency on the
457 .Ar pkgname
458 package.
459 The
460 .Ar pkgname
461 package must be installed before this package may be
462 installed, and this package must be deinstalled before the
463 .Ar pkgname
464 package is deinstalled.
465 Multiple
466 .Cm @pkgdep
467 directives may be used if the package depends on multiple other packages.
468 .It Cm @blddep Ar pkgname
469 Declare that this package was built with the exact version
470 of
471 .Ar pkgname
472 (since the
473 .Cm @pkgdep
474 directive may contain wildcards or relational
475 package version information).
476 .It Cm @pkgcfl Ar pkgcflname
477 Declare a conflict with the
478 .Ar pkgcflname
479 package, as the two packages contain references to the same files,
480 and so cannot co-exist on the same system.
481 .El
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 sysconf 3 ,
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 most of the work
498 .It John Kohl
499 refined it for
500 .Nx
501 .It Hubert Feyrer
502 .Nx
503 wildcard dependency processing, pkgdb, pkg size recording etc.
504 .El