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
----

  - Design a way to support package configurations.


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).


BINARY PACKAGE METADATA
=======================

Refer to documentation for dpkg and opkg.


SOURCE PACKAGE METADATA
=======================

The format of the source package metadata is to be determined.  It should
resemble either Debian package control file syntax or OpenBricks package
metadata file (shell script) syntax.

Metadata will include information necessary to maintain the source package and
build the binary package(s).  Fields will include the upstream source, build
dependencies, and maintainer contact information.