From cde62da0734d0bc1b00a787e07629108b04507f3 Mon Sep 17 00:00:00 2001 From: P. J. McDermott Date: Wed, 22 Feb 2012 02:05:07 -0500 Subject: Move source package format to 'specs' directory. --- (limited to 'specs/source-package-format-1.0.txt') 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. + +_-/ + +- .install + | A list of patterns to match files to be installed in a binary package. + +- .postinst + +- .postrm + +- .preinst + +- .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. + +- _. + | 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. + +_-/ + +- .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. + +- _. + | 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. -- cgit v0.9.1