Mon May 19 16:25:24 2008 UTC ()
Bring pkg_add man page somewhat in sync with reality.


(joerg)
diff -r1.28.6.2 -r1.28.6.3 pkgsrc/pkgtools/pkg_install/files/add/pkg_add.1
diff -r1.25.6.1 -r1.25.6.2 pkgsrc/pkgtools/pkg_install/files/add/pkg_add.cat1
cvs diff -r1.28.6.2 -r1.28.6.3 pkgsrc/pkgtools/pkg_install/files/add/pkg_add.1 (expand / switch to unified diff)

--- pkgsrc/pkgtools/pkg_install/files/add/pkg_add.1 2008/05/11 20:20:37 1.28.6.2
+++ pkgsrc/pkgtools/pkg_install/files/add/pkg_add.1 2008/05/19 16:25:24 1.28.6.3
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: pkg_add.1,v 1.28.6.2 2008/05/11 20:20:37 joerg Exp $ 1.\" $NetBSD: pkg_add.1,v 1.28.6.3 2008/05/19 16:25:24 joerg Exp $
2.\" 2.\"
3.\" FreeBSD install - a package for the installation and maintenance 3.\" FreeBSD install - a package for the installation and maintenance
4.\" of non-core utilities. 4.\" of non-core utilities.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 14.\"
@@ -48,28 +48,28 @@ depends on or requires from both local d @@ -48,28 +48,28 @@ depends on or requires from both local d
48.Bf -emphasis 48.Bf -emphasis
49Since the 49Since the
50.Nm 50.Nm
51command may execute scripts or programs contained within a package file, 51command may execute scripts or programs contained within a package file,
52your system may be susceptible to 52your system may be susceptible to
53.Dq Trojan horses 53.Dq Trojan horses
54or other subtle 54or other subtle
55attacks from miscreants who create dangerous package files. 55attacks from miscreants who create dangerous package files.
56.Pp 56.Pp
57You are advised to verify the competence and identity of those who 57You are advised to verify the competence and identity of those who
58provide installable package files. 58provide installable package files.
59For extra protection, use the digital signatures provided where possible 59For extra protection, use the digital signatures provided where possible
60(see the 60(see the
61.Fl s 61.Xr pkg_install.conf 5 ),
62option), or, failing that, use 62or, failing that, use
63.Xr tar 1 63.Xr tar 1
64to extract the package file, and inspect its contents and scripts 64to extract the package file, and inspect its contents and scripts
65to ensure it poses no danger to your system's integrity. 65to ensure it poses no danger to your system's integrity.
66Pay particular attention to any 66Pay particular attention to any
67.Pa +INSTALL 67.Pa +INSTALL
68or 68or
69.Pa +DEINSTALL 69.Pa +DEINSTALL
70files, and inspect the 70files, and inspect the
71.Pa +CONTENTS 71.Pa +CONTENTS
72file for 72file for
73.Cm @cwd , 73.Cm @cwd ,
74.Cm @mode 74.Cm @mode
75(check for setuid), 75(check for setuid),
@@ -249,96 +249,91 @@ option is given, it's assumed the packag @@ -249,96 +249,91 @@ option is given, it's assumed the packag
249new version instead. 249new version instead.
250Before doing so, all packages that depend on the 250Before doing so, all packages that depend on the
251pkg being upgraded are checked if they also work with the new version. 251pkg being upgraded are checked if they also work with the new version.
252If that test is successful, replacing is prepared by moving an existing 252If that test is successful, replacing is prepared by moving an existing
253.Pa +REQUIRED_BY 253.Pa +REQUIRED_BY
254file aside (if it exists), and running 254file aside (if it exists), and running
255.Xr pkg_delete 1 255.Xr pkg_delete 1
256on the installed package. 256on the installed package.
257Installation then proceeds as if the package 257Installation then proceeds as if the package
258was not installed, and restores the 258was not installed, and restores the
259.Pa +REQUIRED_BY 259.Pa +REQUIRED_BY
260file afterwards. 260file afterwards.
261.It 261.It
 262The package build information is extracted from the
 263.Pa +BUILD_INFO
 264file and compared against the result of
 265.Xr uname 3 .
 266If the operating system or architecture of the package differ from
 267that of the host, installation is aborted.
 268This behavior is overridable with the
 269.Fl f
 270flag.
 271.It
 272The package build information from
 273.Pa +BUILD_INFO
 274is then checked for
 275.Ev USE_ABI_DEPENDS=NO
 276(or
 277.Ev IGNORE_RECOMMENDED ) .
 278If the package was built with ABI dependency recommendations ignored,
 279a warning will be issued.
 280.It
262A check is made to determine if the package conflicts (from 281A check is made to determine if the package conflicts (from
263.Cm @pkgcfl 282.Cm @pkgcfl
264directives, see 283directives, see
265.Xr pkg_create 1 ) 284.Xr pkg_create 1 )
266with an already recorded as installed package. 285with an already recorded as installed package or if an installed package
 286conflicts with the package.
267If it is, installation is terminated. 287If it is, installation is terminated.
268.It 288.It
 289The file list of the package is compared to the file lists of the
 290installed packeges.
 291If there is any overlap, the installation is terminated.
 292.It
