summaryrefslogtreecommitdiffstats
path: root/specs
diff options
context:
space:
mode:
authorP. J. McDermott <pjm@nac.net>2012-06-26 21:34:58 (EDT)
committer P. J. McDermott <pjm@nac.net>2012-06-26 21:34:58 (EDT)
commit6ead5b717b2ba0c8a28e34fd0504d9db99e3f96e (patch)
treec29aa3e868649c551dafbb019787d01fec5b3b01 /specs
parente63de847b074e5362da625056953538694240eeb (diff)
Begin draft of source package format 2.0 spec.
Diffstat (limited to 'specs')
-rw-r--r--specs/source-package-format-2.0.txt604
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