summaryrefslogtreecommitdiffstats
path: root/specs
diff options
context:
space:
mode:
authorP. J. McDermott <pjm@nac.net>2012-02-22 02:05:07 (EST)
committer P. J. McDermott <pjm@nac.net>2012-02-22 02:05:07 (EST)
commitcde62da0734d0bc1b00a787e07629108b04507f3 (patch)
tree7f63df05dc4a73988826ace977478a03c5019de2 /specs
parent672824c09b3a81c87ee80ca9ed0adf171d043796 (diff)
Move source package format to 'specs' directory.
Diffstat (limited to 'specs')
-rw-r--r--specs/source-package-format-1.0.txt183
1 files changed, 183 insertions, 0 deletions
diff --git a/specs/source-package-format-1.0.txt b/specs/source-package-format-1.0.txt
new file mode 100644
index 0000000..aa12f98
--- /dev/null
+++ b/specs/source-package-format-1.0.txt
@@ -0,0 +1,183 @@
+ABOUT THIS DOCUMENT
+===================
+
+This document describes version 1.0 of the format for software source packages.
+
+
+LEGAL NOTICE
+============
+
+Copyright (C) 2012 Patrick "P. J." McDermott
+
+This document may be reproduced, distributed, modified, and otherwise dealt in
+under the terms of the Expat/MIT License:
+http://www.jclark.com/xml/copying.txt
+
+
+SPECIFICATION STATUS
+====================
+
+This specification is in draft status. It is a work-in-progress and is subject
+to change. Comments and revisions are welcome.
+
+TODO
+----
+ * Finish describing binary package control fields.
+ * Describe the control file format.
+
+
+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.
+
+
+RATIONALE
+=========
+
+This source package format is modeled after the package format of the OpenBricks
+Embedded Linux Framework. However, this format more natively supports the
+building of multiple binary packages from one source package. Additionally,
+source packages in this format are intended to be maintained independently (like
+Debian packages are) rather than in one monolithic software repository (such as
+that of OpenBricks). In this and other respects, this format draws inspiration
+from Debian's source package formats.
+
+
+DIRECTORY STRUCTURE
+===================
+
+PROPOSAL 1
+----------
+
+This directory structure proposal has been declared defunct and removed from
+this document.
+
+PROPOSAL 2
+----------
+
+In this structure, all source and binary packaging files are kept in the same
+directory.
+
+Note that this directory structure is very functionally similar to that of
+Debian's source package formats.
+
+<pkgname>_<pkgver>-<pkgrev>/
+ +- <binpkg>.install
+ | A list of patterns to match files to be installed in a binary package.
+ +- <binpkg>.postinst
+ +- <binpkg>.postrm
+ +- <binpkg>.preinst
+ +- <binpkg>.prerm
+ +- build
+ | A makefile with target rules to build the binary package(s).
+ +- control
+ | Metadata about the source and binary packages.
+ +- 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>.<ext>
+ | Upstream source archive (for non-native packages).
+ \- src/
+ Package sources (for native packages).
+
+PROPOSAL 3
+----------
+
+This structure is functionally equivalent to that of proposal 2, however, files
+and metadata related to binary packages are organized into directories.
+
+<pkgname>_<pkgver>-<pkgrev>/
+ +- <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).
+ +- control
+ | Metadata about 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>.<ext>
+ | Upstream source archive (for non-native packages).
+ \- src/
+ Package sources (for native packages).
+
+
+CONTROL FILE FORMAT
+===================
+
+See documentation on Debian packaging.
+
+
+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 four-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.
+ - The string "any" to specify that the package cen be built for any binary
+ architecture and any application platform.
+ * 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)
+ * Recommends (optional)
+ * Suggests (optional)
+ * Pre-Depends (optional)
+ * Conflicts (optional)
+ * Provides (optional)
+ * Replaces (optional)
+ * Description (required)
+
+
+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.
+ * Maintainer (required)
+ The name and e-mail address of the package maintainer. This field must
+ follow the syntax of the "mailbox" symbol in RFC 822 section 6.1.
+ * Build-Depends (optional)
+ A list of packages that must be installed before the package can be built.
+ * Homepage
+ 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.