269All package dependencies (from 293All package dependencies (from
270.Cm @pkgdep 294.Cm @pkgdep
271directives, see 295directives, see
272.Xr pkg_create 1 ) 296.Xr pkg_create 1 )
273are read from the packing list. 297are read from the packing list.
274If any of these required packages are not currently installed, 298If any of these required packages are not currently installed,
275an attempt is made to find and install it; 299an attempt is made to find and install it;
276if the missing package cannot be found or installed, 300if the missing package cannot be found or installed,
277the installation is terminated. 301the installation is terminated.
278If the 302If the
279.Fl u 303.Fl u
280option was specified twice, any required packages that are installed, 304option was specified twice, any required packages that are installed,
281but which have a version number that is considered to be too old, 305but which have a version number that is considered to be too old,
282are also updated. 306are also updated.
283The dependant packages are found according to the normal 307The dependant packages are found according to the normal
284.Ev PKG_PATH 308.Ev PKG_PATH
285rules. 309rules.
286.It 310.It
287A search is made for any 
288.Cm @option 
289directives which control how the package is added to the system. 
290The only currently implemented option is 
291.Cm @option preserve , 
292which tells pkg_add to move any existing files out of the way, 
293preserving the previous contents (which are also resurrected on 
294pkg_delete, so caveat emptor). 
295.It 
296The package build information is extracted from the 
297.Pa +BUILD_INFO 
298file and compared against the result of 
299.Xr uname 3 . 
300If the operating system or architecture of the package differ from 
301that of the host, installation is aborted. 
302This behavior is overridable with the 
303.Fl f 
304flag. 
305.It 
306The package build information from 
307.Pa +BUILD_INFO 
308is then checked for 
309.Ev USE_ABI_DEPENDS=NO 
310(or 
311.Ev IGNORE_RECOMMENDED ) . 
312If the package was built with ABI dependency recommendations ignored, 
313a warning will be issued. 
314.It 
315If the package contains an 311If the package contains an
316.Ar install 312.Ar install
317script, it is executed with the following arguments: 313script, it is executed with the following arguments:
318.Bl -tag -width indentindent 314.Bl -tag -width indentindent
319.It Ar pkg-name 315.It Ar pkg-name
320The name of the package being installed. 316The name of the package being installed.
321.It Cm PRE-INSTALL 317.It Cm PRE-INSTALL
322Keyword denoting that the script is to perform any actions needed before 318Keyword denoting that the script is to perform any actions needed before
323the package is installed. 319the package is installed.
324.El 320.El
325.Pp 321.Pp
326If the 322If the
327.Ar install 323.Ar install
328script exits with a non-zero status code, the installation is terminated. 324script exits with a non-zero status code, the installation is terminated.
329.It 325.It
330It is used as a guide for moving (or copying, as necessary) files from 326The files from the file list are extracted to the choosen prefix.
331the staging area into their final locations. 
332.It 327.It
333If an 328If an
334.Ar install 329.Ar install
335script exists for the package, it is executed with the following arguments: 330script exists for the package, it is executed with the following arguments:
336.Bl -tag -width indentindent 331.Bl -tag -width indentindent
337.It Ar pkg_name 332.It Ar pkg_name
338The name of the package being installed. 333The name of the package being installed.
339.It Cm POST-INSTALL 334.It Cm POST-INSTALL
340Keyword denoting that the script is to perform any actions needed 335Keyword denoting that the script is to perform any actions needed
341after the package has been installed. 336after the package has been installed.
342.El 337.El
343.It 338.It
344After installation is complete, a copy of the packing list, 339After installation is complete, a copy of the packing list,
@@ -347,28 +342,26 @@ script, description, and display files a @@ -347,28 +342,26 @@ script, description, and display files a
347.Pa /var/db/pkg/\*[Lt]pkg-name\*[Gt] 342.Pa /var/db/pkg/\*[Lt]pkg-name\*[Gt]
348for subsequent possible use by 343for subsequent possible use by
349.Xr pkg_delete 1 . 344.Xr pkg_delete 1 .
350Any package dependencies are recorded in the other packages' 345Any package dependencies are recorded in the other packages'
351.Pa /var/db/pkg/\*[Lt]other-pkg\*[Gt]/+REQUIRED_BY 346.Pa /var/db/pkg/\*[Lt]other-pkg\*[Gt]/+REQUIRED_BY
352file 347file
353(if an alternate package database directory is specified, then it 348(if an alternate package database directory is specified, then it
354overrides the 349overrides the
355.Pa /var/db/pkg 350.Pa /var/db/pkg
356path shown above). 351path shown above).
357.It 352.It
358If the package is a depoted package, then add it to the default view. 353If the package is a depoted package, then add it to the default view.
359.It 354.It
360The staging area is deleted and the program terminates. 
361.It 
362Finally, if we were upgrading a package, any 355Finally, if we were upgrading a package, any
363.Pa +REQUIRED_BY 356.Pa +REQUIRED_BY
364file that was moved aside before upgrading was started is now moved 357file that was moved aside before upgrading was started is now moved
365back into place. 358back into place.
366.El 359.El
367.Pp 360.Pp
368The 361The
369.Ar install 362.Ar install
370script is called with the environment variable 363script is called with the environment variable
371.Ev PKG_PREFIX 364.Ev PKG_PREFIX
372set to the installation prefix (see the 365set to the installation prefix (see the
373.Fl p 366.Fl p
374option above). 367option above).
@@ -411,30 +404,26 @@ is used if a given package can't be foun @@ -411,30 +404,26 @@ is used if a given package can't be foun
411.Pa /usr/pkgsrc/packages/All . 404.Pa /usr/pkgsrc/packages/All .
412The environment variable 405The environment variable
413should be a series of entries separated by semicolons. 406should be a series of entries separated by semicolons.
414Each entry consists of a directory name or URL. 407Each entry consists of a directory name or URL.
415The current directory may be indicated implicitly by an empty directory 408The current directory may be indicated implicitly by an empty directory
416name, or explicitly by a single period. 409name, or explicitly by a single period.
417FTP URLs may not end with a slash. 410FTP URLs may not end with a slash.
418.It Ev PKG_REFCOUNT_DBDIR 411.It Ev PKG_REFCOUNT_DBDIR
419Location of the package reference counts database directory. 412Location of the package reference counts database directory.
420The default location is the path to the package database directory with 413The default location is the path to the package database directory with
421.Dq .refcount 414.Dq .refcount
422appended to the path, e.g. 415appended to the path, e.g.
423.Pa /var/db/pkg.refcount . 416.Pa /var/db/pkg.refcount .
424.It Ev PKG_TMPDIR 
425Staging directory for installing packages, defaults to /var/tmp. 
426Set to directory with lots of free disk if you run out of 
427space when installing a binary package. 
428.It Ev PKG_VIEW 417.It Ev PKG_VIEW
429The default view can be specified in the 418The default view can be specified in the
430.Ev PKG_VIEW 419.Ev PKG_VIEW
431environment variable. 420environment variable.
432.El 421.El
433.Sh EXAMPLES 422.Sh EXAMPLES
434In all cases, 423In all cases,
435.Nm 424.Nm
436will try to install binary packages listed in dependencies list. 425will try to install binary packages listed in dependencies list.
437.Pp 426.Pp
438You can specify a compiled binary package explicitly on the command line. 427You can specify a compiled binary package explicitly on the command line.
439.Bd -literal 428.Bd -literal
440# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz 429# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz
@@ -476,47 +465,68 @@ directory to your @@ -476,47 +465,68 @@ directory to your
476.Ev PKG_PATH 465.Ev PKG_PATH
477like this: 466like this:
478.Bd -literal 467.Bd -literal
479# export PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/;ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/vulnerable/" 468# export PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/;ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/vulnerable/"
480.Ed 469.Ed
481.Pp 470.Pp
482(The quotes are needed because semicolon 471(The quotes are needed because semicolon
483.Pq Sq \&; 472.Pq Sq \&;
484is a shell meta-character.) 473is a shell meta-character.)
485If you do this, consider installing and using the 474If you do this, consider installing and using the
486.Pa security/audit-packages 475.Pa security/audit-packages
487package and running it after every 476package and running it after every
488.Nm . 477.Nm .
 478.Sh CONFIGURATION VARIABLES
 479The following variables change the behaviour of
 480.Nm
 481and can be found in greater detail in
 482.Xr pkg_install.conf 5 :
 483.Bl -tag -width CERTIFICATE_ANCHOR_PKGS
 484.It Ev CERTIFICATE_ANCHOR_PKGS
 485Location of the trust anchor for binary packages.
 486.It Ev CERTIFICATE_CHAIN
 487Location of a file with additional certificates used to fill holes in
 488the trust chain.
 489.It Ev VERIFIED_INSTALLATION
 490Specify interactiveness and use of digital signature.
 491The value "never" just uses the binary package without requiring a signature.
 492The value "always" requires a valid signature and terminates the installation
 493otherwise.
 494The value "trusted" asks before installing packages without valid signature.
 495The value "interactive" will always ask the user.
 496.El
