document the package(5) format.

Some tweaks by jmc@

2 files changed, 124 insertions, 2 deletions

diff --git a/usr.sbin/pkg_add/Makefile b/usr.sbin/pkg_add/Makefile
index 2eb9948114b..e4a1eaa55a5 100644
--- a/usr.sbin/pkg_add/Makefile
+++ b/usr.sbin/pkg_add/Makefile
@@ -1,9 +1,10 @@
-# $OpenBSD: Makefile,v 1.31 2005/09/17 09:30:34 espie Exp $
+# $OpenBSD: Makefile,v 1.32 2005/09/18 00:54:28 espie Exp $
 
 .include <bsd.own.mk>
 
 MAN=pkg_add.1 pkg_info.1 pkg_create.1 pkg_delete.1 pkg_merge.1 \
-	pkg.1 pkg_mklocatedb.1
+	pkg.1 pkg_mklocatedb.1 package.5
+
 POD2MAN=/usr/bin/pod2man
 
 PACKAGES= \
diff --git a/usr.sbin/pkg_add/package.5 b/usr.sbin/pkg_add/package.5
new file mode 100644
index 00000000000..525380a961c
--- /dev/null
+++ b/usr.sbin/pkg_add/package.5
@@ -0,0 +1,121 @@
+.\"	$OpenBSD: package.5,v 1.1 2005/09/18 00:54:29 espie Exp $
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.Dd September 17, 2005
+.Dt PACKAGE 5
+.Os
+.Sh NAME
+.Nm package
+.Nd format for
+.Ox
+binary packages
+.Sh DESCRIPTION
+Binary packages for
+.Ox
+can be created using
+.Xr pkg_create 1
+and
+.Xr pkg_merge 1 ,
+and are usually manipulated using
+.Xr pkg_add 1 ,
+.Xr pkg_merge 1 ,
+.Xr pkg_mklocatedb 1 ,
+or
+.Xr pkg_info 1 .
+.Pp
+The basic underlying format is an archive following the UStar specification
+that can be handled with
+.Xr tar 1
+and compressed using
+.Xr gzip 1 .
+.Pp
+Package names always end in
+.Dq tgz ;
+the file name itself should conform to
+.Xr packages-specs 7 .
+.Pp
+Note that the base distribution tarballs of
+.Ox
+(e.g.\&
+.Pa baseXXX.tgz ,
+.Pa compXXX.tgz ,
+\&...) are not binary packages fit for
+.Xr pkg_add 1 .
+.Pp
+All types of archive contents can be present in a package,
+including files, directories, hardlinks, symlinks, fifos, block and character
+devices.
+.Pp
+A special extension to the format, dubbed fat packages, is described in
+the next section.
+.Pp
+In order to allow just-in-time extraction,
+packages always begin with a table of contents, named
+.Pa +CONTENTS .
+This table of contents can be read using the API described in
+.Xr OpenBSD::PackingList 7 .
+.Pp
+All the remaining information in the archive should be referenced in
+the packing-list, including all relevant information: symlinks destinations,
+special permissions, and file owners.
+See
+.Xr pkg_create 1
+for annotation details.
+.Pp
+This table of contents is always followed by a few special files, some of
+which are optional: the package description (+DESC), an installation script
+(+INSTALL), a display message (+MESSAGE), etc.
+.Pp
+The Ustar format has some limitations with respect to file names.
+Accordingly, the package tools will replace very long names with
+.Pa LongName#n
+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 FAT PACKAGES DESCRIPTION
+The
+.Xr pkg_merge 1
+command can create fat packages, which coalesce several normal packages in
+a single Ustar archive, by interleaving their contents.
+.Pp
+Other tools, such as
+.Xr pkg_add 1 ,
+are aware of fat packages and can handle them transparently.
+.Pp
+In a fat package, every item has a small prefix that identifies the
+original package.
+For instance, after merging two packages, the package will usually
+begin with
+.Pa a/+CONTENTS
+and
+.Pa b/+CONTENTS .
+Individual items will then begin with
+.Pa ab/file ,
+for a file common to both packages;
+.Pa a/file
+for a file belonging to the first package;
+and
+.Pa b/file
+for a file belonging to the second package.
+.Sh SEE ALSO
+.Xr pkg_add 1 ,
+.Xr pkg_create 1 ,
+.Xr pkg_info 1 ,
+.Xr pkg_merge 1 ,
+.Xr packages 7 ,
+.Xr packages-specs 7
+.Sh STANDARDS
+Packages are valid gzip'ed Ustar archives that can be extracted using
+.Xr tar 1 .
+In particular, hardlink names should be valid, and all items will
+extract to different names.
+However, it may be a bit difficult to make sense of the package contents
+without peeking at the packing-list.