diff options
| -rw-r--r-- | specs/source-package-format-2.0.txt | 86 |
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 |