summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--specs/source-package-format-1.0.txt349
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.