From cb44dbe27f3366f7c019d2f2e26b8e9579fa265f Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pjm@nac.net>
Date: Mon, 13 Aug 2012 22:19:11 -0400
Subject: Finish moving SPF 2.0 into a book.
Omitted (at least temporarily) are "Packaging Recommendations" and
"Example Files".
---
(limited to 'specs')
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
--
cgit v0.9.1