diff options
| -rw-r--r-- | specs/source-package-format-1.0.txt | 349 |
1 files changed, 0 insertions, 349 deletions
diff --git a/specs/source-package-format-1.0.txt b/specs/source-package-format-1.0.txt deleted file mode 100644 index 7a06322..0000000 --- a/specs/source-package-format-1.0.txt +++ /dev/null @@ -1,349 +0,0 @@ - Title: Source Package Format 1.0 - Status: DRAFT - Date: 2012-03-08 - - -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. - -1.1. Remaining Tasks ---------------------- - - * Finish describing binary package control fields. - * Describe the control file format. - * Document `install` file syntax. - * Describe maintainer scripts. - * Refer to Debian Policy Manual Chapter 7 for syntax and types of package - relationship fields. - - -2. Abstract -============ - -This document describes version 1.0 of the format for software source 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. Rationale -============= - -This source package format is functionally similar to Debian's source package -formats. It differs from them most noticeably in that: - - * All source and binary package metadata is kept outside of the upstream - source directory structure, - * Each binary package has its metadata and scripts organized in its own - directory, - * Certain control file fields are omitted, and - * Packages may be configured at build time or at run time for hardware and - application platforms. - -Overall, this format is designed to be conducive to building packages for a -highly flexible embedded operating system. Additionally, source packages in -this format are intended to be maintained independently (like packages in Debian -and most other GNU/Linux distributions are) rather than in one monolithic -software repository (as is the case with most embedded operating system -distributions). - -It may not be the most efficient or maintainer-friendly format, but this is an -innovative first step and may be improved over time. - - -5. Directory Structure -======================= - -The source package directory hierarchy can be summarized with the following -tree: - - <source-package-directory>/ - +- <binpkg>.pkg/ - | +- control - | | Metadata about the binary package. - | +- install - | | A list of patterns to match files to be installed in the binary - | | package. - | +- postinst - | +- postrm - | +- preinst - | \- prerm - +- build - | A makefile with target rules to build the binary package(s). - +- changelog - | A log of changes made to the source package. - +- config - | A list of build-time and run-time configuration files. - +- control - | Metadata about the source package. - +- copyright - | Information about copyrights and licenses in the source package. - +- format - | A magic file to identify the source format version. Should simply - | contain the string "1.0". - +- patches/ - | Patches to be applied to package sources before building. - +- <pkgname>-<pkgver>.tar.<ext> - | Upstream source archive (for non-native packages). - \- src/ - Package sources (for native packages). - -`<source-package-directory>` is the directory in which all packaging work is -done. There are no constraints on the name of this directory. - -`<binpkg>` is the name of each binary package generated by the source package. - -`<pkgname>` is the name of the source package. - -`<pkgver>` is the upstream source version. - -`<ext>` is a compression format file extension. It must be one of the -following: - - * `gz` for the "gzip" algorithm. - * `bz2` for the "bzip2" algorithm. - * `lz` for the "LZMA" algorithm. - * `Z` for the "compress" algorithm. - - -6. Build File Format -===================== - -An executable file named `build` should direct the process of building one or -more binary packages from a source package. This file should be a makefile with -a target for each binary package (whose name is that of the binary package) and -a target for each build stamp (whose name is that of the build stamp file). - -6.1. Build Stamps ------------------- - -A build stamp is a file the existence of which indicates that one or more -packages were successfully built. It is located in the package building work -area directory, and its name ends in `.buildstamp`. - -In a makefile that directs the building of binary packages, each package target -should depend on one build stamp target. Actual building of packages should be -done in build stamp targets. After successfully building one or more binary -packages, a build stamp target should create its build stamp file in the work -area directory. - -6.2. Multiple and Split Binary Packages ----------------------------------------- - -Some source packages generate multiple binary packages from a single build of -the packaged software. In the build makefiles of such source packages, the -targets for these binary packages should all depend on the same build stamp -target. This is called a split binary package configuration. - -Some source packages generate a set of one or more binary packages that is built -independently of all other packages. In the build makefiles of such source -packages, the target or targets for this set of binary packages should depend on -a build stamp on which no other binary package targets depend. This is called a -multiple binary package configuration. - -Note that both configurations may be used in a single source package. - - -7. 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. - -It is recommended that single blank lines be used: - - * After the package name and version and before change entries, - * After change entries and before the maintainer and date, and - * Between groups of related change entries. - - -8. Configuration File List Format -================================== - -Platform-specific configuration files used by the source package at build time -or by the binary package(s) at run time should be listed in the file `config`. - -Each file must be described with an entry of the following format: - - type source destination - -`type` is the string `buildtime` for a file used at build time or `runtime` for -a file used at run time. - -`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 architcture 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. - - -9. Control File Format -======================= - -See [Debian Policy Manual section 5.1][DPM-5.1] for the syntax of control files. - -[DPM-5.1]: -<http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax> - - -10. 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. - - -11. 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. - - -12. 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. |