summaryrefslogtreecommitdiffstats
path: root/specs
diff options
context:
space:
mode:
Diffstat (limited to 'specs')
-rw-r--r--specs/source-package-format-2.0.txt86
1 files changed, 65 insertions, 21 deletions
diff --git a/specs/source-package-format-2.0.txt b/specs/source-package-format-2.0.txt
index 2b72f90..e5267a7 100644
--- a/specs/source-package-format-2.0.txt
+++ b/specs/source-package-format-2.0.txt
@@ -58,6 +58,9 @@ source package format:
binary packages. See section 5 for rationale behind this design.
* The source package version is no longer included in `control`.
- It is already given in the most recent entry in `changelog`.
+ * The version identifier syntax now encodes information about source archive
+ repacks and non-trunk distribution uploads.
+ - The syntax has been made strict to make parsing simple and deterministic.
5. Rationale
@@ -177,7 +180,7 @@ children) shall be removed.
All of the following files are located under what is called a "source package
directory" (`<source-package-directory>` in the tree in section 8). No naming
-requirements are made for this directory. See section 20.1 for a recommended
+requirements are made for this directory. See section 21.1 for a recommended
naming convention for this directory.
10.1. `<binpkg>.pkg/`
@@ -195,7 +198,7 @@ This directory contains metadata and scripts for a binary package.
This file is required.
This file contains control fields describing the binary package. See section 15
-for the syntax of this file and section 17 for the list of control fields in
+for the syntax of this file and section 19 for the list of control fields in
this file.
10.3. `<binpkg>.pkg/install`
@@ -231,7 +234,7 @@ See section 14 for the syntax of this file.
This file is optional.
This file is a maintainer script to be executed after a binary package is
-unpacked. See section 19 for more information about maintainer scripts.
+unpacked. See section 20 for more information about maintainer scripts.
10.6. `<binpkg>.pkg/postrm`
----------------------------
@@ -239,7 +242,7 @@ unpacked. See section 19 for more information about maintainer scripts.
This file is optional.
This file is a maintainer script to be executed after a binary package is
-removed. See section 19 for more information about maintainer scripts.
+removed. See section 20 for more information about maintainer scripts.
10.7. `<binpkg>.pkg/preinst`
------------------------------
@@ -247,7 +250,7 @@ removed. See section 19 for more information about maintainer scripts.
This file is optional.
This file is a maintainer script to be executed before a binary package is
-unpacked. See section 19 for more information about maintainer scripts.
+unpacked. See section 20 for more information about maintainer scripts.
10.8. `<binpkg>.pkg/prerm`
------------------------------
@@ -255,7 +258,7 @@ unpacked. See section 19 for more information about maintainer scripts.
This file is optional.
This file is a maintainer script to be executed before a binary package is
-removed. See section 19 for more information about maintainer scripts.
+removed. See section 20 for more information about maintainer scripts.
10.9. `build`
--------------
@@ -371,7 +374,8 @@ format:
`package` is the source package name.
-`version` is the source package version number.
+`version` is the source package version. See section 17 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
@@ -419,7 +423,47 @@ user's filesystem hierarchy.
TODO
-17. Source Package Metadata
+17. Source Package Version Identifier Syntax
+=============================================
+
+In general, the syntax of source package version identifiers is:
+
+ <pkgver>[+sip<siprev>][-<pkgrev>][+<dist>-<distrev>]
+
+`<pkgver>` is the version of the original upstream package or the native
+package. It may only consist of lowercase Latin letters, digits, periods, and
+tildes. 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. 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 installed into a distribution other than `trunk`, the
+string `+<dist>-<distrev>` must be appended to the end of 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]*`.)
+
+18. Source Package Metadata
============================
The fields in the source package metadata are:
@@ -444,7 +488,7 @@ The fields in the source package metadata are:
by angle brackets or any other characters.
-18. Binary Package Metadata
+19. Binary Package Metadata
============================
The fields in the binary package metadata are:
@@ -509,24 +553,24 @@ The fields in the binary package metadata are:
description.
-19. Maintainer Scripts
+20. Maintainer Scripts
=======================
-19.1. Maintainer Script Format
+20.1. Maintainer Script Format
-------------------------------
TODO
-19.2. Calling Standard
+20.2. Calling Standard
-----------------------
TODO
-20. Packaging Recommendations
+21. Packaging Recommendations
==============================
-20.1. Source Package Directory Naming
+21.1. Source Package Directory Naming
--------------------------------------
It is recommended that the name of the source package directory be simply the
@@ -534,7 +578,7 @@ name of the source package. Including the package version number or any part
thereof in the directory name is not recommended, as this number will likely
change over time.
-20.2. `build` File Generation
+21.2. `build` File Generation
------------------------------
For non-trivial packages, it is recommended that the `config` script generates a
@@ -549,7 +593,7 @@ However, it is not specified by POSIX.1 (and therefore cannot be expected to be
supported by all implementations). Furthermore, conditional logic goes beyond
the original design of the `make` utility.
-20.3. Dynamic Binary Package Generation
+21.3. Dynamic Binary Package Generation
----------------------------------------
For certain source packages, the set of binary packages to be built depends on
@@ -560,15 +604,15 @@ generated by the `config` script from template directories named
`<binpkg>.pkg.in/` or similar.
-21. Example Files
+22. Example Files
==================
In the following sections are some example files that might be used for the
-`opkg` source package. They observe the recommendation made in section 20.2 to
+`opkg` source package. They observe the recommendation made in section 21.2 to
make the `config` script generate a `build` makefile from an input `build.in`
file.
-21.1. Example `config` File
+22.1. Example `config` File
----------------------------
Following is an example `config` file:
@@ -586,7 +630,7 @@ Following is an example `config` file:
It detects whether the user intends to cross build the software and generates
appropriate `build` and `host` options for the software's `configure` script.
-21.2. Example `build.in` File
+22.2. Example `build.in` File
------------------------------
Following is an example `build.in` file:
@@ -638,7 +682,7 @@ Additionally, this file relies on the opkhelper utilities to perform tasks
related to the production of binary packages.
-22. Legal Notice
+23. Legal Notice
=================
Copyright (C) 2012 Patrick "P. J." McDermott