489.Sh SEE ALSO 497.Sh SEE ALSO
490.Xr pkg_admin 1 , 498.Xr pkg_admin 1 ,
491.Xr pkg_create 1 , 499.Xr pkg_create 1 ,
492.Xr pkg_delete 1 , 500.Xr pkg_delete 1 ,
493.Xr pkg_info 1 , 501.Xr pkg_info 1 ,
494.Xr tar 1 , 502.Xr tar 1 ,
495.Xr mktemp 3 , 503.Xr mktemp 3 ,
496.Xr sysconf 3 , 504.Xr sysconf 3 ,
497.Xr pkgsrc 7 505.Xr pkgsrc 7
498.Sh AUTHORS 506.Sh AUTHORS
499.Bl -tag -width indent -compact 507.Bl -tag -width indent -compact
500.It "Jordan Hubbard" 508.It "Jordan Hubbard"
501Initial work and ongoing development. 509Initial work and ongoing development.
502.It "John Kohl" 510.It "John Kohl"
503.Nx 511.Nx
504refinements. 512refinements.
505.It "Hubert Feyrer" 513.It "Hubert Feyrer"
506.Nx 514.Nx
507wildcard dependency processing, pkgdb, upgrading, etc. 515wildcard dependency processing, pkgdb, upgrading, etc.
508.It Thomas Klausner 516.It Thomas Klausner
509HTTP support. 517HTTP support.
 518.It Joerg Sonnenberger
 519Rewrote most of the code base to work without external commands.
