Begin draft of source package format 2.0 spec.

1 files changed, 604 insertions, 0 deletions

diff --git a/specs/source-package-format-2.0.txt b/specs/source-package-format-2.0.txt
new file mode 100644
index 0000000..de29985
--- /dev/null
+++ b/specs/source-package-format-2.0.txt
@@ -0,0 +1,604 @@
+    Title: Source Package Format 2.0
+    Status: DRAFT
+    Date: 2012-06-26
+    Revises: Source Package Format 1.0
+
+
+1.  Status of This Document
+===========================
+
+This specification is in `DRAFT` status.  It is a work-in-progress and is
+subject to change.  Comments and revisions are welcome.
+
+
+2.  Abstract
+============
+
+This document describes version 2.0 of the format for software packages.
+
+
+3.  Background
+==============
+
+A source package consists of software source code, a build system, and package
+metadata.  From it is built one or more binary packages, which can be installed
+into an operating system.
+
+
+4.  Changes Since Version 1.0
+=============================
+
+TODO
+
+
+5.  Rationale
+=============
+
+TODO
+
+
+6.  Scope
+=========
+
+This specification applies both to source packages and to the package building
+tools that interact with them.
+
+
+7.  Definitions
+===============
+
+TODO
+
+source package
+
+binary package
+
+package sources
+
+source package directory
+
+package building work area, work area
+
+package building tool
+
+
+8.  Source Package Directory Structure Summary
+==============================================
+
+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).
+
+
+9.  Package Building 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.
+
+
+10.  Descriptions of Files
+==========================
+
+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 19.1 for a recommended
+naming convention for this directory.
+
+10.1.  `<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.
+
+This directory contains metadata and scripts for a binary package.
+
+10.2.  `<binpkg>.pkg/control`
+-----------------------------
+
+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
+this file.
+
+10.3.  `<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.
+
+10.4.  `<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 section 14 for the syntax of this file.
+
+10.9.  `build`
+--------------
+
+After execution of the `config` file, this file must exist.
+
+This file is a makefile that controls the building of binary packages.  See
+section 12 for requirements for this file.
+
+10.10.  `changelog`
+-------------------
+
+This file is required.
+
+This file is a log of changes made to the source package.  See section 13 for
+the format of this file.
+
+10.11.  `config`
+----------------
+
+This file is optional.
+
+This file is a script in shell command language that configures the package
+build.  See section 11 for requirements for this file.
+
+10.12.  `control`
+-----------------
+
+This file is required.
+
+This file contains control fields describing the source package.  See section 15
+for the syntax of this file and section 16 for the list of control fields in
+this file.
+
+10.13.  `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.
+
+10.14.  `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`.
+
+10.15.  `patches/`
+------------------
+
+This directory is optional.
+
+This directory shall contain patches to be applied to package sources before
+configuring and building any binary packages.
+
+See section 15 for the syntax of patch files.
+
+10.16.  `<pkgname>-<pkgver>.tar.<ext>`
+--------------------------------------
+
+TODO
+
+10.17.  `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 section 14 for the syntax of this file.
+
+10.18.  `src/`
+--------------
+
+TODO
+
+
+11.  Package Configuration Script Format
+========================================
+
+TODO
+
+
+12.  Build File Format
+======================
+
+TODO
+
+
+13.  Change Log Format
+======================
+
+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)
+    [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.
+
+`version` is the source package version number.
+
+`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.
+
+
+14.  Platform Configuration File List Format
+============================================
+
+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.
+
+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.
+
+
+15.  Patch File Syntax
+======================
+
+
+16.  Control File Format
+========================
+
+TODO
+
+
+17.  Source Package Metadata
+============================
+
+The fields in the source package metadata are:
+
+  * `Source` (required)  
+    The name of the source package.  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.
+
+  * `Version` (required)
+    The version number of the package.  The format is:
+    
+        <upstream_version>[-<package_revision>]
+    
+    `<upstream_version>` is the version of the original upstream package, if
+    any.
+    
+    `<package_revision>` is the version of the distribution packaging.  It is
+    optional and should be omitted for native packages.  It should be
+    incremented for each uploaded revision of packaging for the same upstream
+    package version.  It should be reset for the first uploaded revision of
+    packaging for a new upstream package version.
+
+  * `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.
+
+
+18.  Binary Package Metadata
+============================
+
+The fields in the binary package metadata are:
+
+  * `Package` (required)  
+    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.
+
+  * `Architecture` (required)  
+    The names of the architectures for which this package is built.  The list of
+    names may consist of values selected from the following:
+
+      - A three-tuple binary architecture name to specify that the package can
+        be built for the binary architecture and any application platform.
+      - An application platform architecture name to specify that the package
+        can be built for the application platform and its associated binary
+        architecture.
+
+    Alternatively, the list may consist solely of one of the following values:
+
+      - The string `all` to specify that the package can be built on any binary
+        architecture and any application platform and can then be installed on
+        binary architectures and/or application platforms other than those on
+        which it is built.  This value should be used for packages that provide
+        only architecture- and platform-independent files, such as common shell
+        scripts or data.
+      - The string `any` to specify that the package can be built for any binary
+        architecture and any application platform.  This value should be used
+        for packages that provide architecture- and/or platform-dependent files
+        that can be built and run on any architecture and platform, such as
+        portably-written C programs.
+
+  * `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.
+
+
+19.  Packaging Recommendations
+==============================
+
+19.1.  Source Package Directory Naming
+--------------------------------------
+
+It is recommended that the name of the source package directory be simply the
+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.
+
+19.2.  `build` File Generation
+------------------------------
+
+For non-trivial packages, it is recommended that the `config` script generates a
+`build` makefile from some input template, named `build.in` or something
+similar.  This is similar to the way that a `configure` script generated by GNU
+Autoconf will produce a `Makefile` from `Makefile.in`.
+
+With such makefile generation, the `build` file need not contain any conditional
+logic (e.g. to test for cross building or to enable certain software features).
+Such logic is supported by certain implementations of `make` including GNU Make.
+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.
+
+19.3.  Dynamic Binary Package Generation
+----------------------------------------
+
+For certain source packages, the set of binary packages to be built depends on
+the build configuration.  For example, the target architecture of a cross
+compiler may be embedded in the name of the providing binary package.  In such
+cases it is recommended that binary package directories and their files be
+generated by the `config` script from template directories named
+`<binpkg>.pkg.in/` or similar.
+
+
+20.  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 19.2 to
+make the `config` script generate a `build` makefile from an input `build.in`
+file.
+
+20.1.  Example `config` File
+----------------------------
+
+Following is an example `config` file:
+
+    #! /bin/sh
+    
+    if [ "${OH_BUILD_ARCH_GNU}" = "${OH_HOST_ARCH_GNU}" ]; then
+        ARCH_OPTS=
+    else
+        ARCH_OPTS="--build=${OH_BUILD_ARCH_GNU} --host=${OH_HOST_ARCH_GNU}"
+    fi
+    
+    sed -e "s&@ARCH_OPTS@&${ARCH_OPTS}&" build.in > build
+
+It detects whether the user intends to cross build the software and generates
+appropriate `build` and `host` options for the software's `configure` script.
+
+20.2.  Example `build.in` File
+------------------------------
+
+Following is an example `build.in` file:
+
+    #! /usr/bin/make -f
+    
+    PKGS_ARCH = opkg libopkg.1 libopkg.1-dbg
+    PKGS_INDEP = opkg-doc libopkg.1-dev
+    PKG_COMMON = libopkg.1
+    
+    configure.stamp: configure
+        cd src && ./configure --prefix=/usr @ARCH_OPTS@ \
+            --disable-static --disable-curl --disable-ssl-curl --disable-gpg
+        touch $@
+    
+    build.stamp: configure.stamp
+        cd src && make -j $${JOBS:-1}
+        touch $@
+    
+    install-arch.stamp: build.stamp
+        cd src && make DESTDIR=$${PWD}/../dest install
+        rm -Rf dest/usr/include dest/usr/share/man
+        touch $@
+    
+    install-indep.stamp: build.stamp
+        cd src && make DESTDIR=$${PWD}/../dest install-data-am
+        cd src && make DESTDIR=$${PWD}/../dest install-man
+        touch $@
+    
+    binary-arch: install-arch.stamp
+        oh-strip -gl /usr/lib/libopkg.so.1.0.0
+        oh-installfiles $(PKGS_ARCH)
+        oh-installdocs $(PKG_COMMON)
+        oh-gencontrol $(PKGS_ARCH)
+        oh-buildopk $(PKGS_ARCH)
+    
+    binary-indep: install-indep.stamp
+        oh-installfiles $(PKGS_INDEP)
+        oh-installdocs $(PKG_COMMON)
+        oh-gencontrol $(PKGS_INDEP)
+        oh-buildopk $(PKGS_INDEP)
+    
+    binary: binary-arch binary-indep
+    
+    clean:
+
+It has the required `binary`, `binary-arch`, and `binary-indep` targets, along
+with targets to configure, build, and install the packaged software.  It makes
+use of build stamps to record that certain stages of the binary package build
+process are completed.
+
+Additionally, this file relies on the opkhelper utilities to perform tasks
+related to the production of binary packages.
+
+
+21.  Legal Notice
+=================
+
+Copyright (C) 2012 Patrick "P. J." McDermott
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+[posix-xcu-2.6.6]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_06