Move source package format to 'specs' directory.

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.