diff options
Diffstat (limited to 'specs/source-package-format-2.0.txt')
| -rw-r--r-- | specs/source-package-format-2.0.txt | 604 |
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 |