510.El 520.El
511.Sh BUGS 521.Sh BUGS
512Hard links between files in a distribution are only preserved if either 522Hard links between files in a distribution are only preserved if either
513(1) the staging area is on the same file system as the target directory of 523(1) the staging area is on the same file system as the target directory of
514all the links to the file, or (2) all the links to the file are bracketed by 524all the links to the file, or (2) all the links to the file are bracketed by
515.Cm @cwd 525.Cm @cwd
516directives in the contents file, 526directives in the contents file,
517.Em and 527.Em and
518and the link names are extracted with a single 528and the link names are extracted with a single
519.Cm tar 529.Cm tar
520command (not split between 530command (not split between
521invocations due to exec argument-space limitations--this depends on the 531invocations due to exec argument-space limitations--this depends on the
522value returned by 532value returned by
cvs diff -r1.25.6.1 -r1.25.6.2 pkgsrc/pkgtools/pkg_install/files/add/Attic/pkg_add.cat1 (expand / switch to unified diff)

--- pkgsrc/pkgtools/pkg_install/files/add/Attic/pkg_add.cat1 2008/05/11 20:20:37 1.25.6.1
+++ pkgsrc/pkgtools/pkg_install/files/add/Attic/pkg_add.cat1 2008/05/19 16:25:24 1.25.6.2
@@ -15,33 +15,33 @@ DDEESSCCRRIIPPTTIIOONN @@ -15,33 +15,33 @@ DDEESSCCRRIIPPTTIIOONN
15 prepared collections of pre-built binaries, documentation, configura- 15 prepared collections of pre-built binaries, documentation, configura-
16 tions, installation instructions and/or other files. ppkkgg__aadddd can recur- 16 tions, installation instructions and/or other files. ppkkgg__aadddd can recur-
17 sively install other packages that the current package depends on or 17 sively install other packages that the current package depends on or
18 requires from both local disk and via FTP or HTTP. 18 requires from both local disk and via FTP or HTTP.
19 19
20WWAARRNNIINNGG 20WWAARRNNIINNGG
21 _S_i_n_c_e _t_h_e ppkkgg__aadddd _c_o_m_m_a_n_d _m_a_y _e_x_e_c_u_t_e _s_c_r_i_p_t_s _o_r _p_r_o_g_r_a_m_s _c_o_n_t_a_i_n_e_d 21 _S_i_n_c_e _t_h_e ppkkgg__aadddd _c_o_m_m_a_n_d _m_a_y _e_x_e_c_u_t_e _s_c_r_i_p_t_s _o_r _p_r_o_g_r_a_m_s _c_o_n_t_a_i_n_e_d
22 _w_i_t_h_i_n _a _p_a_c_k_a_g_e _f_i_l_e_, _y_o_u_r _s_y_s_t_e_m _m_a_y _b_e _s_u_s_c_e_p_t_i_b_l_e _t_o _`_`_T_r_o_j_a_n 22 _w_i_t_h_i_n _a _p_a_c_k_a_g_e _f_i_l_e_, _y_o_u_r _s_y_s_t_e_m _m_a_y _b_e _s_u_s_c_e_p_t_i_b_l_e _t_o _`_`_T_r_o_j_a_n
23 _h_o_r_s_e_s_'_' _o_r _o_t_h_e_r _s_u_b_t_l_e _a_t_t_a_c_k_s _f_r_o_m _m_i_s_c_r_e_a_n_t_s _w_h_o _c_r_e_a_t_e _d_a_n_g_e_r_o_u_s 23 _h_o_r_s_e_s_'_' _o_r _o_t_h_e_r _s_u_b_t_l_e _a_t_t_a_c_k_s _f_r_o_m _m_i_s_c_r_e_a_n_t_s _w_h_o _c_r_e_a_t_e _d_a_n_g_e_r_o_u_s
24 _p_a_c_k_a_g_e _f_i_l_e_s_. 24 _p_a_c_k_a_g_e _f_i_l_e_s_.
25 25
26 _Y_o_u _a_r_e _a_d_v_i_s_e_d _t_o _v_e_r_i_f_y _t_h_e _c_o_m_p_e_t_e_n_c_e _a_n_d _i_d_e_n_t_i_t_y _o_f _t_h_o_s_e _w_h_o _p_r_o_- 26 _Y_o_u _a_r_e _a_d_v_i_s_e_d _t_o _v_e_r_i_f_y _t_h_e _c_o_m_p_e_t_e_n_c_e _a_n_d _i_d_e_n_t_i_t_y _o_f _t_h_o_s_e _w_h_o _p_r_o_-
27 _v_i_d_e _i_n_s_t_a_l_l_a_b_l_e _p_a_c_k_a_g_e _f_i_l_e_s_. _F_o_r _e_x_t_r_a _p_r_o_t_e_c_t_i_o_n_, _u_s_e _t_h_e _d_i_g_i_t_a_l 27 _v_i_d_e _i_n_s_t_a_l_l_a_b_l_e _p_a_c_k_a_g_e _f_i_l_e_s_. _F_o_r _e_x_t_r_a _p_r_o_t_e_c_t_i_o_n_, _u_s_e _t_h_e _d_i_g_i_t_a_l
28 _s_i_g_n_a_t_u_r_e_s _p_r_o_v_i_d_e_d _w_h_e_r_e _p_o_s_s_i_b_l_e _(_s_e_e _t_h_e --ss _o_p_t_i_o_n_)_, _o_r_, _f_a_i_l_i_n_g _t_h_a_t_, 28 _s_i_g_n_a_t_u_r_e_s _p_r_o_v_i_d_e_d _w_h_e_r_e _p_o_s_s_i_b_l_e _(_s_e_e _t_h_e pkg_install.conf(_5) _)_, _o_r_,
29 _u_s_e tar(_1) _t_o _e_x_t_r_a_c_t _t_h_e _p_a_c_k_a_g_e _f_i_l_e_, _a_n_d _i_n_s_p_e_c_t _i_t_s _c_o_n_t_e_n_t_s _a_n_d 29 _f_a_i_l_i_n_g _t_h_a_t_, _u_s_e tar(_1) _t_o _e_x_t_r_a_c_t _t_h_e _p_a_c_k_a_g_e _f_i_l_e_, _a_n_d _i_n_s_p_e_c_t _i_t_s
30 _s_c_r_i_p_t_s _t_o _e_n_s_u_r_e _i_t _p_o_s_e_s _n_o _d_a_n_g_e_r _t_o _y_o_u_r _s_y_s_t_e_m_'_s _i_n_t_e_g_r_i_t_y_. _P_a_y 30 _c_o_n_t_e_n_t_s _a_n_d _s_c_r_i_p_t_s _t_o _e_n_s_u_r_e _i_t _p_o_s_e_s _n_o _d_a_n_g_e_r _t_o _y_o_u_r _s_y_s_t_e_m_'_s
31 _p_a_r_t_i_c_u_l_a_r _a_t_t_e_n_t_i_o_n _t_o _a_n_y _+_I_N_S_T_A_L_L _o_r _+_D_E_I_N_S_T_A_L_L _f_i_l_e_s_, _a_n_d _i_n_s_p_e_c_t _t_h_e 31 _i_n_t_e_g_r_i_t_y_. _P_a_y _p_a_r_t_i_c_u_l_a_r _a_t_t_e_n_t_i_o_n _t_o _a_n_y _+_I_N_S_T_A_L_L _o_r _+_D_E_I_N_S_T_A_L_L _f_i_l_e_s_,
32 _+_C_O_N_T_E_N_T_S _f_i_l_e _f_o_r @@ccwwdd_, @@mmooddee _(_c_h_e_c_k _f_o_r _s_e_t_u_i_d_)_, @@ddiirrrrmm_, @@eexxeecc_, _a_n_d 32 _a_n_d _i_n_s_p_e_c_t _t_h_e _+_C_O_N_T_E_N_T_S _f_i_l_e _f_o_r @@ccwwdd_, @@mmooddee _(_c_h_e_c_k _f_o_r _s_e_t_u_i_d_)_,
33 @@uunneexxeecc _d_i_r_e_c_t_i_v_e_s_, _a_n_d_/_o_r _u_s_e _t_h_e pkg_info(_1) _c_o_m_m_a_n_d _t_o _e_x_a_m_i_n_e _t_h_e 33 @@ddiirrrrmm_, @@eexxeecc_, _a_n_d @@uunneexxeecc _d_i_r_e_c_t_i_v_e_s_, _a_n_d_/_o_r _u_s_e _t_h_e pkg_info(_1) _c_o_m_m_a_n_d
34 _p_a_c_k_a_g_e _f_i_l_e_. 34 _t_o _e_x_a_m_i_n_e _t_h_e _p_a_c_k_a_g_e _f_i_l_e_.
35 35
36OOPPTTIIOONNSS 36OOPPTTIIOONNSS
37 The following command line arguments are supported: 37 The following command line arguments are supported:
38 38
39 _p_k_g_-_n_a_m_e [_._._.] 39 _p_k_g_-_n_a_m_e [_._._.]
40 The named packages are installed. _p_k_g_-_n_a_m_e may be either a URL 40 The named packages are installed. _p_k_g_-_n_a_m_e may be either a URL
41 or a local pathname, a package name of "-" will cause ppkkgg__aadddd to 41 or a local pathname, a package name of "-" will cause ppkkgg__aadddd to
42 read from stdin. If the packages are not found in the current 42 read from stdin. If the packages are not found in the current
43 working directory, ppkkgg__aadddd will search them in each directory 43 working directory, ppkkgg__aadddd will search them in each directory
44 named by the PKG_PATH environment variable. Any dependencies 44 named by the PKG_PATH environment variable. Any dependencies
45 required by the installed package will be searched in the same 45 required by the installed package will be searched in the same
46 location that the original package was installed from. 46 location that the original package was installed from.
47 47
@@ -132,97 +132,93 @@ TTEECCHHNNIICCAALL DDEETTAA @@ -132,97 +132,93 @@ TTEECCHHNNIICCAALL DDEETTAA
132 of it is already recorded as installed. If it is, installa- 132 of it is already recorded as installed. If it is, installa-
133 tion is terminated if the --uu option is not given. 133 tion is terminated if the --uu option is not given.
134 134
135 If the --uu option is given, it's assumed the package should be 135 If the --uu option is given, it's assumed the package should be
136 replaced by the new version instead. Before doing so, all 136 replaced by the new version instead. Before doing so, all
137 packages that depend on the pkg being upgraded are checked if 137 packages that depend on the pkg being upgraded are checked if
138 they also work with the new version. If that test is success- 138 they also work with the new version. If that test is success-
139 ful, replacing is prepared by moving an existing _+_R_E_Q_U_I_R_E_D___B_Y 139 ful, replacing is prepared by moving an existing _+_R_E_Q_U_I_R_E_D___B_Y
140 file aside (if it exists), and running pkg_delete(1) on the 140 file aside (if it exists), and running pkg_delete(1) on the
141 installed package. Installation then proceeds as if the pack- 141 installed package. Installation then proceeds as if the pack-
142 age was not installed, and restores the _+_R_E_Q_U_I_R_E_D___B_Y file 142 age was not installed, and restores the _+_R_E_Q_U_I_R_E_D___B_Y file
143 afterwards. 143 afterwards.
144 144
145 2. A check is made to determine if the package conflicts (from 145 2. The package build information is extracted from the
 146 _+_B_U_I_L_D___I_N_F_O file and compared against the result of uname(3).
 147 If the operating system or architecture of the package differ
 148 from that of the host, installation is aborted. This behavior
 149 is overridable with the --ff flag.
 150
 151 3. The package build information from _+_B_U_I_L_D___I_N_F_O is then checked
 152 for USE_ABI_DEPENDS=NO (or IGNORE_RECOMMENDED). If the pack-
 153 age was built with ABI dependency recommendations ignored, a
 154 warning will be issued.
 155
 156 4. A check is made to determine if the package conflicts (from
146 @@ppkkggccffll directives, see pkg_create(1)) with an already 157 @@ppkkggccffll directives, see pkg_create(1)) with an already
147 recorded as installed package. If it is, installation is ter- 158 recorded as installed package or if an installed package con-
148 minated. 159 flicts with the package. If it is, installation is termi-
 160 nated.
 161
 162 5. The file list of the package is compared to the file lists of
 163 the installed packeges. If there is any overlap, the instal-
 164 lation is terminated.
149 165
150 3. All package dependencies (from @@ppkkggddeepp directives, see 166 6. All package dependencies (from @@ppkkggddeepp directives, see
151 pkg_create(1)) are read from the packing list. If any of 167 pkg_create(1)) are read from the packing list. If any of
152 these required packages are not currently installed, an 168 these required packages are not currently installed, an
153 attempt is made to find and install it; if the missing package 169 attempt is made to find and install it; if the missing package
154 cannot be found or installed, the installation is terminated. 170 cannot be found or installed, the installation is terminated.
155 If the --uu option was specified twice, any required packages 171 If the --uu option was specified twice, any required packages
156 that are installed, but which have a version number that is 172 that are installed, but which have a version number that is
157 considered to be too old, are also updated. The dependant 173 considered to be too old, are also updated. The dependant
158 packages are found according to the normal PKG_PATH rules. 174 packages are found according to the normal PKG_PATH rules.
159 175
160 4. A search is made for any @@ooppttiioonn directives which control how 
161 the package is added to the system. The only currently imple- 
162 mented option is @@ooppttiioonn pprreesseerrvvee, which tells pkg_add to move 
163 any existing files out of the way, preserving the previous 
164 contents (which are also resurrected on pkg_delete, so caveat 
165 emptor). 
166 
167 5. The package build information is extracted from the 
168 _+_B_U_I_L_D___I_N_F_O file and compared against the result of uname(3). 
169 If the operating system or architecture of the package differ 
170 from that of the host, installation is aborted. This behavior 
171 is overridable with the --ff flag. 
172 
173 6. The package build information from _+_B_U_I_L_D___I_N_F_O is then checked 
174 for USE_ABI_DEPENDS=NO (or IGNORE_RECOMMENDED). If the pack- 
175 age was built with ABI dependency recommendations ignored, a 
176 warning will be issued. 
177 
178 7. If the package contains an _i_n_s_t_a_l_l script, it is executed with 176 7. If the package contains an _i_n_s_t_a_l_l script, it is executed with
179 the following arguments: 177 the following arguments:
180 178
181 _p_k_g_-_n_a_m_e The name of the package being installed. 179 _p_k_g_-_n_a_m_e The name of the package being installed.
182 180
183 PPRREE--IINNSSTTAALLLL Keyword denoting that the script is to perform 181 PPRREE--IINNSSTTAALLLL Keyword denoting that the script is to perform
184 any actions needed before the package is 182 any actions needed before the package is
185 installed. 183 installed.
186 184
187 If the _i_n_s_t_a_l_l script exits with a non-zero status code, the 185 If the _i_n_s_t_a_l_l script exits with a non-zero status code, the
188 installation is terminated. 186 installation is terminated.
189 187
190 8. It is used as a guide for moving (or copying, as necessary) 188 8. The files from the file list are extracted to the choosen pre-
191 files from the staging area into their final locations. 189 fix.
192 190
193 9. If an _i_n_s_t_a_l_l script exists for the package, it is executed 191 9. If an _i_n_s_t_a_l_l script exists for the package, it is executed
194 with the following arguments: 192 with the following arguments:
195 193
196 _p_k_g___n_a_m_e The name of the package being installed. 194 _p_k_g___n_a_m_e The name of the package being installed.
197 195
198 PPOOSSTT--IINNSSTTAALLLL Keyword denoting that the script is to perform 196 PPOOSSTT--IINNSSTTAALLLL Keyword denoting that the script is to perform
199 any actions needed after the package has been 197 any actions needed after the package has been
200 installed. 198 installed.
201 199
202 10. After installation is complete, a copy of the packing list, 200 10. After installation is complete, a copy of the packing list,
203 _d_e_i_n_s_t_a_l_l script, description, and display files are copied 201 _d_e_i_n_s_t_a_l_l script, description, and display files are copied
204 into _/_v_a_r_/_d_b_/_p_k_g_/_<_p_k_g_-_n_a_m_e_> for subsequent possible use by 202 into _/_v_a_r_/_d_b_/_p_k_g_/_<_p_k_g_-_n_a_m_e_> for subsequent possible use by
205 pkg_delete(1). Any package dependencies are recorded in the 203 pkg_delete(1). Any package dependencies are recorded in the
206 other packages' _/_v_a_r_/_d_b_/_p_k_g_/_<_o_t_h_e_r_-_p_k_g_>_/_+_R_E_Q_U_I_R_E_D___B_Y file (if 204 other packages' _/_v_a_r_/_d_b_/_p_k_g_/_<_o_t_h_e_r_-_p_k_g_>_/_+_R_E_Q_U_I_R_E_D___B_Y file (if
207 an alternate package database directory is specified, then it 205 an alternate package database directory is specified, then it
208 overrides the _/_v_a_r_/_d_b_/_p_k_g path shown above). 206 overrides the _/_v_a_r_/_d_b_/_p_k_g path shown above).
209 207
210 11. If the package is a depoted package, then add it to the 208 11. If the package is a depoted package, then add it to the
211 default view. 209 default view.
212 210
213 12. The staging area is deleted and the program terminates. 211 12. Finally, if we were upgrading a package, any _+_R_E_Q_U_I_R_E_D___B_Y file
214 
215 13. Finally, if we were upgrading a package, any _+_R_E_Q_U_I_R_E_D___B_Y file 
216 that was moved aside before upgrading was started is now moved 212 that was moved aside before upgrading was started is now moved
217 back into place. 213 back into place.
218 214
219 The _i_n_s_t_a_l_l script is called with the environment variable PKG_PREFIX set 215 The _i_n_s_t_a_l_l script is called with the environment variable PKG_PREFIX set
220 to the installation prefix (see the --pp option above). This allows a 216 to the installation prefix (see the --pp option above). This allows a
221 package author to write a script that reliably performs some action on 217 package author to write a script that reliably performs some action on
222 the directory where the package is installed, even if the user might 218 the directory where the package is installed, even if the user might
223 change it with the --pp flag to ppkkgg__aadddd. The scripts are also called with 219 change it with the --pp flag to ppkkgg__aadddd. The scripts are also called with
224 the PKG_METADATA_DIR environment variable set to the location of the _+_* 220 the PKG_METADATA_DIR environment variable set to the location of the _+_*
225 meta-data files, and with the PKG_REFCOUNT_DBDIR environment variable set 221 meta-data files, and with the PKG_REFCOUNT_DBDIR environment variable set
226 to the location of the package reference counts database directory. 222 to the location of the package reference counts database directory.
227 223
228EENNVVIIRROONNMMEENNTT 224EENNVVIIRROONNMMEENNTT
@@ -238,30 +234,26 @@ EENNVVIIRROONNMMEENNTT @@ -238,30 +234,26 @@ EENNVVIIRROONNMMEENNTT
238 found, it's usually set to _/_u_s_r_/_p_k_g_s_r_c_/_p_a_c_k_a_g_e_s_/_A_l_l. The 234 found, it's usually set to _/_u_s_r_/_p_k_g_s_r_c_/_p_a_c_k_a_g_e_s_/_A_l_l. The
239 environment variable should be a series of entries separated 235 environment variable should be a series of entries separated
240 by semicolons. Each entry consists of a directory name or 236 by semicolons. Each entry consists of a directory name or
241 URL. The current directory may be indicated implicitly by an 237 URL. The current directory may be indicated implicitly by an
242 empty directory name, or explicitly by a single period. FTP 238 empty directory name, or explicitly by a single period. FTP
243 URLs may not end with a slash. 239 URLs may not end with a slash.
244 240
245 PKG_REFCOUNT_DBDIR 241 PKG_REFCOUNT_DBDIR
246 Location of the package reference counts database directory. 242 Location of the package reference counts database directory.
247 The default location is the path to the package database 243 The default location is the path to the package database
248 directory with ``.refcount'' appended to the path, e.g. 244 directory with ``.refcount'' appended to the path, e.g.
249 _/_v_a_r_/_d_b_/_p_k_g_._r_e_f_c_o_u_n_t. 245 _/_v_a_r_/_d_b_/_p_k_g_._r_e_f_c_o_u_n_t.
250 246
251 PKG_TMPDIR Staging directory for installing packages, defaults to 
252 /var/tmp. Set to directory with lots of free disk if you run 
253 out of space when installing a binary package. 
254 
255 PKG_VIEW The default view can be specified in the PKG_VIEW environment 247 PKG_VIEW The default view can be specified in the PKG_VIEW environment
256 variable. 248 variable.
257 249
258EEXXAAMMPPLLEESS 250EEXXAAMMPPLLEESS
259 In all cases, ppkkgg__aadddd will try to install binary packages listed in 251 In all cases, ppkkgg__aadddd will try to install binary packages listed in
260 dependencies list. 252 dependencies list.
261 253
262 You can specify a compiled binary package explicitly on the command line. 254 You can specify a compiled binary package explicitly on the command line.
263 255
264 # pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz 256 # pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz
265 257
266 If you omit the version number, ppkkgg__aadddd will install the latest version 258 If you omit the version number, ppkkgg__aadddd will install the latest version
267 available. With --vv, ppkkgg__aadddd emits more messages to terminal. 259 available. With --vv, ppkkgg__aadddd emits more messages to terminal.
@@ -277,39 +269,60 @@ EEXXAAMMPPLLEESS @@ -277,39 +269,60 @@ EEXXAAMMPPLLEESS
277 # pkg_add -v firefox 269 # pkg_add -v firefox
278 270
279 Over time, as problems are found in packages, they will be moved from the 271 Over time, as problems are found in packages, they will be moved from the
280 _A_l_l subdirectory into the _v_u_l_n_e_r_a_b_l_e subdirectory. If you want to accept 272 _A_l_l subdirectory into the _v_u_l_n_e_r_a_b_l_e subdirectory. If you want to accept
281 vulnerable packages by default (and know what you are doing), you can add 273 vulnerable packages by default (and know what you are doing), you can add
282 the _v_u_l_n_e_r_a_b_l_e directory to your PKG_PATH like this: 274 the _v_u_l_n_e_r_a_b_l_e directory to your PKG_PATH like this:
283 275
284 # export PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/;ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/vulnerable/" 276 # export PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/;ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/vulnerable/"
285 277
286 (The quotes are needed because semicolon (`;') is a shell meta-charac- 278 (The quotes are needed because semicolon (`;') is a shell meta-charac-
287 ter.) If you do this, consider installing and using the 279 ter.) If you do this, consider installing and using the
288 _s_e_c_u_r_i_t_y_/_a_u_d_i_t_-_p_a_c_k_a_g_e_s package and running it after every ppkkgg__aadddd. 280 _s_e_c_u_r_i_t_y_/_a_u_d_i_t_-_p_a_c_k_a_g_e_s package and running it after every ppkkgg__aadddd.
289 281
 282CCOONNFFIIGGUURRAATTIIOONN VVAARRIIAABBLLEESS
 283 The following variables change the behaviour of ppkkgg__aadddd and can be found
 284 in greater detail in pkg_install.conf(5):
 285
 286 CERTIFICATE_ANCHOR_PKGS Location of the trust anchor for binary pack-
 287 ages.
 288
 289 CERTIFICATE_CHAIN Location of a file with additional certificates
 290 used to fill holes in the trust chain.
 291
 292 VERIFIED_INSTALLATION Specify interactiveness and use of digital sig-
 293 nature. The value "never" just uses the binary
 294 package without requiring a signature. The
 295 value "always" requires a valid signature and
 296 terminates the installation otherwise. The
 297 value "trusted" asks before installing packages
 298 without valid signature. The value "interac-
 299 tive" will always ask the user.
 300
290SSEEEE AALLSSOO 301SSEEEE AALLSSOO
291 pkg_admin(1), pkg_create(1), pkg_delete(1), pkg_info(1), tar(1), 302 pkg_admin(1), pkg_create(1), pkg_delete(1), pkg_info(1), tar(1),
292 mktemp(3), sysconf(3), pkgsrc(7) 303 mktemp(3), sysconf(3), pkgsrc(7)
293 304
294AAUUTTHHOORRSS 305AAUUTTHHOORRSS
295 Jordan Hubbard 306 Jordan Hubbard
296 Initial work and ongoing development. 307 Initial work and ongoing development.
297 John Kohl 308 John Kohl
298 NetBSD refinements. 309 NetBSD refinements.
299 Hubert Feyrer 310 Hubert Feyrer
300 NetBSD wildcard dependency processing, pkgdb, upgrading, etc. 311 NetBSD wildcard dependency processing, pkgdb, upgrading, etc.
301 Thomas Klausner 312 Thomas Klausner
302 HTTP support. 313 HTTP support.
 314 Joerg Sonnenberger
 315 Rewrote most of the code base to work without external commands.
303 316
304BBUUGGSS 317BBUUGGSS
305 Hard links between files in a distribution are only preserved if either 318 Hard links between files in a distribution are only preserved if either
306 (1) the staging area is on the same file system as the target directory 319 (1) the staging area is on the same file system as the target directory
307 of all the links to the file, or (2) all the links to the file are brack- 320 of all the links to the file, or (2) all the links to the file are brack-
308 eted by @@ccwwdd directives in the contents file, _a_n_d and the link names are 321 eted by @@ccwwdd directives in the contents file, _a_n_d and the link names are
309 extracted with a single ttaarr command (not split between invocations due to 322 extracted with a single ttaarr command (not split between invocations due to
310 exec argument-space limitations--this depends on the value returned by 323 exec argument-space limitations--this depends on the value returned by
311 ssyyssccoonnff(___S_C___A_R_G___M_A_X)). 324 ssyyssccoonnff(___S_C___A_R_G___M_A_X)).
312 325
313 Package upgrading needs a lot more work to be really universal. 326 Package upgrading needs a lot more work to be really universal.
314 327
315 Sure to be others. 328 Sure to be others.