diff options
| -rw-r--r-- | specs/spf-2.0/about.mdwn | 22 | ||||
| -rw-r--r-- | specs/spf-2.0/buildsys.mdwn | 22 | ||||
| -rw-r--r-- | specs/spf-2.0/chapters | 6 | ||||
| -rw-r--r-- | specs/spf-2.0/fields.mdwn | 90 | ||||
| -rw-r--r-- | specs/spf-2.0/index.mdwn | 6 | ||||
| -rw-r--r-- | specs/spf-2.0/metadata.mdwn | 110 | ||||
| -rw-r--r-- | specs/spf-2.0/overview.mdwn | 246 | ||||
| -rw-r--r-- | specs/spf-2.0/scripts.mdwn | 11 | ||||
| -rw-r--r-- | specs/spf-2.0/sources.mdwn | 12 |
9 files changed, 520 insertions, 5 deletions
diff --git a/specs/spf-2.0/about.mdwn b/specs/spf-2.0/about.mdwn index 75743b6..1604e43 100644 --- a/specs/spf-2.0/about.mdwn +++ b/specs/spf-2.0/about.mdwn @@ -21,7 +21,7 @@ source package format: platform-specific. * Package building can now be configured by a `config` script. - There is now no need for any configuration logic in the `build` makefile. - See section 5 for rationale behind this design. + See $[sectlink][rationale] for rationale behind this design. - The list of binary packages that can be built from a source package no longer needs to be statically defined. * The source package hierarchy has been clarified to to indicate whether each @@ -36,7 +36,7 @@ source package format: requiring the `build` file to list all binary packages. - The user can choose to build all binary packages, only architecture-independent binary packages, or only architecture-independent - binary packages. See section 5 for rationale behind this design. + binary packages. See $[sectlink][rationale] 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 @@ -63,3 +63,21 @@ Scope [scope] This specification applies both to source packages and to the package building tools that interact with them. + + +Definitions [defs] +================== + +TODO + +source package + +binary package + +package sources + +source package directory + +package building work area, work area + +package building tool diff --git a/specs/spf-2.0/buildsys.mdwn b/specs/spf-2.0/buildsys.mdwn new file mode 100644 index 0000000..5f5e302 --- /dev/null +++ b/specs/spf-2.0/buildsys.mdwn @@ -0,0 +1,22 @@ +Configuration Script [config] +============================= + +TODO + + +Build Makefile [build] +====================== + +TODO + + +Build Work Area [work-area] +=========================== + +When building packages, a new directory named `tmp` shall be created in the +source package directory. In this directory, the package source code shall be +copied or unpacked into a directory called `src` and an installation destination +directory named `dest` shall be created. + +After all expected binary packages have been built, the work area (`tmp` and its +children) shall be removed. diff --git a/specs/spf-2.0/chapters b/specs/spf-2.0/chapters index 477249a..12c6811 100644 --- a/specs/spf-2.0/chapters +++ b/specs/spf-2.0/chapters @@ -1 +1,7 @@ about About this Manual +overview Directory Structure Overview +sources Sources +metadata Metadata +fields Control Fields +buildsys Build System +scripts Maintainer Scripts diff --git a/specs/spf-2.0/fields.mdwn b/specs/spf-2.0/fields.mdwn new file mode 100644 index 0000000..51a9415 --- /dev/null +++ b/specs/spf-2.0/fields.mdwn @@ -0,0 +1,90 @@ +Source Package Fields [fields-src] +================================== + +The fields in the source package metadata are: + + * `Maintainer` (required) + + The name and e-mail address of the package maintainer. This field must + follow the syntax of the `mailbox` symbol in RFC 5322 section 3.4. + + * `Build-Depends` (optional) + + A list of packages that must be installed before the package can be built. + + * `Homepage` (optional) + + The URL of the Web site for the package. Accessible at this site should be + origin source code and documentation and/or information. Though the + information in this field is machine-usable, the URL must not be surrounded + by angle brackets or any other characters. + + +Binary Package Fields [fields-bin] +================================== + +The fields in the binary package metadata are: + + * `Architecture` (required) + + A list of architectures for which this package may be built. The value may + be any one of the following: + + - The string `all` to specify that all of the provided files are + architecture-independent; + - The string `any` to specify that at least some of the provided files are + architecture-dependent; or + - A space-separated list of one or more real or wildcard binary architecture + strings to specify that at least some of the provided files are only + usable on systems of the named binary architecture(s). + + A "wildcard" binary architecture string is one in which one or two + components (called "wildcard components") is the string `any`. It shall be + considered to match any real binary architecture string for which the + non-wildcard components are equal. + + * `Platform` (required) + + A list of platforms for which this package may be built. The value may be + any one of the following: + + - The string `all` to specify that all of the provided files are + platform-independent; + - The string `any` to specify that at least some of the provided files are + platform-dependent; or + - A space-separated list of one or more platform strings to specify that at + least some of the provided files are only usable on systems of the named + platform(s). + + * `Essential` (optional) + + A flag to indicate whether the package is essential for the functioning of a + system on which it is installed. If this field is set to `yes`, opkg will + refuse to remove the package except when upgrading it. If this field is set + to any other value or is omitted, the package may be removed by a user. + + * `Depends` (optional) + + A list of packages that must be installed and configured before the package + may itself be configured. + + * `Recommends` (optional) + + * `Suggests` (optional) + + * `Pre-Depends` (optional) + + A list of packages that must be installed before the package may itself be + installed. + + * `Conflicts` (optional) + + * `Provides` (optional) + + * `Replaces` (optional) + + * `Description` (required) + + A description of the binary package. This is a multiline field. The first + line is a short synopsis, and all following lines are an extended + description. diff --git a/specs/spf-2.0/index.mdwn b/specs/spf-2.0/index.mdwn index 93e4529..451deb3 100644 --- a/specs/spf-2.0/index.mdwn +++ b/specs/spf-2.0/index.mdwn @@ -1,5 +1,5 @@ Status: DRAFT - Date: 2012-08-04 + Date: 2012-08-13 Revises: Source Package Format 1.0 @@ -9,8 +9,8 @@ Abstract This document describes version 2.0 of the format for software packages. -Status of This Document -======================= +Status +====== This specification is in `DRAFT` status. It is a work-in-progress and is subject to change. Comments and revisions are welcome. diff --git a/specs/spf-2.0/metadata.mdwn b/specs/spf-2.0/metadata.mdwn new file mode 100644 index 0000000..f5b08bd --- /dev/null +++ b/specs/spf-2.0/metadata.mdwn @@ -0,0 +1,110 @@ +Control Files [control] +======================= + +TODO + + +Change Log [changelog] +====================== + +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. 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+.-]+`.) + +`version` is the source package version. See $[sectlink][src-ver] 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. + + +Platform Configuration File Lists [platconf] +============================================ + +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/config/PLATFORM/PACKAGE-VERSION` or +`/usr/share/config/PLATFORM/PACKAGE`, where `PLATFORM` is the architecture +string denoting an application platform, `PACKAGE` is the name of the +configurable source package, and `VERSION` is 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 Version Identifier [src-ver] +=========================================== + +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]*`.) diff --git a/specs/spf-2.0/overview.mdwn b/specs/spf-2.0/overview.mdwn new file mode 100644 index 0000000..b4e6f09 --- /dev/null +++ b/specs/spf-2.0/overview.mdwn @@ -0,0 +1,246 @@ +Directory Tree [tree] +===================== + +The source package directory hierarchy can be summarized with the following +tree: + + <source-package-directory>/ + | No naming requirements are made for this directory. + +- <binpkg>.pkg/ + | | Required for each binary package after execution of "config". + | +- control + | | Required. + | | Metadata about the binary package. + | +- install + | | Required. + | | A list of patterns to match files to be installed in the binary + | | package. + | +- platconf + | | Optional. + | | A list of run-time configuration files. + | +- postinst + | | Optional. + | | A maintainer script to be executed after a binary package is + | | unpacked. + | +- postrm + | | Optional. + | | A maintainer script to be executed after a binary package is + | | removed. + | +- preinst + | | Optional. + | | A maintainer script to be executed before a binary package is + | | unpacked. + | \- prerm + | Optional. + | A maintainer script to be executed before a binary package is + | removed. + +- build + | Required after execution of "config". + | A makefile with target rules to build the binary package(s). + +- changelog + | Required. + | A log of changes made to the source package. + +- config + | Optional. + | A shell script to configure the package build. + +- control + | Required. + | Metadata about the source package. + +- copyright + | Required. + | Information about copyrights and licenses in the source package. + +- format + | Required. + | A magic file to identify the source format version. Should simply + | contain the string "2.0". + +- patches/ + | Optional. + | Patches to be applied to package sources before building. + +- <pkgname>-<pkgver>.tar.<ext> + | Optional. + | Upstream source archive (for non-native packages). + +- platconf + | Optional. + | A list of build-time configuration files. + \- src/ + Optional. + Package sources (for native packages). + + +Descriptions of Files [files] +============================= + +All of the following files are located under what is called a "source package +directory" (`<source-package-directory>` in the tree in $[sectlink][tree]). No +naming requirements are made for this directory. + +`<binpkg>.pkg/` [files-binpkg.pkg] +---------------------------------- + +After execution of the `config` file, for each binary package there must exist a +directory named `<binpkg>.pkg`, where `<binpkg>` is the name of the binary +package. + +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+.-]+`.) + +This directory contains metadata and scripts for a binary package. + +`<binpkg>.pkg/control` [files-binpkg.pkg-control] +------------------------------------------------- + +This file is required. + +This file contains control fields describing the binary package. See +$[sectlink][control] for the syntax of this file and $[sectlink][fields-bin] for +the list of control fields in this file. + +`<binpkg>.pkg/install` [files-binpkg.pkg-install] +------------------------------------------------- + +This file is required. + +This file contains a list of patterns to match files to be installed in the +binary package. + +Each line in this file is a pattern that is expanded to match files as explained +in [POSIX.1-2008, Shell & Utilities Volume, Section 2.6.6][posix-xcu-2.6.6]. + +A file or directory in the destination directory may not be matched by more than +one binary package's `install` file. The behavior of package building tools in +such a case is undefined. + +`<binpkg>.pkg/platconf` [files-binpkg.pkg-platconf] +--------------------------------------------------- + +This file is optional. Its presence indicates that a binary package is +platform-specific. + +This file contains a list of run-time configuration files to be installed in the +binary package. Files listed in this file shall not be listed in the binary +package's `install` file. + +See $[sectlink][platconf] for the syntax of this file. + +`<binpkg>.pkg/postinst` [files-binpkg.pkg-postinst] +--------------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed after a binary package is +unpacked. See $[sectlink][scripts] for more information about maintainer +scripts. + +`<binpkg>.pkg/postrm` [files-binpkg.pkg-postrm] +----------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed after a binary package is +removed. See $[sectlink][scripts] for more information about maintainer +scripts. + +`<binpkg>.pkg/preinst` [files-binpkg.pkg-preinst] +------------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed before a binary package is +unpacked. See $[sectlink][scripts] for more information about maintainer +scripts. + +`<binpkg>.pkg/prerm` [files-binpkg.pkg-prerm] +--------------------------------------------- + +This file is optional. + +This file is a maintainer script to be executed before a binary package is +removed. See $[sectlink][scripts] for more information about maintainer +scripts. + +`build` [files-build] +--------------------- + +After execution of the `config` file, this file must exist. + +This file is a makefile that controls the building of binary packages. See +$[sectlink][build] for requirements for this file. + +`changelog` [files-changelog] +----------------------------- + +This file is required. + +This file is a log of changes made to the source package. See +$[sectlink][changelog] for the format of this file. + +`config` [files-config] +----------------------- + +This file is optional. + +This file is a script in shell command language that configures the package +build. See $[sectlink][config] for requirements for this file. + +`control` [files-control] +------------------------- + +This file is required. + +This file contains control fields describing the source package. See +$[sectlink][control] for the syntax of this file and $[sectlink][fields-src] for +the list of control fields in this file. + +`copyright` [files-copyright] +----------------------------- + +This file is required. + +This file contains information about the copyrights in and licenses for the +source package. This specification currently makes no requirements for the +format of this file. + +`format` [files-format] +----------------------- + +This file is required. + +This "magic" file identifies the format version of the source package. For +packages in this version of the source package format, this file should simply +contain the string `2.0`. + +`patches/` [files-patches] +-------------------------- + +This directory is optional. + +This directory shall contain patches to be applied to package sources before +configuring and building any binary packages. + +See $[sectlink][patches] for the syntax of patch files. + +`<pkgname>-<pkgver>.tar.<ext>` [files-src-src-ver-tar-ext] +---------------------------------------------------------- + +TODO + +`platconf` [files-platconf] +--------------------------- + +This file is optional. Its presence indicates that each binary package is +platform-specific. + +This file contains a list of build-time configuration files to be installed into +the package building work area. + +See $[sectlink][platconf] for the syntax of this file. + +`src/` [files-src] +------------------ + +TODO + + +[posix-xcu-2.6.6]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_06 diff --git a/specs/spf-2.0/scripts.mdwn b/specs/spf-2.0/scripts.mdwn new file mode 100644 index 0000000..a32d899 --- /dev/null +++ b/specs/spf-2.0/scripts.mdwn @@ -0,0 +1,11 @@ +Maintainer Script Format [scripts-fmt] +====================================== + +TODO + + +Calling Standard [scripts-calling] +================================== + +TODO + diff --git a/specs/spf-2.0/sources.mdwn b/specs/spf-2.0/sources.mdwn new file mode 100644 index 0000000..7dec8d9 --- /dev/null +++ b/specs/spf-2.0/sources.mdwn @@ -0,0 +1,12 @@ +Patch Files [patches] +===================== + +Patch File Headers [patch-headers] +---------------------------------- + +TODO + +Patch File Format [patch-format] +-------------------------------- + +TODO |