From: espie Date: Fri, 3 Jan 2014 12:54:59 +0000 (+0000) Subject: start moving internal annotations' description into package(5) proper, X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=c1614ab3b8f3f651553307a6fbc3e76bcf832e00;p=openbsd start moving internal annotations' description into package(5) proper, pkg_create(1) should only document what users can use. Accordingly, describe dependencies in terms of -P and -W directly. --- diff --git a/usr.sbin/pkg_add/package.5 b/usr.sbin/pkg_add/package.5 index fb32ceec62b..bb564523273 100644 --- a/usr.sbin/pkg_add/package.5 +++ b/usr.sbin/pkg_add/package.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: package.5,v 1.12 2011/09/29 17:57:09 jmc Exp $ +.\" $OpenBSD: package.5,v 1.13 2014/01/03 12:54:59 espie Exp $ .\" Copyright (c) 2005-2006 Marc Espie .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -12,7 +12,7 @@ .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.Dd $Mdocdate: September 29 2011 $ +.Dd $Mdocdate: January 3 2014 $ .Dt PACKAGE 5 .Os .Sh NAME @@ -78,6 +78,49 @@ and long link names with .Pa LongLink#n . The packing-list will hold the real file names, and the package tools will reconstitute the correct names behind the scenes. +.Sh PACKING LIST ANNOTATIONS +User annotations are described in +.Xr pkg_create 1 . +The following annotations are automatically inserted during package creation +and installations: +.Pp +.Bl -tag -width Ds -compact +.It Cm @arch Ar arches +List of architectures for which this package is intended. +This corresponds to +.Fl A Ar arches +of +.Xr pkg_create 1 +.It Cm @comment pkgpath=path cdrom=yes/no ftp=yes/no +Historical accident. +This specific comment encodes the actual +.Fl D Ar FULLPKGPATH , +.Fl D Ar CDROM , +and +.Fl D Ar FTP +arguments to +.Xr pkg_create 1 . +.Pp +.It Xo +.Cm @depend +.Sm off +.Ar pkgpath : +.Ar pkgspec : +.Ar default +.Sm on +.Xc +Record a dependency declared using the option +.Fl P +of +.Xr pkg_create 1 . +.Pp +.Pp +.It Cm @wantlib Ar libspec +Record a library requirement declared using the option +.Fl W +of +.Xr pkg_create 1 . +.El .Sh PACKAGE SIGNATURES All information within a package is checksummed, using SHA256 since .Ox 4.4 . @@ -89,8 +132,10 @@ Packing-lists can be signed. If a signature is found, then it will be checked during installation, and failure to verify will prevent the package from installing correctly. -Currently, only X.509-style signatures are supported. -They rely on a certificate authority file being present as +Currently, +.Xr signify 1 +and X.509-style signatures are supported. +X.509 signatures rely on a certificate authority file being present as .Pa /etc/ssl/pkgca.pem and all signatures will be checked against it. Once the packing-list signature is checked, all individual packing elements diff --git a/usr.sbin/pkg_add/pkg_create.1 b/usr.sbin/pkg_add/pkg_create.1 index 3fd168200c7..e91554c2606 100644 --- a/usr.sbin/pkg_add/pkg_create.1 +++ b/usr.sbin/pkg_add/pkg_create.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pkg_create.1,v 1.84 2014/01/02 17:02:48 espie Exp $ +.\" $OpenBSD: pkg_create.1,v 1.85 2014/01/03 12:54:59 espie Exp $ .\" .\" Documentation and design originally from FreeBSD. All the code has .\" been rewritten since. We keep the documentation's notice: @@ -21,7 +21,7 @@ .\" [jkh] Took John's changes back and made some additional extensions for .\" better integration with FreeBSD's new ports collection. .\" -.Dd $Mdocdate: January 2 2014 $ +.Dd $Mdocdate: January 3 2014 $ .Dt PKG_CREATE 1 .Os .Sh NAME @@ -36,10 +36,10 @@ .Op Fl D Ar name Ns Op = Ns Ar value .Op Fl L Ar localbase .Op Fl M Ar displayfile -.Op Fl P Ar pkg-dependency +.Op Fl P Ar pkgpath Ns : Ns Ar pkgspec Ns : Ns Ar default .Op Fl s Ar signature-parameter .Op Fl U Ar undisplayfile -.Op Fl W Ar wantedlib +.Op Fl W Ar libspec .Fl d Ar desc .Fl D Ar COMMENT Ns = Ns Ar value .Fl D Ar PORTSDIR Ns = Ns Ar value @@ -95,14 +95,10 @@ records extra information in the packing-list, such as the existence of symlinks and hard links, computes and stores file checksums, and verifies that all special objects are properly annotated in the packing-list. .Pp -It will also check all -.Cm @wantlib -for reachability, by looking into all installed -.Cm @depend . +It will also check all required shared libraries +for reachability, by looking into all installed dependencies. It may also ask the ports tree for extra dependencies, -provided some other -.Cm @depend -refers to the same +provided some other dependency refers to the same .Ev BASE_PKGPATH .Po see @@ -110,9 +106,7 @@ see .Pc . The rationale is that those libraries must already be present for the package to build correctly, and thus be reachable through the -subset of -.Cm @depend -that are not pure +subset of dependencies that are not pure .Ev RUN_DEPENDS . .Pp The options are as follows: @@ -180,9 +174,11 @@ concatenated together. .It Fl L Ar localbase Record .Ar localbase -as the localbase used in the package. +as the localbase used in the package +.Po By default, -.Pa /usr/local . +.Pa /usr/local +.Pc . Packages built with another localbase can only be installed by using the same localbase in .Xr pkg_add 1 , @@ -202,10 +198,23 @@ Don't actually create a package. .It Fl o Ar dir Specify output directory for signing packages after the fact. Otherwise, unsigned packages will be replaced with signed packages. -.It Fl P Ar pkg-dependency -Specify a -.Cm @depend -dependency on the command line. +.It Fl P Ar pkgpath Ns : Ns Ar pkgspec Ns : Ns Ar default +Declare a dependency on a package matching +.Ar pkgspec +.Pq see Xr packages-specs 7 . +An appropriate package must be installed before this package may be +installed, and that package must be deinstalled before this package +is deinstalled. +The dependency also contains a +.Ar pkgpath +.Po +see +.Xr pkgpath 7 +.Pc +and a +.Ar default +package name, in case there is no listing of available packages. +.Pp .It Fl p Ar prefix Set .Ar prefix @@ -271,10 +280,26 @@ when deinstalling the package. Useful for reminders about stuff to clean up. .It Fl v Turn on verbose output. -.It Fl W Ar wantedlib -Specify a -.Cm @wantlib -requirement on the command line. +.It Fl W Ar libspec +Package needs a shared library to work. +.Ar libspec +is +.Sq name.major.minor +or +.Sq path/name.major.minor . +The package won't be installed unless a library with the same name, +the exact same major number and at least the same minor number can +be located. +A library without path is searched through dependent packages under the +same +.Ar localbase , +then in the system libraries under +.Pa /usr/lib +and +.Pa /usr/X11R6/lib . +A library with a path is only searched through dependent packages, +that path being relative to +.Ar localbase . .It Fl x Disable progress meter. .El @@ -303,10 +328,10 @@ next section. .Pp Directory names are denoted by a trailing slash. .Pp -There are a few annotations that can be inserted for better control. +There are some annotations that can be inserted for better control. All these commands start with an .Sq @ . -Here is a list: +The following annotations can be inserted manually: .Pp .Bl -tag -width Ds -compact .It Cm @ask-update Ar pkgspec Ar message @@ -332,9 +357,6 @@ Classical use case for postgresql: Use very sparingly. Most cases that seem to require manual updates just require a bit more thought. .Pp -.It Cm @arch Ar arches -List of architectures for which this package is intended. -.Pp .It Cm @bin Ar filename Describe the file as an .Ox @@ -373,30 +395,6 @@ Set the package current directory. All subsequent filenames will be assumed relative to .Ar pathname . .Pp -.It Xo -.Cm @depend -.Sm off -.Ar pkgpath : -.Ar pkgspec : -.Ar default -.Sm on -.Xc -Declare a dependency on a package matching -.Ar pkgspec -.Pq see Xr packages-specs 7 . -An appropriate package must be installed before this package may be -installed, and that package must be deinstalled before this package -is deinstalled. -The dependency also contains a -.Ar pkgpath -.Po -see -.Xr pkgpath 7 -.Pc -and a -.Ar default -package name, in case there is no listing of available packages. -.Pp .It Cm @dir Ar directoryname Create directory .Pa directoryname @@ -415,13 +413,6 @@ If does not begin with an @, same as .Dl name/ .Pp -.It Cm @display Ar name -Declare -.Pa name -as the file to be displayed at install time (see -.Fl M -above). -.Pp .It Cm @endfake Mark end of packing-list for .Xr pkg_add 1 @@ -885,28 +876,11 @@ and not during true deletions. Original location of the package, automatically recorded in installed packages by .Xr pkg_add 1 . -.Pp -.It Cm @wantlib Ar libspec -Package needs a shared library to work. -.Ar libspec -is -.Sq name.major.minor -or -.Sq path/name.major.minor . -The package won't be installed unless a library with the same name, -the exact same major number and at least the same minor number can -be located. -A library without path is searched through dependent packages under the -same -.Ar localbase , -then in the system libraries under -.Pa /usr/lib -and -.Pa /usr/X11R6/lib . -A library with a path is only searched through dependent packages, -that path being relative to -.Ar localbase . .El +See +.Xr package 5 +for other internal annotations that are automatically added by the +package tools. .Sh VARIABLE SUBSTITUTION AND FRAGMENT INCLUSION In packing-lists, installation, deinstallation and requirement scripts, description and message files, diff --git a/usr.sbin/pkg_add/pkg_info.1 b/usr.sbin/pkg_add/pkg_info.1 index 5c6f1c485a2..c32c4e0595b 100644 --- a/usr.sbin/pkg_add/pkg_info.1 +++ b/usr.sbin/pkg_add/pkg_info.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pkg_info.1,v 1.47 2011/11/25 09:30:08 espie Exp $ +.\" $OpenBSD: pkg_info.1,v 1.48 2014/01/03 12:54:59 espie Exp $ .\" .\" Documentation and design originally from FreeBSD. All the code has .\" been rewritten since. We keep the documentation's notice: @@ -15,7 +15,7 @@ .\" Jordan K. Hubbard .\" .\" -.Dd $Mdocdate: November 25 2011 $ +.Dd $Mdocdate: January 3 2014 $ .Dt PKG_INFO 1 .Os .Sh NAME @@ -114,6 +114,11 @@ will match any package that was compiled according to .Pa ${PORTSDIR}/x11/kde/base3 . .It Fl f Show the packing-list instructions for each package. +See +.Xr pkg_create 1 +and +.Xr package 5 +for the various annotations. .It Fl I Show the index entry for each package. .It Fl K