path: root/specs/source-package-format-1.0.txt

    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][DPM-5.1] for the syntax of control files.

[DPM-5.1]:
<http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax>


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.