Status: DRAFT
Date: 2023-09-25
Obsoletes: Source Package Format 1.0

Abstract

This document describes version 2.0 of the format for software packages.

Status

This specification is in DRAFT status. It is a work-in-progress and is subject to change. Comments and revisions are welcome.

Although some sections have yet to be written, this specification is already implemented by package building tools and over 100 source packages since 2012. Any changes made to written sections will maintain compatibility with the existing format and implementations.

Occasionally, new optional elements of the format are added and existing limitations are relaxed. Such changes are made in tandem with corresponding support being added to package building tools. Source packages that make use of such new elements and relaxed limitations are responsible for ensuring that package building tools are new enough to support them, by listing such tools and minimum required versions in the Build-Depends control field (see § 5.1). Refer to the release notes of package building tools to identify the versions in which support is added for changes to this Source Package Format.

Legal Notice

Copyright © 2012, 2019-2021, 2023 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.

Contents

• 1 About this Manual
  • 1.1 Background
  • 1.2 Changes Since Version 1.0
  • 1.3 Rationale
  • 1.4 Scope
  • 1.5 Definitions
• 2 Directory Structure Overview
  • 2.1 Directory Tree
  • 2.2 Descriptions of Files
    • 2.2.1 <binpkg>.pkg/
    • 2.2.2 <binpkg>.pkg/control
    • 2.2.3 <binpkg>.pkg/docs
    • 2.2.4 <binpkg>.pkg/platconf
    • 2.2.5 <binpkg>.pkg/postinst
    • 2.2.6 <binpkg>.pkg/postrm
    • 2.2.7 <binpkg>.pkg/preinst
    • 2.2.8 <binpkg>.pkg/prerm
    • 2.2.9 build
    • 2.2.10 changelog
    • 2.2.11 control
    • 2.2.12 copyright
    • 2.2.13 format
    • 2.2.14 patches/
    • 2.2.15 <pkgname>-<pkgver>.orig.tar<ext>
    • 2.2.16 platconf
    • 2.2.17 src/
    • 2.2.18 substvars
• 3 Sources
  • 3.1 Patch Files
    • 3.1.1 Patch File Headers
    • 3.1.2 Patch File Format
• 4 Metadata
  • 4.1 Control Files
  • 4.2 Change Log
  • 4.3 Source Package Documentation File List
  • 4.4 Platform Configuration File Lists
  • 4.5 Package Names
    • 4.5.1 Source Packages
    • 4.5.2 Binary Package Names
  • 4.6 Source Package Version Identifier
• 5 Control Fields
  • 5.1 Source Package Fields
  • 5.2 Binary Package Fields
  • 5.3 Package Relationship Fields Syntax
• 6 Substitution Variables
  • 6.1 Variable Names
  • 6.2 Variable Substitutions
  • 6.3 Special Variables
  • 6.4 Defining Substitution Variables
• 7 Build System
  • 7.1 Build Makefile
  • 7.2 Build Work Area
  • 7.3 Environment Variables
    • 7.3.1 Package Variables
    • 7.3.2 Build and Host System Variables
    • 7.3.3 Toolchain Variables
• 8 Maintainer Scripts
  • 8.1 Maintainer Script Format
  • 8.2 Calling Standard