TODO
Changes made to the source package should be explained in the file changelog.
Each new package revision must be documented with an entry of the following format:
package (version) distributions
[zero or more blank lines]
* change details
[zero or more blank lines]
* more change details
more detailed change details
[zero or more blank lines]
-- maintainer date
package is the source package name. See § 4.5.1 for the requirements on source package names.
version is the source package version. See § 4.6 for the syntax of source package version identifiers.
distributions is a list of distributions into which the package should be installed when uploaded to the package archive. The list consists of one or more distribution names, separated by spaces.
maintainer is the name and e-mail address of the package maintainer. This field must follow the syntax of the mailbox symbol of RFC 5322 section 3.4.
date is the date of packaging. This field must follow the syntax of the date-time symbol of RFC 5322 section 3.3. The following date(1) command gives the current date and time in the correct format:
$ LC_ALL='POSIX' date '+%a, %d %b %Y %H:%M:%S %z'
One binary package built from a source package provides documentation files about the source package. This binary package is identified by the presence of a <binpkg>.pkg/docs file, where <binpkg> is the name of the binary package.
All other binary packages built from the same source package must declare a hard run-time dependency (either Depends or Pre-Depends) on this binary package.
At least the copyright and changelog files are provided by the binary package. If found in the source package directory, a file named README is also provided.
Additional documentation files may be listed in <binpkg>.pkg/docs. Each file must be identified with an entry of the following format:
source destination
source is the path to the file, relative to the build work area (see § 7.2).
destination is the path to which the file should be installed, relative to the source package documentation directory in the user's filesystem hierarchy.
Platform-specific configuration files used by the source package at build time shall be listed in the platconf file. Platform-specific configuration files used by the binary package(s) at run time shall be listed in the <binpkg>.pkg/platconf file.
Source packages with a platconf file, a <binpkg>.pkg/platconf file, or both shall list in their build-time dependencies a package (real or virtual) that provides the listed platform-specific configuration files.
Each configuration file must be described with an entry of the following format:
source destination
source is the path to the file, relative to the platform configuration directory -- either /usr/share/platconf/PLATFORM/PACKAGE_VERSION or /usr/share/platconf/PLATFORM/PACKAGE, where PLATFORM is the architecture string denoting an application platform, PACKAGE is the name of the configurable source package, and VERSION is a shell command language pattern matching the upstream version of the configurable source package.
destination is the path (file or directory) to which the file should be copied. For a file used at build time, it is a path relative to the package building work area. For a file used at run time, it is an absolute path in the user's filesystem hierarchy.
Source package names may only consist of lowercase Latin letters, digits, plus and minus signs, and periods. Names must be at least two characters long and must start with either a letter or a digit. (A regular expression for this is [a-z0-9][a-z0-9+.-]+.)
Source package names may not begin with the reserved string "src-". This limitation is expected to be removed in a future draft of this version of this Source Package Format.
Binary package names may only consist of lowercase Latin letters, digits, plus and minus signs, and periods. Names must be at least two characters long and must start with either a letter or a digit. (A regular expression for this is [a-z0-9][a-z0-9+.-]+.)
Binary package names may not begin with the reserved string "src-". This limitation is expected to be removed in a future draft of this version of this Source Package Format.
A binary package clean name is a binary package name with all plus and minus signs and periods removed. No two binary packages built from the same source package may have the same clean name. This limitation is expected to be removed in a future draft of this version of this Source Package Format.
In general, the syntax of source package version identifiers is:
[<epoch>:]<pkgver>[+sip<siprev>][-<pkgrev>][+<dist>~<distrev>][~bpu<distnum>+<bpurev>]
<epoch> should almost always be omitted, in which case it is effectively zero. It may be used when the upstream version numbering scheme changes or when one or more binary packages are migrated to a different source package with a different upstream version numbering scheme. It must be a string of one or more digits, the first of which must be greater than or equal to 1. (A regular expression for this is [1-9][0-9]*.)
<pkgver> is the version of the original upstream package or the native package. It may only consist of lowercase Latin letters, digits, periods, tildes, and plus signs. It must be at least one character long. (A regular expression for this is [0-9a-z.~+]+.)
If the upstream source archive needs to be repacked with certain changes for compliance with the Software Inclusion Policy, the string +sip<siprev> must be appended to <pkgver>. <siprev> is a number that should be incremented on each repack while <pkgver> remains constant. It should be reset to 1 for the first repack of a new upstream source archive. It must be a string of one or more digits, the first of which must be greater than or equal to 1. (A regular expression for this is [1-9][0-9]*.)
<pkgrev> is the version of the distribution packaging. It is optional and should be omitted for native packages. It should be incremented on each revision of packaging while <pkgver> and <siprev> remain constant. It should be reset to 1 for the first revision of packaging for a new upstream package version or source archive repack if the package is to be installed into the trunk distribution; otherwise it should be set to 0 and never incremented. It must be a string of one or more digits. (A regular expression for this is [0-9]+.)
If the package is to be installed into a distribution other than trunk, the string +<dist>~<distrev> must be included in the version identifier. <dist> is the distribution into which the package is to be installed, may only consist of lowercase Latin letters and digits, and must be at least one character long. (A regular expression for this is [a-z0-9]+.) <distrev> is a number that should be incremented on each upload to <dist> while <pkgver>, <siprev>, and <pkgrev> remain constant. It should be reset to 1 for the first upload to <dist> of a new upstream package version, source archive repack, or distribution packaging revision. It must be a string of one or more digits, the first of which must be greater than or equal to 1. (A regular expression for this is [1-9][0-9]*.)
If the package is to be backported from trunk or another distribution into a different distribution other than trunk, the string ~bpu<distnum>+<bpurev> must be included in the version identifier. <distnum> is a numeric distribution version identifier for the distribution to which the package is backported. It must be a string of one or more digits, the first of which must be greater than or equal to 1. (A regular expression for this is [1-9][0-9]*.) <bpurev> is a number that should be incremented on each backport to distribution version <distnum> while <pkgver>, <siprev>, <pkgrev>, <dist>, and <distrev> remain constant. It should be reset to 1 for the first backport to distribution version <distnum> of a new upstream package version, source archive repack, distribution packaging revision, or installation into a distribution other than trunk. It must be a string of one or more digits, the first of which must be greater than or equal to 1. (A regular expression for this is [1-9][0-9]*.)