.\"	$OpenBSD: package.5,v 1.3 2006/01/13 11:50:31 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 3p .
.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.