summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--specs/source-package-format-1.0.txt77
1 files changed, 24 insertions, 53 deletions
diff --git a/specs/source-package-format-1.0.txt b/specs/source-package-format-1.0.txt
index aa12f98..5b7008f 100644
--- a/specs/source-package-format-1.0.txt
+++ b/specs/source-package-format-1.0.txt
@@ -1,10 +1,10 @@
-ABOUT THIS DOCUMENT
+About This Document
===================
This document describes version 1.0 of the format for software source packages.
-LEGAL NOTICE
+Legal Notice
============
Copyright (C) 2012 Patrick "P. J." McDermott
@@ -14,7 +14,7 @@ under the terms of the Expat/MIT License:
http://www.jclark.com/xml/copying.txt
-SPECIFICATION STATUS
+Specification Status
====================
This specification is in draft status. It is a work-in-progress and is subject
@@ -24,9 +24,10 @@ TODO
----
* Finish describing binary package control fields.
* Describe the control file format.
+ * Describe the formats of the config and changelog files.
-BACKGROUND
+Background
==========
A source package consists of software source code, a build system, and package
@@ -34,7 +35,7 @@ metadata. From it is built one or more binary packages, which can be installed
into an operating system.
-RATIONALE
+Rationale
=========
This source package format is modeled after the package format of the OpenBricks
@@ -46,51 +47,9 @@ that of OpenBricks). In this and other respects, this format draws inspiration
from Debian's source package formats.
-DIRECTORY STRUCTURE
+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
@@ -104,8 +63,14 @@ and metadata related to binary packages are organized into directories.
| \- 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".
@@ -117,13 +82,13 @@ and metadata related to binary packages are organized into directories.
Package sources (for native packages).
-CONTROL FILE FORMAT
+Control File Format
===================
See documentation on Debian packaging.
-BINARY PACKAGE METADATA
+Binary Package Metadata
=======================
The fields in the binary package metadata are:
@@ -135,8 +100,8 @@ The fields in the binary package metadata are:
* 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.
+ - 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.
@@ -153,16 +118,22 @@ The fields in the binary package metadata are:
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.
-SOURCE PACKAGE METADATA
+Source Package Metadata
=======================
The fields in the source package metadata are: