Source Package Format 2.0

Chapter 2 - Directory Structure Overview

2.1 Directory Tree

The source package directory hierarchy can be summarized with the following tree:

<source-package-directory>/
 |  No naming requirements are made for this directory.
 +- <binpkg>.pkg/
 |   |  Required for each binary package.
 |   +- control
 |   |      Required.
 |   |      Metadata about the binary package.
 |   +- docs
 |   |      Required for exactly one binary package.
 |   |      A list of source package documentation files to be provided by
 |   |      the package.
 |   +- platconf
 |   |      Optional.
 |   |      A list of run-time configuration files.
 |   +- postinst
 |   |      Optional.
 |   |      A maintainer script to be executed after a binary package is
 |   |      unpacked.
 |   +- postrm
 |   |      Optional.
 |   |      A maintainer script to be executed after a binary package is
 |   |      removed.
 |   +- preinst
 |   |      Optional.
 |   |      A maintainer script to be executed before a binary package is
 |   |      unpacked.
 |   \- prerm
 |          Optional.
 |          A maintainer script to be executed before a binary package is
 |          removed.
 +- build
 |      Required.
 |      A makefile with target rules to build the binary package(s).
 +- changelog
 |      Required.
 |      A log of changes made to the source package.
 +- control
 |      Required.
 |      Metadata about the source package.
 +- copyright
 |      Required.
 |      Information about copyrights and licenses in the source package.
 +- format
 |      Required.
 |      A magic file to identify the source format version.  Should simply
 |      contain the string "2.0".
 +- patches/
 |      Optional.
 |      Patches to be applied to package sources before building.
 +- <pkgname>-<pkgver>.orig.tar.<ext>
 |      Optional.
 |      Upstream source archive (for non-native packages).
 +- platconf
 |      Optional.
 |      A list of build-time configuration files.
 +- src/
 |      Optional.
 |      Package sources (for native packages).
 \- substvars
        Optional.
        Definitions of substitution variables.

2.2 Descriptions of Files

All of the following files are located under what is called a "source package directory" (<source-package-directory> in the tree in § 2.1). No naming requirements are made for this directory.

2.2.1 <binpkg>.pkg/

For each binary package there must exist a directory named <binpkg>.pkg, where <binpkg> is the name of the binary package. See § 4.5.2 for the requirements on binary package names.

This directory contains metadata and scripts for a binary package.

2.2.2 <binpkg>.pkg/control

This file is required.

This file contains control fields describing the binary package. See § 4.1 for the syntax of this file and § 5.2 for the list of control fields in this file.

2.2.3 <binpkg>.pkg/docs

This file is required for exactly one binary package.

This file contains a list of source package documentation files to be provided by the binary package.

See § 4.3 for more information about this file.

2.2.4 <binpkg>.pkg/platconf

This file is optional.

This file contains a list of run-time configuration files to be installed in the binary package.

See § 4.4 for the syntax of this file.

2.2.5 <binpkg>.pkg/postinst

This file is optional.

This file is a maintainer script to be executed after a binary package is unpacked. See § 8 for more information about maintainer scripts.

2.2.6 <binpkg>.pkg/postrm

This file is optional.

This file is a maintainer script to be executed after a binary package is removed. See § 8 for more information about maintainer scripts.

2.2.7 <binpkg>.pkg/preinst

This file is optional.

This file is a maintainer script to be executed before a binary package is unpacked. See § 8 for more information about maintainer scripts.

2.2.8 <binpkg>.pkg/prerm

This file is optional.

This file is a maintainer script to be executed before a binary package is removed. See § 8 for more information about maintainer scripts.

2.2.9 build

This file is required.

This file is a makefile that controls the building of binary packages. See § 7.1 for requirements for this file.

2.2.10 changelog

This file is required.

This file is a log of changes made to the source package. See § 4.2 for the format of this file.

2.2.11 control

This file is required.

This file contains control fields describing the source package. See § 4.1 for the syntax of this file and § 5.1 for the list of control fields in this file.

This file is required.

This file contains information about the copyrights in and licenses for the source package. This specification currently makes no requirements for the format of this file.

2.2.13 format

This file is required.

This "magic" file identifies the format version of the source package. For packages in this version of the source package format, this file should simply contain the string 2.0.

2.2.14 patches/

This directory is optional.

This directory shall contain patches to be applied to package sources before building any binary packages.

See § 3.1 for the syntax of patch files.

2.2.15 <pkgname>-<pkgver>.orig.tar<ext>

This file is optional. <pkgname> is the name of the source package, <pkgver> is the upstream version of the source package (see § 4.6), and <ext> is an optional file extension to indicate compression.

This file is a tar archive containing the source files for non-native packages. There must be exactly one top-level directory in the archive.

The file may be compressed, in which case <ext> must be one of the following:

If the file is not compress, <ext> must be empty.

2.2.16 platconf

This file is optional.

This file contains a list of build-time configuration files to be installed into the package building work area.

See § 4.4 for the syntax of this file.

2.2.17 src/

This directory is optional.

This directory contains the source files for native packages.

2.2.18 substvars

This file is optional.

This file contains control fields defining substitution variables. See § 4.1 for the syntax of this file and § 6 for more information about substitution variables.