ubuntu-policy.txt

This manual describes the policy requirements for the Ubuntu distribution. This includes the struc

                           Ubuntu Policy Manual
                           --------------------

                      The Debian Policy Mailing List

                    The Ubuntu Developers Mailing List

                    version 3.8.0.1ubuntu4, 2008-10-20


-------------------------------------------------------------------------------


Abstract
--------

     This manual describes the policy requirements for the Ubuntu
     distribution.  This includes the structure and contents of the Ubuntu
     archive and several design issues of the operating system, as well as
     technical requirements that each package must satisfy to be included
     in the distribution.  It is derived from the Debian Policy Manual.


Copyright Notice
----------------

     Copyright (C) 1996,1997,1998 Ian Jackson and Christian Schwarz.

     This manual is free software; you may redistribute it and/or modify it
     under the terms of the GNU General Public License as published by the
     Free Software Foundation; either version 2, or (at your option) any
     later version.

     This is distributed in the hope that it will be useful, but _without
     any warranty_; without even the implied warranty of merchantability or
     fitness for a particular purpose.  See the GNU General Public License
     for more details.

     A copy of the GNU General Public License is available as
     `/usr/share/common-licenses/GPL' in the Debian GNU/Linux distribution
     or on the World Wide Web at the GNU General Public Licence
     (http://www.gnu.org/copyleft/gpl.html).  You can also obtain it by
     writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth
     Floor, Boston, MA 02110-1301, USA.


-------------------------------------------------------------------------------


Contents
--------

     1.        About this manual
     1.1.      Scope
     1.2.      New versions of this document
     1.3.      Authors and Maintainers
     1.4.      Related documents

     2.        The Ubuntu Archive
     2.1.      The Ubuntu Licensing Policy
     2.2.      Categories
     2.2.1.         The main category
     2.2.2.         The restricted category
     2.2.3.         The universe category
     2.2.4.         The multiverse category
     2.3.      Copyright considerations
     2.4.      Sections
     2.5.      Priorities

     3.        Binary packages
     3.1.      The package name
     3.2.      The version of a package
     3.2.1.         Version numbers based on dates
     3.3.      The maintainer of a package
     3.4.      The description of a package
     3.4.1.         The single line synopsis
     3.4.2.         The extended description
     3.5.      Dependencies
     3.6.      Virtual packages
     3.7.      Base system
     3.8.      Essential packages
     3.9.      Maintainer Scripts
     3.9.1.         Prompting in maintainer scripts

     4.        Source packages
     4.1.      Standards conformance
     4.2.      Package relationships
     4.3.      Changes to the upstream sources
     4.4.      Ubuntu changelog: `debian/changelog'
     4.4.1.         Alternative changelog formats
     4.5.      Copyright: `debian/copyright'
     4.6.      Error trapping in makefiles
     4.7.      Time Stamps
     4.8.      Restrictions on objects in source packages
     4.9.      Main building script: `debian/rules'
     4.9.1.         `debian/rules' and `DEB_BUILD_OPTIONS'
     4.10.     Variable substitutions: `debian/substvars'
     4.11.     Optional upstream source location: `debian/watch'
     4.12.     Generated files list: `debian/files'
     4.13.     Convenience copies of code
     4.14.     Source package handling: `debian/README.source'

     5.        Control files and their fields
     5.1.      Syntax of control files
     5.2.      Source package control files -- `debian/control'
     5.3.      Binary package control files -- `DEBIAN/control'
     5.4.      Debian source control files -- `.dsc'
     5.5.      Debian changes files -- `.changes'
     5.6.      List of fields
     5.6.1.         `Source'
     5.6.2.         `Maintainer'
     5.6.3.         `Uploaders'
     5.6.4.         `Changed-By'
     5.6.5.         `Section'
     5.6.6.         `Priority'
     5.6.7.         `Package'
     5.6.8.         `Architecture'
     5.6.9.         `Essential'
     5.6.10.        Package interrelationship fields: `Depends',
                    `Pre-Depends', `Recommends', `Suggests', `Breaks',
                    `Conflicts', `Provides', `Replaces', `Enhances'
     5.6.11.        `Standards-Version'
     5.6.12.        `Version'
     5.6.13.        `Description'
     5.6.14.        `Distribution'
     5.6.15.        `Date'
     5.6.16.        `Format'
     5.6.17.        `Urgency'
     5.6.18.        `Changes'
     5.6.19.        `Binary'
     5.6.20.        `Installed-Size'
     5.6.21.        `Files'
     5.6.22.        `Closes'
     5.6.23.        `Launchpad-Bugs-Fixed'
     5.6.24.        `Homepage'
     5.7.      User-defined fields

     6.        Package maintainer scripts and installation procedure
     6.1.      Introduction to package maintainer scripts
     6.2.      Maintainer scripts idempotency
     6.3.      Controlling terminal for maintainer scripts
     6.4.      Exit status
     6.5.      Summary of ways maintainer scripts are called
     6.6.      Details of unpack phase of installation or upgrade
     6.7.      Details of configuration
     6.8.      Details of removal and/or configuration purging

     7.        Declaring relationships between packages
     7.1.      Syntax of relationship fields
     7.2.      Binary Dependencies - `Depends', `Recommends', `Suggests',
               `Enhances', `Pre-Depends'
     7.3.      Packages which break other packages - `Breaks'
     7.4.      Conflicting binary packages - `Conflicts'
     7.5.      Virtual packages - `Provides'
     7.6.      Overwriting files and replacing packages - `Replaces'
     7.6.1.         Overwriting files in other packages
     7.6.2.         Replacing whole packages, forcing their removal
     7.7.      Relationships between source and binary packages -
               `Build-Depends', `Build-Depends-Indep', `Build-Conflicts',
               `Build-Conflicts-Indep'

     8.        Shared libraries
     8.1.      Run-time shared libraries
     8.1.1.         `ldconfig'
     8.2.      Shared library support files
     8.3.      Static libraries
     8.4.      Development files
     8.5.      Dependencies between the packages of the same library
     8.6.      Dependencies between the library and other packages - the
               `shlibs' system
     8.6.1.         The `shlibs' files present on the system
     8.6.2.         How to use `dpkg-shlibdeps' and the `shlibs' files
     8.6.3.         The `shlibs' File Format
     8.6.4.         Providing a `shlibs' file
     8.6.5.         Writing the `debian/shlibs.local' file

     9.        The Operating System
     9.1.      File system hierarchy
     9.1.1.         File system Structure
     9.1.2.         Site-specific programs
     9.1.3.         The system-wide mail directory
     9.2.      Users and groups
     9.2.1.         Introduction
     9.2.2.         UID and GID classes
     9.3.      System run levels and `init.d' scripts
     9.3.1.         Introduction
     9.3.2.         Writing the scripts
     9.3.3.         Interfacing with the initscript system
     9.3.4.         Boot-time initialization
     9.3.5.         Example
     9.4.      Console messages from `init.d' scripts
     9.5.      Cron jobs
     9.6.      Menus
     9.7.      Multimedia handlers
     9.8.      Keyboard configuration
     9.9.      Environment variables
     9.10.     Registering Documents using doc-base

     10.       Files
     10.1.     Binaries
     10.2.     Libraries
     10.3.     Shared libraries
     10.4.     Scripts
     10.5.     Symbolic links
     10.6.     Device files
     10.7.     Configuration files
     10.7.1.        Definitions
     10.7.2.        Location
     10.7.3.        Behavior
     10.7.4.        Sharing configuration files
     10.7.5.        User configuration files ("dotfiles")
     10.8.     Log files
     10.9.     Permissions and owners
     10.9.1.        The use of `dpkg-statoverride'

     11.       Customized programs
     11.1.     Architecture specification strings
     11.2.     Daemons
     11.3.     Using pseudo-ttys and modifying wtmp, utmp and lastlog
     11.4.     Editors and pagers
     11.5.     Web servers and applications
     11.6.     Mail transport, delivery and user agents
     11.7.     News system configuration
     11.8.     Programs for the X Window System
     11.8.1.        Providing X support and package priorities
     11.8.2.        Packages providing an X server
     11.8.3.        Packages providing a terminal emulator
     11.8.4.        Packages providing a window manager
     11.8.5.        Packages providing fonts
     11.8.6.        Application defaults files
     11.8.7.        Installation directory issues
     11.8.8.        The OSF/Motif and OpenMotif libraries
     11.8.9.        Icon caching
     11.9.     Perl programs and modules
     11.10.    Emacs lisp programs
     11.11.    Games

     12.       Documentation
     12.1.     Manual pages
     12.2.     Info documents
     12.3.     Additional documentation
     12.4.     Preferred documentation formats
     12.5.     Copyright information
     12.6.     Examples
     12.7.     Changelog files

     A.        Introduction and scope of these appendices

     B.        Binary packages (from old Packaging Manual)
     B.1.      Creating package files - `dpkg-deb'
     B.2.      Package control information files
     B.3.      The main control information file: `control'
     B.4.      Time Stamps

     C.        Source packages (from old Packaging Manual)
     C.1.      Tools for processing source packages
     C.1.1.         `dpkg-source' - packs and unpacks Debian source
                    packages
     C.1.2.         `dpkg-buildpackage' - overall package-building control
                    script
     C.1.3.         `dpkg-gencontrol' - generates binary package control
                    files
     C.1.4.         `dpkg-shlibdeps' - calculates shared library
                    dependencies
     C.1.5.         `dpkg-distaddfile' - adds a file to `debian/files'
     C.1.6.         `dpkg-genchanges' - generates a `.changes' upload
                    control file
     C.1.7.         `dpkg-parsechangelog' - produces parsed representation
                    of a changelog
     C.1.8.         `dpkg-architecture' - information about the build and
                    host system
     C.2.      The Debianised source tree
     C.2.1.         `debian/rules' - the main building script
     C.2.2.         `debian/changelog'
     C.2.3.         `debian/substvars' and variable substitutions
     C.2.4.         `debian/files'
     C.2.5.         `debian/tmp'
     C.3.      Source packages as archives
     C.4.      Unpacking a Debian source package without `dpkg-source'
     C.4.1.         Restrictions on objects in source packages

     D.        Control files and their fields (from old Packaging Manual)
     D.1.      Syntax of control files
     D.2.      List of fields
     D.2.1.         `Filename' and `MSDOS-Filename'