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 for the syntax of control files.

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.