diff --git a/docs/how-ubuntu-is-made/index.md b/docs/how-ubuntu-is-made/index.md index 0884e0c03..d52ea0a08 100644 --- a/docs/how-ubuntu-is-made/index.md +++ b/docs/how-ubuntu-is-made/index.md @@ -12,6 +12,16 @@ All about the Ubuntu Community, its support structures, and communication channe /community/index ``` +## The Ubuntu Policy Manual + +Policy requirements for the Ubuntu distribution. + +```{toctree} +:maxdepth: 3 + +ubuntu-policy/index +``` + ## Project governance How the project is governed. This sets out the expectations for contributors and maintainers alike. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/1-about-this-manual.rst b/docs/how-ubuntu-is-made/ubuntu-policy/1-about-this-manual.rst new file mode 100644 index 000000000..f2ea54cda --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/1-about-this-manual.rst @@ -0,0 +1,130 @@ +.. _chapter-1-about-this-manual: + +Chapter 1 - About this manual +----------------------------- + +1.1 Scope +~~~~~~~~~ + +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. + +This manual also describes Ubuntu policy as it relates to creating Ubuntu +packages. It is not a tutorial on how to build packages, nor is it exhaustive +where it comes to describing the behavior of the packaging system. Instead, +this manual attempts to define the interface to the package management system +that the developers have to be conversant with. [#f1]_ + +The footnotes present in this manual are merely informative, and are not part +of Ubuntu policy itself. + +The appendices to this manual are not necessarily normative, either. Please see +:ref:`Appendix A ` for more information. + +In the normative part of this manual, the words *must*, *should* and *may*, and +the adjectives *required*, *recommended* and *optional*, are used to +distinguish the significance of the various guidelines in this policy document. +Packages that do not conform to the guidelines denoted by must (or required) +will generally not be considered acceptable for the Ubuntu distribution. +Non-conformance with guidelines denoted by *should* (or *recommended*) will +generally be considered a bug, but will not necessarily render a package +unsuitable for distribution. Guidelines denoted by *may* (or *optional*) are +truly optional and adherence is left to the maintainer's discretion. + +These classifications are roughly equivalent to the bug severities *serious* +(for *must* or *required* directive violations), *minor*, *normal* or +*important* (for *should* or *recommended* directive violations) and *wishlist* +(for optional items). [#f2]_ + +Much of the information presented in this manual will be useful even when +building a package which is to be distributed in some other way or is intended +for local use only. + +The Ubuntu distribution differs from its parent Debian distribution in a +number of significant ways. In this document, these are marked with the tag +*Ubuntu*:. + +---- + +1.2 New versions of this document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Historically, this manual has been distributed via the Ubuntu package +ubuntu-policy (packages.ubuntu.com http://packages.ubuntu.com/ubuntu-policy). +Now, the policy is hosted on the Ubuntu Project Docs under the +:ref:`ubuntu-policy`. + +---- + +1.3 Authors and Maintainers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Originally called "Debian GNU/Linux Policy Manual", this manual was initially +written in 1996 by Ian Jackson. It was revised on November 27th, 1996 by David +A. Morris. Christian Schwarz added new sections on March 15th, 1997, and +reworked/restructured it in April-July 1997. Christoph Lameter contributed the +"Web Standard". Julian Gilbey largely restructured it in 2001. + +The Ubuntu branch of this manual is maintained by the `ubuntu-devel mailing +list `_. In 2026 Simon Johnsson reduced +the branch to the differences between Debian and Ubuntu, and moved it to the +Ubuntu Project Docs. + +Since September 1998, the responsibility for the contents of the Debian +version of this document lies on the `debian-policy mailing list +`_. Proposals are +discussed there and inserted into policy after a certain consensus is +established. + +---- + +.. _ubuntu-policy-related-documents: + +1.4 Related documents +~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 1.4 +`_) + +---- + +1.5 Definitions +~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 1.5 +`_) + +---- + +:ref:`← (Ubuntu Policy Manual) ` | :ref:`(Chapter 2 - The Ubuntu Archive) → ` + +---- + +.. [#f1] + Informally, the criteria used for inclusion is that the material meet one of + the following requirements: + + :Standard interfaces: + + The material presented represents an interface to the packaging system + that is mandated for use, and is used by, a significant number of + packages, and therefore should not be changed without peer review. + Package maintainers can then rely on this interfaces not changing, and + the package management software authors need to ensure compatibility + with these interface definitions. (Control file and changelog file + formats are examples.) + + :Chosen Convention: + + If there are a number of technically viable choices that can be made, + but one needs to select one of these options for inter-operability. The + version number format is one example. + + Please note that these are not mutually exclusive; selected conventions + often become parts of standard interfaces. +.. [#f2] + Compare RFC 2119. Note, however, that these words are used in a different + way in this document. + diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/10-files.rst b/docs/how-ubuntu-is-made/ubuntu-policy/10-files.rst new file mode 100644 index 000000000..524a11843 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/10-files.rst @@ -0,0 +1,168 @@ +.. _chapter-10-files: + +Chapter 10 - Files +------------------ + +10.1 Binaries +~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.1 +`_) + +---- + +.. _ubuntu-policy-libraries: + +10.2 Libraries +~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.2 +`_) + +---- + +10.3 Shared libraries +~~~~~~~~~~~~~~~~~~~~~ + +This section has moved to `Shared libraries, Chapter 8 +`_. + +---- + +10.4 Scripts +~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.4 +`_) + +---- + +10.5 Symbolic links +~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.5 +`_) + +---- + +10.6 Device files +~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 10.6 +`_) + +Packages must not include device files in the package file tree. + +If a package needs any special device files that are not included in the base +system, it must call MAKEDEV in the postinst script, after notifying the +user [#f72]_. + +Packages must not remove any device files in the postrm or any other script. +This is left to the system administrator. + +Ubuntu uses the serial devices :file:`/dev/ttyS*`. Programs using the old +:file:`/dev/cu*` devices should be changed to use :file:`/dev/ttyS*`. + +---- + +10.7 Configuration files +~~~~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: This section is considerably similar to the Debian + policy. Review is suggested. + +10.7.1 Definitions +^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.1 +`_) + +10.7.2 Location +^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.2 +`_) + +10.7.3 Behavior +^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.3 +`_) + +10.7.4 Sharing configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 10.7.4 +`_) + +Packages which specify the same file as a ``conffile`` must be tagged as +*conflicting* with each other. (This is an instance of the general rule about +not sharing files. Note that neither alternatives nor diversions are likely to +be appropriate in this case; in particular, :pkg:`dpkg` does not handle +diverted conffiles well.) + +The maintainer scripts must not alter a conffile of any package, including the +one the scripts belong to. + +If two or more packages use the same configuration file and it is reasonable +for both to be installed at the same time, one of these packages must be +defined as *owner* of the configuration file, i.e., it will be the package +which handles that file as a configuration file. Other packages that use the +configuration file must depend on the owning package if they require the +configuration file to operate. If the other package will use the configuration +file if present, but is capable of operating without it, no dependency need be +declared. + +If it is desirable for two or more related packages to share a configuration +file *and* for all of the related packages to be able to modify that +configuration file, then the following should be done: + +One of the related packages (the "owning" package) will manage the +configuration file with maintainer scripts as described in the previous +section. + +The owning package should also provide a program that the other packages may +use to modify the configuration file. + +The related packages must use the provided program to make any desired +modifications to the configuration file. They should either depend on the core +package to guarantee that the configuration modifier program is available or +accept gracefully that they cannot modify the configuration file if it is not. +(This is in addition to the fact that the configuration file may not even be +present in the latter scenario.) + +Sometimes it's appropriate to create a new package which provides the basic +infrastructure for the other packages and which manages the shared +configuration files. (The :pkg:`sgml-base` package is a good example.) + +10.7.5 User configuration files ("dotfiles") +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.7.5 +`_) + +---- + +10.8 Log files +~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.8 +`_) + +---- + +10.9 Permissions and owners +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 10.9 +`_) + +---- + +:ref:`← (Chapter 9 - The Operating System) ` | :ref:`(Chapter 11 - Customized programs) → ` + +---- + +.. [#f72] + This notification could be done via a (low-priority) debconf message, or an + echo (printf) statement. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/11-customized-programs.rst b/docs/how-ubuntu-is-made/ubuntu-policy/11-customized-programs.rst new file mode 100644 index 000000000..1937aabdb --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/11-customized-programs.rst @@ -0,0 +1,232 @@ +.. _chapter-11-customized-programs: + +Chapter 11 - Customized Programs +-------------------------------- + +.. _ubuntu-policy-architecture-specification: + +11.1 Architecture specification strings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Chapter 11 +`_) + +---- + +11.2 Daemons +~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.2 +`_) + +---- + +11.3 Using pseudo-ttys and modifying wtmp, utmp and lastlog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.3 +`_) + +---- + +11.4 Editors and pagers +~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.4 +`_) + +---- + +11.5 Web servers and applications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.5 +`_) + +---- + +11.6 Mail transport, delivery and user agents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.6 +`_) + +---- + +11.7 News system configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.7 +`_) + +---- + +11.8 Programs for the X Window System +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +11.8.1 Providing X support and package priorities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.8.1 +`_) + +11.8.2 Packages providing an X server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.8.2 +`_) + +11.8.3 Packages providing a terminal emulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.8.3 +`_) + +11.8.4 Packages providing a window manager +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 11.8.4 +`_) + +Packages that provide a window manager should declare in their control data +that they provide the virtual package :pkg:`x-window-manager`. They should also +register themselves as an alternative for :file:`/usr/bin/x-window-manager`, +with a priority calculated as follows: + +- Start with a priority of 20. + +- If the window manager supports the Debian menu system, add 20 points if this + support is available in the package's default configuration (i.e., no + configuration files belonging to the system or user have to be edited to + activate the feature); if configuration files must be modified, add only 10 + points. + +- If the window manager complies with `The Window Manager Specification Project + `_, written by the Free Desktop + Group, add 40 points. + +- If the window manager permits the X session to be restarted using a different + window manager (without killing the X server) in its default configuration, + add 10 points; otherwise add none. + +11.8.5 Packages providing fonts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.8.5 +`_) + +11.8.6 Application default files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.8.6 +`_) + +11.8.7 Installation directory issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + **Editor's note:** This section is outdated and is different to the Debian + policy. Review is suggested. + +(*Modifies*: `Debian Policy Manual, Section 11.8.7 +`_) + +Packages using the X Window System should not be configured to install files +under the :file:`/usr/X11R6/` directory. The :file:`/usr/X11R6/` directory +hierarchy should be regarded as obsolete. + +Programs that use GNU ``autoconf`` and ``automake`` are usually easily +configured at compile time to use :file:`/usr/` instead of :file:`/usr/X11R6/`, +and this should be done whenever possible. Configuration files for window +managers and display managers should be placed in a subdirectory of +:file:`/etc/X11/` corresponding to the package name due to these programs' +tight integration with the mechanisms of the X Window System. Application-level +programs should use the :file:`/etc/` directory unless otherwise mandated by +policy. + +The installation of files into subdirectories of +:file:`/usr/X11R6/include/X11/` and :file:`/usr/X11R6/lib/X11/` is now +prohibited; package maintainers should determine if subdirectories of +:file:`/usr/lib/` and :file:`/usr/share/` can be used instead. + +Packages should install any relevant files into the directories +:file:`/usr/include/X11/` and :file:`/usr/lib/X11/`, but if they do so, they +must pre-depend on :pkg:`x11-common (>= 1:7.0.0)` [#f87]_ + +11.8.8 The OSF/Motif and OpenMotif libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + **Editor's note:** This section is missing from the Debian policy. Review + is suggested. + +*Programs* that require the *non-DFSG-compliant* *OSF/Motif* or *OpenMotif +libraries* [#f88]_ should be compiled against and tested with LessTif (a free +re-implementation of Motif) instead. If the maintainer judges that the program +or programs do not work sufficiently well with LessTif to be distributed and +supported, but do so when compiled against Motif, then two versions of the +package should be created; one linked statically against Motif and with +``-smotif`` appended to the package name, and one linked dynamically against +Motif and with ``-dmotif`` appended to the package name. + +Both Motif-linked versions are dependent upon non-DFSG-compliant software and +thus cannot be uploaded to the *main* distribution; if the software is itself +DFSG-compliant it may be uploaded to the *contrib* distribution. While known +existing versions of Motif permit unlimited redistribution of binaries linked +against the library (whether statically or dynamically), it is the package +maintainer's responsibility to determine whether this is permitted by the +license of the copy of Motif in their possession. + +11.8.9 Icon caching +^^^^^^^^^^^^^^^^^^^ + +Ubuntu: Packages that provide icons in a subdirectory of +:file:`/usr/share/icons` must invoke ``update-icon-caches`` on each directory +into which they installed icons. This invocation must occur in both the +``postinst`` (for all arguments) and ``postrm`` (for all arguments) scripts +[#f89]_. Doing this allows GTK+ to make use of the icon cache for efficiency +gains, while ensuring that the cache does not get out of date and cause +problems for some applications. + +If ``update-icon-caches`` is not installed, this invocation may safely be +skipped. No additional dependency is necessary. + +---- + +11.9 Perl programs and modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.9 +`_) + +---- + +11.10 Emacs lisp programs +~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.10 +`_) + +---- + +11.11 Games +~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 11.11 +`_) + +---- + +:ref:`← (Chapter 10 - Files) ` | :ref:`(Chapter 12 - Documentation) → ` + +---- + +.. [#f87] + These libraries used to be all symbolic links. However, with ``X11R7``, + :file:`/usr/include/X11` and :file:`/usr/lib/X11` are now real directories, + and packages should ship their files here instead of in + ``/usr/X11R6/{include,lib}/X11``. :pkg:`x11-common (>= 1:7.0.0)` is the + package responsible for converting these symlinks into directories. +.. [#f88] + OSF/Motif and OpenMotif are collectively referred to as "Motif" in this + policy document. +.. [#f89] + If you are using debhelper, the dh_icons program will do this work for you. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/12-documentation.rst b/docs/how-ubuntu-is-made/ubuntu-policy/12-documentation.rst new file mode 100644 index 000000000..41c8daf62 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/12-documentation.rst @@ -0,0 +1,104 @@ +.. _chapter-12-documentation: + +Chapter 12 - Documentation +-------------------------- + +12.1 Manual pages +~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.1 +`_) + +---- + +12.2 Info documents +~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.2 +`_) + +---- + +12.3 Additional documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.3 +`_) + +---- + +12.4 Preferred documentation formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.4 +`_) + +---- + +.. _ubuntu-policy-copyright-information: + +12.5 Copyright information +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 12.5 +`_) + +Every package must be accompanied by a verbatim copy of its copyright and +distribution license in the file :file:`/usr/share/doc/package/copyright`. This file +must neither be compressed nor be a symbolic link. + +In addition, the copyright file must say where the upstream sources (if any) +were obtained. It should name the original authors of the package and the +Ubuntu maintainer(s) who were involved with its creation. + +A copy of the file which will be installed in +:file:`/usr/share/doc/package/copyright` should be in debian/copyright in the +source package. + +:file:`/usr/share/doc/package` may be a symbolic link to another directory in +:file:`/usr/share/doc` only if the two packages both come from the same source +and the first package Depends on the second. These rules are important because +copyrights must be extractable by mechanical means. + +Packages distributed under the UCB BSD license, the Apache license (version +2.0), the Artistic license, the GNU GPL (version 2 or 3), the GNU LGPL +(versions 2, 2.1, or 3), and the GNU FDL (versions 1.2 or 1.3) should refer to +the corresponding files under :file:`/usr/share/common-licenses`, [#f98]_ +rather than quoting them in the copyright file. + +You should not use the copyright file as a general README file. If your package +has such a file it should be installed in :file:`/usr/share/doc/package/README` +or README.Debian or some other appropriate place. + +---- + +12.6 Examples +~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.6 +`_) + +---- + +.. _ubuntu-policy-changelog-files: + +12.7 Changelog files +~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 12.7 +`_) + +---- + +:ref:`← (Chapter 11 - Customized programs) ` | :ref:`(Appendix A) → ` + +---- + +.. [#f98] + In particular, :file:`/usr/share/common-licenses/BSD`, + :file:`/usr/share/common-licenses/Apache-2.0`, :file:`/usr/share/common-licenses/Artistic`, + :file:`/usr/share/common-licenses/GPL-2`, :file:`/usr/share/common-licenses/GPL-3`, + :file:`/usr/share/common-licenses/LGPL-2`, :file:`/usr/share/common-licenses/LGPL-2.1`, + :file:`/usr/share/common-licenses/LGPL-3`, :file:`/usr/share/common-licenses/GFDL-1.2`, and + :file:`/usr/share/common-licenses/GFDL-1.3 respectively`. + diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/2-ubuntu-archive.rst b/docs/how-ubuntu-is-made/ubuntu-policy/2-ubuntu-archive.rst new file mode 100644 index 000000000..d912f5dfa --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/2-ubuntu-archive.rst @@ -0,0 +1,390 @@ +.. _chapter-2-ubuntu-archive: + +Chapter 2 - The Ubuntu Archive +------------------------------ + +The Ubuntu system is maintained and distributed as a collection of *packages*. +Since there are so many of them (currently well over 60000), they are split +into *sections* and given *priorities* to simplify the handling of them. + +The effort of the Ubuntu project is to build a *free* operating system, but +not every package we want to make accessible is free in our sense (see the +Ubuntu Licensing Policy, below), or may be imported/exported without +restrictions. Thus, the archive is split into areas [#f3]_ based on their licenses +and other restrictions. We also divide up packages based on whether they are +supported or not. + +The aims of this are: + +- to allow us to make as much software available as we can + +- to allow us to encourage everyone to write free software, and + +- to allow us to make it easy for people to produce CD-ROMs of our system + without violating any licenses, import/export restrictions, or any other + laws. + +---- + +2.1 The Ubuntu Licensing Policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Ubuntu Licensing Policy forms our definition of "free software". The +following guidelines apply to the *main* and *universe* categories of the +archive: + +Must include source code. + + The *main* and *universe* categories have a strict and non-negotiable + requirement that application software included in them must come with full + source code. + +Must allow modification and distribution of modified copies under the same +license. + + Just having the source code does not convey the same freedom as having the + right to change it. Without the ability to modify software, the Ubuntu + community cannot support software, fix bugs, translate it, or improve it. + +The following additional guidelines apply to the *main*, *restricted* and +*universe* categories of the archive: + +Must allow these rights to be passed on along with the software. + + You should be able to have exactly the same rights to the software as we + do. + +Must not discriminate against persons, groups or against fields of endeavour. + + The license of software included in Ubuntu can not discriminate against + anyone or any group of users and cannot restrict users from using the + software for a particular field of endeavour - a business for example. Thus + we will not distribute software that is licensed "freely for non-commercial + use". + +Must not be distributed under a license specific to Ubuntu. + + The rights attached to the software must not depend on the programme's + being part of Ubuntu system. So we will not distribute software for which + Ubuntu has a "special" exemption or right, and we will not put our own + software into Ubuntu and then refuse you the right to pass it on. + +The following additional guidelines apply to the entire archive: + +Must allow redistribution. + + Your right to sell or give away the software alone, or as part of an + aggregate software distribution, is important because: + + - You, the user, must be able to pass on any software you have received from + Ubuntu in either source code or compiled form. + + - While Ubuntu will not charge license fees for this distribution, you + might well want to charge to print Ubuntu CD's, or create your own + customized versions of Ubuntu which you sell, and should have the freedom + to do so. + +Must not require royalty payments or any other fee for redistribution or +modification. + + It's important that you can exercise your rights to this software without + having to pay for the privilege, and that you can pass these rights on to + other people on exactly the same basis. + +Must not contaminate other software licenses. + + The license must not place restrictions on other software that is + distributed along with it. For example, the license must not insist that + all other programmes distributed on the same medium be free software. + +May require source modifications to be distributed as patches. + + In some cases, software authors are happy for us to distribute their + software and modifications to their software, as long as the two are + distributed separately, so that people always have a copy of their pristine + code. We are happy to respect this preference. However, the license must + explicitly permit distribution of software built from modified source code. + +The "GPL," "BSD," and "Artistic" licenses are examples of licenses that we +consider *free*. + +Ubuntu contains licensed and copyrighted works that are not application +software. For example, the default Ubuntu installation includes documentation, +images, sounds, video clips and firmware. The Ubuntu community will make +decisions on the inclusion of these works on a case-by-case basis, ensuring +that these works do not restrict our ability to make Ubuntu available free of +charge, and that Ubuntu remains re-distributable by you. + +---- + +2.2 Archive Areas +~~~~~~~~~~~~~~~~~ + +| + +2.2.1 The main archive area +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every package in *main* must comply with the Ubuntu Licensing Policy. + +In addition, the packages in *main*: + +- must not require a package outside of *main* for compilation or execution + (thus, the package must not declare a "Depends", "Recommends", or + "Build-Depends" relationship on a non-*main* package), + +- must not be so buggy that we refuse to support them, and + +- must meet all policy requirements presented in this manual. + +2.2.2 The restricted archive area +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every package in *restricted* must comply with the Ubuntu Licensing Policy, +with the exceptions that source code may not be available and that modification +may not be permitted. + +In addition, the packages in *restricted*: + +- must not be so buggy that we refuse to support them, and +- must meet all policy requirements presented in this manual that it is + possible for them to meet. [#f4]_ + +The Ubuntu team recognises that many users have vital hardware in their +computer that requires drivers that are currently only available in binary +format. We urge all hardware vendors to insist that their suppliers provide +open source drivers for their components, but we recognise that in some cases +binary drivers are the only way to make your hardware work. As a result, +Ubuntu includes several of these drivers on the CD and in the repository, +clearly separated from the rest of the software by being placed in the +*restricted* archive area. + +Binary drivers are a poor choice, if you have a choice. Without source code, +Ubuntu cannot support this software, we only provide it for users who require +it to be able to run the Free Software we provide in main. Also, we cannot +make binary drivers available on other architectures (such as the Mac or IPAQ) +if we don't have the ability to port the software source code ourselves. If +your hardware is fully supported with open source drivers you can simply +remove the *restricted* archive area, and we would encourage you to do so. + +The *restricted* archive area may not include application software, only +hardware drivers. + +2.2.3 The universe archive area +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every package in universe must comply with the Ubuntu Licensing Policy. + +Packages in the *universe* archive area are not supported by the core Ubuntu +developers and Canonical Ltd. Packages may be moved between *main* and +*universe* as their support status changes. + +In addition, the packages in *universe*: + +- must not require a package outside of *main* and *universe* for + compilation or execution (thus, the package must not declare a "Depends", + "Recommends", or "Build-Depends" relationship on a non-*main* and + non-*universe* package), and + +- must meet all policy requirements presented in this manual. + + +2.2.4 The multiverse archive area +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Every package in *multiverse* must comply with the Ubuntu Licensing Policy, with +the exceptions that source code may not be available, that modification may +not be permitted, that rights may not be passed on along with the software, +that they may discriminate against persons, groups or fields of endeavour, and +that their license may be specific to Ubuntu. (In other words, they must be +redistributable without a fee and must not contaminate other software +licenses.) + +Packages must be placed in *multiverse* if they are not compliant with the parts +of the Ubuntu Licensing Policy that cover other categories of the archive, or +if they are encumbered by patents or other legal issues that make their +distribution problematic. + +Packages in the *multiverse* archive area are not supported by the core Ubuntu +developers and Canonical Ltd. + +In addition, the packages in *multiverse*: + +- must not be so buggy that we refuse to support them, and + +- must meet all policy requirements presented in this manual that it is + possible for them to meet. [#f5]_ + +---- + +.. _ubuntu-policy-copyright-considerations: + +2.3 Copyright considerations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Every package must be accompanied by a verbatim copy of its copyright and +distribution license in the file :file:`/usr/share/doc/package/copyright` (see +:ref:`Copyright information, Section 12.5 +` for further details). + +We reserve the right to restrict files from being included anywhere in our +archives if + +- their use or distribution would break a law, + +- there is an ethical conflict in their distribution or use, + +- we would have to sign a license for them, or + +- their distribution would conflict with other project policies. + +Programs whose authors encourage the user to make donations are fine for the +main distribution, provided that the authors do not claim that not donating is +immoral, unethical, illegal or something similar; in such a case they must go +in *multiverse*. + +Packages whose copyright permission notices (or patent problems) do not even +allow redistribution of binaries only, and where no special permission has been +obtained, must not be placed on the Ubuntu FTP site and its mirrors at all. + +Note that under international copyright law (this applies in the United States, +too), *no* distribution or modification of a work is allowed without an +explicit notice saying so. Therefore a program without a copyright notice *is* +copyrighted and you may not do anything to it without risking being sued! +Likewise if a program has a copyright notice but no statement saying what is +permitted then nothing is permitted. + +Many authors are unaware of the problems that restrictive copyrights (or lack +of copyright notices) can cause for the users of their supposedly-free +software. It is often worthwhile contacting such authors diplomatically to ask +them to modify their license terms. However, this can be a politically +difficult thing to do and you should ask for advice on the ``ubuntu-archive +mailing`` list first, as explained below. + +When in doubt about a copyright, send mail to +mailto:ubuntu-archive@lists.ubuntu.com. Be prepared to provide us with the +copyright statement. Software covered by the GPL, public domain software and +BSD-like copyrights are safe; be wary of the phrases "commercial use +prohibited" and "distribution restricted". + +---- + +2.4 Sections +~~~~~~~~~~~~ + +The packages in the archive areas *main*, *restricted*, *universe* and +*multiverse* are grouped further into sections to simplify handling. + +The archive area and section for each package should be specified in the +package's ``Section`` control record (see :ref:`Section, Section 5.6.5 +`). However, the maintainer of the Ubuntu +archive may override this selection to ensure the consistency of the Ubuntu +distribution. The ``Section`` field should be of the form: + + - section if the package is in the main archive area, + - area/section if the + package is in the restricted, universe or multiverse archive areas. + [#f6]_ + +The Ubuntu archive maintainers provide the authoritative list of sections. At +present, they are: ``admin``, ``cli-mono``, ``comm``, ``database``, ``devel``, ``debug``, ``doc``, ``editors``, +``electronics``, ``embedded``, ``fonts``, ``games``, ``gnome``, ``graphics``, ``gnu-r``, ``gnustep``, ``hamradio``, +``haskell``, ``httpd``, ``interpreters``, ``java``, ``kde``, ``kernel``, ``libs``, ``libdevel``, ``lisp``, +``localization``, ``mail``, ``math``, ``metapackages``, ``misc``, ``net``, ``news``, ``ocaml``, ``oldlibs``, +``otherosfs``, ``perl``, ``php``, ``python``, ``ruby``, ``science``, ``shells``, ``sound``, ``tex``, ``text``, ``utils``, +``vcs``, ``video``, ``web``, ``x11``, ``xfce``, ``zope``. + +Ubuntu: The *metapackages* section exists for the benefit of package management +tools. When removing a package in that section, its dependencies will not be +automatically considered for removal by tools which track the distinction +between packages that were installed explicitly and packages that were only +installed to satisfy dependencies. + +---- + +2.5 Priorities +~~~~~~~~~~~~~~ + +Each package should have a priority value, which is included in the package's +*control record* (see :ref:`Priority, Section 5.6.6 +`). This information is used by the Ubuntu +package management tools to separate high-priority packages from less-important +packages. + +The following *priority* levels are recognized by the Ubuntu package management +tools. + +``required`` + Packages which are necessary for the proper functioning of the system + (usually, this means that dpkg functionality depends on these packages). + Removing a ``required`` package may cause your system to become totally + broken and you may not even be able to use :pkg:`dpkg` to put things back, + so only do so if you know what you are doing. Systems with only the + required packages are probably unusable, but they do have enough + functionality to allow the sysadmin to boot and install more software. + +``important`` + Important programs, including those which one would expect to find on any + Unix-like system. If the expectation is that an experienced Unix person who + found it missing would say "What on earth is going on, where is foo?", it + must be an important package. [#f7]_ Other packages without which the + system will not run well or be usable must also have priority important. + This does not include Emacs, the X Window System, TeX or any other large + applications. The important packages are just a bare minimum of + commonly-expected and necessary tools. + +``standard`` + These packages provide a reasonably small but not too limited + character-mode system. This is what will be installed by default if the + user doesn't select anything else. It doesn't include many large + applications. + +``optional`` + (In a sense everything that isn't required is optional, but that's not what + is meant here.) This is all the software that you might reasonably want to + install if you didn't know what it was and don't have specialized + requirements. This is a much larger system and includes the X Window + System, a full TeX distribution, and many applications. Note that optional + packages should not conflict with each other. + +``extra`` + This contains all packages that conflict with others with required, + important, standard or optional priorities, or are only likely to be useful + if you already know what they are or have specialized requirements (such as + packages containing only detached debugging symbols). + + Packages must not depend on packages with lower priority values (excluding + build-time dependencies). In order to ensure this, the priorities of one or + more packages may need to be adjusted. + +---- + +:ref:`← (Chapter 1 - About this manual) ` | :ref:`(Chapter 3 - Binary packages) → ` + +---- + +.. [#f3] + The Ubuntu archive software uses the term "component" internally and in the + Release file format to refer to the division of an archive. The Debian + Social Contract simply refers to "areas." This document uses terminology + similar to the Social Contract. + +.. [#f4] + It is possible that there are policy requirements which the package is + unable to meet, for example, if the source is unavailable. These situations + will need to be handled on a case-by-case basis. + +.. [#f5] + It is possible that there are policy requirements which the package is + unable to meet, for example, if the source is unavailable. These situations + will need to be handled on a case-by-case basis. + +.. [#f6] + Packages that originally came from the Debian archive will often not have + ``Section`` fields matching the archive area selected for them in Ubuntu. + There is no need to change the package just for this; the maintainers of the + Ubuntu archive can and will override its placement. + +.. [#f7] + This is an important criterion because we are trying to produce, amongst + other things, a free Unix. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/3-binary-packages.rst b/docs/how-ubuntu-is-made/ubuntu-policy/3-binary-packages.rst new file mode 100644 index 000000000..6f628c326 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/3-binary-packages.rst @@ -0,0 +1,168 @@ +.. _chapter-3-binary-packages: + +Chapter 3 - Binary packages +--------------------------- + +The Ubuntu distribution is based on the Debian package management system, +called :pkg:`dpkg`. Thus, all packages in the Ubuntu distribution must be +provided in the ``.deb`` file format. + +---- + +3.1 The package name +~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.1 +`_) + +---- + +3.2 The version of a package +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.2 +`_) + +3.2.1 Version numbers based on dates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 3.2.1 +`_) + +In general, Ubuntu packages should use the same version numbers as the upstream +sources. + +However, in some cases where the upstream version number is based on a date +(e.g., a development "snapshot" release) the package management system cannot +handle these version numbers without epochs. For example, dpkg will consider +"96May01" to be greater than "96Dec24". + +To prevent having to use epochs for every new upstream version, the date based +portion of the version number should be changed to the following format in such +cases: "19960501", "19961224". It is up to the maintainer whether they want to +bother the upstream maintainer to change the version numbers upstream, too. + +Note that other version formats based on dates which are parsed correctly by +the package management system should not be changed. + +Native Debian or Ubuntu packages (i.e., packages which have been written +especially for Debian or Ubuntu) whose version numbers include dates should +always use the "YYYYMMDD" format. + +---- + +3.3 The maintainer of a package +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 3.3 +`_) + +Every package must have a Debian maintainer (the maintainer may be one person +or a group of people reachable from a common email address, such as a mailing +list). The maintainer is responsible for ensuring that the package is placed in +the appropriate distributions. + +The maintainer must be specified in the ``Maintainer`` control field with their +correct name and a working email address. If one person maintains several +packages, they should try to avoid having different forms of their name and +email address in the ``Maintainer`` fields of those packages. + +The format of the ``Maintainer`` control field is described in :ref:`Maintainer, Section 5.6.2 `. + +If the maintainer of a package quits from the Debian project, "Debian QA Group" +mailto:packages@qa.debian.org takes over the maintainer-ship of the package +until someone else volunteers for that task. These packages are called orphaned +packages. [#f8]_ + +Ubuntu: Packages that are modified in Ubuntu should have an Ubuntu-specific +``Maintainer field``. [#f9]_ All Ubuntu binary packages, and Ubuntu source +packages that are modified relative to Debian (that is, its version number +contains the string "ubuntu"), should have their ``Maintainer`` field adjusted as +follows: + +- If the ``Maintainer`` field contains an ``ubuntu.com`` email address, or + one associated with an Ubuntu developer, then no modifications should be + made. + +- If the package is in ``main`` or ``restricted``, the ``Maintainer`` field + should be set to Ubuntu Core Developers + mailto:ubuntu-devel-discuss@lists.ubuntu.com. + +- If the package is in ``universe`` or ``multiverse``, the ``Maintainer`` + field should be set to Ubuntu MOTU Developers + mailto:ubuntu-motu@lists.ubuntu.com. + +If the ``Maintainer`` field is modified, then the old value must be saved in a +field named ``XSBC-Original-Maintainer``. Because it is mandated and very +common, it is not necessary or appropriate to document this change in +:file:`debian/changelog`, unless it is the only change involved in the upload. + +---- + +3.4 The description of a package +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.4 +`_) + +---- + +3.5 Dependencies +~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.5 +`_) + +---- + +3.6 Virtual packages +~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.6 +`_) + +---- + +3.7 Base system +~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.7 +`_) + +---- + +3.8 Essential packages +~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.8 +`_) + +---- + +3.9 Maintainer scripts +~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.9 +`_) + +3.9.1 Prompting in maintainer scripts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 3.9.1 +`_) + +---- + +:ref:`← (Chapter 2 - The Ubuntu Archive) ` | :ref:`(Chapter 4 - Source packages) → ` + +---- + +.. [#f8] + The detailed procedure for doing this gracefully can be found in the Debian + Developer's Reference, see :ref:`Related documents, Section 1.4 + `. + +.. [#f9] + This is in response to a poll of Debian maintainers, documented in the + `DebianMaintainerField `_ + specification. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/4-source-packages.rst b/docs/how-ubuntu-is-made/ubuntu-policy/4-source-packages.rst new file mode 100644 index 000000000..2f6f9f114 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/4-source-packages.rst @@ -0,0 +1,479 @@ +.. _chapter-4-source-packages: + +Chapter 4 - Source packages +--------------------------- + +4.1 Standards conformance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.1 +`_) + +Source packages should specify the most recent version number of this policy +document with which your package complied when it was last updated. + +This information may be used to file bug reports automatically if your package +becomes too much out of date. + +The version is specified in the Standards-Version control field. The format of +the ``Standards-Version`` field is described in :ref:`Standards-Version, Section 5.6.11 `. + +You should regularly, and especially if your package has become out of date, +check for the newest Policy Manual available and update your package, if +necessary. When your package complies with the new standards you should update +the ``Standards-Version`` source package field and release it. [#f14]_ + +---- + +4.2 Package relationships +~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.2 +`_) + +---- + +4.3 Changes to upstream sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.3 +`_) + +If changes to the source code are made that are not specific to the needs of +the Ubuntu system, they should be sent to the upstream authors in whatever form +they prefer so as to be included in the upstream version of the package. + +If you need to configure the package differently for Ubuntu or for Linux, and +the upstream source doesn't provide a way to do so, you should add such +configuration facilities (for example, a new ``autoconf`` test or ``#define``) +and send the patch to the upstream authors, with the default set to the way +they originally had it. You can then easily override the default in your +debian/rules or wherever is appropriate. + +You should make sure that the ``configure`` utility detects the correct +architecture specification string (refer to :ref:`Architecture specification +strings, Section 11.1 ` for details). + +If you need to edit a :file:`Makefile` where GNU-style ``configure`` scripts +are used, you should edit the :file:`.in` files rather than editing the +:file:`Makefile` directly. This allows the user to reconfigure the package if +necessary. You should *not* configure the package and edit the generated +:file:`Makefile`! This makes it impossible for someone else to later +reconfigure the package without losing the changes you made. + +---- + +4.4 Ubuntu changelog: :file:`debian/changelog` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.4 +`_) + +Changes in the Ubuntu version of the package should be briefly explained in the Ubuntu changelog file :file:`debian/changelog`. [#f17]_ This includes modifications made in the Ubuntu package compared to the upstream one or the Debian package as well as other changes and updates to the package. [#f18]_ + +The format of the :file:`debian/changelog` allows the package building tools to +discover which version of the package is being built and find out other +release-specific information. + +That format is a series of entries like this: + +.. code-block:: none + + package (version) distribution(s); urgency=urgency + [optional blank line(s), stripped] + * change details + more change details + [blank line(s), included in output of dpkg-parsechangelog] + * even more change details + [optional blank line(s), stripped] + -- maintainer name [two spaces] date + +``package`` and ``version`` are the source package name and version number. + +``distribution(s)`` lists the distributions where this version should be +installed when it is uploaded - it is copied to the ``Distribution`` field in +the :file:`.changes` file. See :ref:`Distribution, Section 5.6.14 +`. + +``urgency`` is the value for the ``Urgency`` field in the :file:`.changes` file +for the upload (see :ref:`Urgency, Section 5.6.17 +`). It is not possible to specify an urgency +containing commas; commas are used to separate ``keyword=value`` settings in +the :pkg:`dpkg` changelog format (though there is currently only one useful +*keyword*, ``urgency``). + +The change details may in fact be any series of lines starting with at least +two spaces, but conventionally each change starts with an asterisk and a +separating space and continuation lines are indented so as to bring them in +line with the start of the text above. Blank lines may be used here to separate +groups of changes, if desired. + +If this upload resolves bugs recorded in the Debian Bug Tracking System (BTS), +they may be automatically closed on the inclusion of this package into the +Debian archive by including the string: ``closes: Bug#nnnnn`` in the change +details. [#f19]_ This information is conveyed via the ``Closes`` field in the +:file:`.changes` file (see :ref:`Closes, Section 5.6.22 +`). + +Ubuntu: If this upload resolves bugs recorded in Launchpad, they may be +automatically closed on the inclusion of this package into the Ubuntu archive +by including the string: ``LP: #nnnnn`` in the change details. [#f20]_ This +information is conveyed via the Launchpad-Bugs-Fixed field in the +:file:`.changes` file (see :ref:`Launchpad-Bugs-Fixed, Section 5.6.23 +`). + +The maintainer name and email address used in the changelog should be the +details of the person uploading *this* version. They are not necessarily those +of the usual package maintainer. The information here will be copied to the +``Changed-By`` field in the :file:`.changes` file (see :ref:`Changed-By, +Section 5.6.4 `), and then later used to send +an acknowledgement when the upload has been installed. + +The ``date`` must be in RFC822 format [#f21]_; it must include the time zone +specified numerically, with the time zone name or abbreviation optionally +present as a comment in parentheses. + +The first "title" line with the package name must start at the left hand +margin. The "trailer" line with the maintainer and date details must be +preceded by exactly one space. The maintainer details and the date must be +separated by exactly two spaces. + +The entire changelog must be encoded in UTF-8. + +For more information on placement of the changelog files within binary +packages, please see :ref:`Changelog files, Section 12.7 +`. + +---- + +4.5 Copyright: :file:`debian/copyright` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.5 +`_) + +Every package must be accompanied by a verbatim copy of its copyright and +distribution license in the file :file:`/usr/share/doc/package/copyright` (see +:ref:`Copyright information, Section 12.5 ` for +further details). Also see :ref:`Copyright considerations, Section 2.3 +` for further considerations relayed to +copyrights for packages. + +---- + +4.6 Error trapping in makefiles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.6 +`_) + +---- + +4.7 Time Stamps +~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.7 +`_) + +---- + +4.8 Restrictions on objects in source packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.8 +`_) + +The source package may not contain any hard links [#f23]_, device special +files, sockets or setuid or setgid files. [#f24]_ + +---- + +4.9 Main building script: :file:`debian/rules` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: This section deviates significantly from the current + Debian Policy Manual. Future revisions of this section are encouraged. + +(*Modifies*: `Debian Policy Manual, Section 4.9 +`_) + +This file must be an executable makefile, and contains the package-specific +recipes for compiling the package and building binary package(s) from the +source. + +It must start with the line ``#!/usr/bin/make -f``, so that it can be invoked +by saying its name rather than invoking make explicitly. + +Since an interactive :file:`debian/rules` script makes it impossible to +auto-compile that package and also makes it hard for other people to reproduce +the same binary package, all *required targets* MUST be non-interactive. At a +minimum, required targets are the ones called by ``dpkg-buildpackage``, namely, +*clean*, *binary*, *binary-arch*, *binary-indep*, and *build*. It also follows +that any target that these targets depend on must also be non-interactive. + +The targets are as follows (required unless stated otherwise): + +``build`` + The ``build`` target should perform all the configuration and compilation of + the package. If a package has an interactive pre-build configuration + routine, the Debianized source package must either be built after this has + taken place (so that the binary package can be built without rerunning the + configuration) or the configuration routine modified to become + non-interactive. (The latter is preferable if there are + architecture-specific features detected by the configuration routine.) + + For some packages, notably ones where the same source tree is compiled in + different ways to produce two binary packages, the ``build`` target does + not make much sense. For these packages it is good enough to provide two + (or more) targets (``build-a`` and ``build-b`` or whatever) for each of the + ways of building the package, and a ``build`` target that does nothing. The + ``binary`` target will have to build the package in each of the possible + ways and make the binary package out of each. + + The ``build`` target must not do anything that might require root + privilege. + + The ``build`` target may need to run the ``clean`` target first - see + below. + + When a package has a configuration and build routine which takes a long + time, or when the makefiles are poorly designed, or when ``build`` needs to + run ``clean`` first, it is a good idea to ``touch build`` when the build + process is complete. This will ensure that if :file:`debian/rules` build is + run again it will not rebuild the whole program. [#f25]_ + +``build-arch`` (optional), ``build-indep`` (optional) + A package may also provide both of the targets ``build-arch`` and + ``build-indep``. The ``build-arch`` target, if provided, should perform all + the configuration and compilation required for producing all + architecture-dependant binary packages (those packages for which the body + of the ``Architecture`` field in :file:`debian/control` is not all). + Similarly, the ``build-indep`` target, if provided, should perform all the + configuration and compilation required for producing all + architecture-independent binary packages (those packages for which the body + of the ``Architecture`` field in :file:`debian/control` is all). The + ``build`` target should depend on those of the targets ``build-arch`` and + ``build-indep`` that are provided in the rules file. + + If one or both of the targets ``build-arch`` and ``build-indep`` are not + provided, then invoking :file:`debian/rules` with one of the not-provided + targets as arguments should produce a exit status code of 2. Usually this + is provided automatically by make if the target is missing. + + The ``build-arch`` and ``build-indep`` targets must not do anything that + might require root privilege. + +``binary``, ``binary-arch``, ``binary-indep`` + The ``binary`` target must be all that is necessary for the user to build + the binary package(s) produced from this source package. It is split into + two parts: ``binary-arch`` builds the binary packages which are specific to + a particular architecture, and ``binary-indep`` builds those which are not. + + ``binary`` may be (and commonly is) a target with no commands which simply + depends on ``binary-arch`` and ``binary-indep``. + + Both ``binary``-* targets should depend on the ``build`` target, or on the + appropriate ``build-arch`` or ``build-indep`` target, if provided, so that + the package is built if it has not been already. It should then create the + relevant binary package(s), using ``dpkg-gencontrol`` to make their control + files and ``dpkg-deb`` to build them and place them in the parent of the top + level directory. + + Both the ``binary-arch`` and ``binary-indep`` targets *must* exist. If one + of them has nothing to do (which will always be the case if the source + generates only a single binary package, whether architecture-dependent or + not), it must still exist and must always succeed. + + The *binary* targets must be invoked as root. [#f26]_ + +``clean`` + This must undo any effects that the ``build`` and ``binary`` targets may + have had, except that it should leave alone any output files created in the + parent directory by a run of a ``binary`` target. + + If a :file:`build` file is touched at the end of the ``build`` target, as + suggested above, it should be removed as the first action that ``clean`` + performs, so that running ``build`` again after an interrupted ``clean`` + doesn't think that everything is already done. + + The ``clean`` target may need to be invoked as root if ``binary`` has been + invoked since the last ``clean``, or if ``build`` has been invoked as root + (since ``build`` may create directories, for example). + +``get-orig-source`` (optional) + This target fetches the most recent version of the original source package + from a canonical archive site (via FTP or WWW, for example), does any + necessary rearrangement to turn it into the original source tar file format + described below, and leaves it in the current directory. + + This target may be invoked in any directory, and should take care to clean + up any temporary files it may have left. + + This target is optional, but providing it if possible is a good idea. + +``patch`` (optional) + This target performs whatever additional actions are required to make the + source ready for editing (unpacking additional upstream archives, applying + patches, etc.). It is recommended to be implemented for any package where + ``dpkg-source -x`` does not result in source ready for additional + modification. See :ref:`Source package handling: debian/README.source, Section + 4.14 `. + +The ``build``, ``binary`` and ``clean`` targets must be invoked with the +current directory being the package's top-level directory. + +Additional targets may exist in :file:`debian/rules`, either as published or +undocumented interfaces or for the package's internal use. + +The architectures we build on and build for are determined by :pkg:`make` +variables using the utility ``dpkg-architecture``. You can determine the Debian +architecture and the GNU style architecture specification string for the build +machine (the machine type we are building on) as well as for the host machine +(the machine type we are building for). Here is a list of supported :pkg:`make` +variables: + +- ``DEB_*_ARCH`` (the Debian architecture) + +- ``DEB_*_GNU_TYPE`` (the GNU style architecture specification string) + +- ``DEB_*_GNU_CPU`` (the CPU part of DEB_*_GNU_TYPE) + +- ``DEB_*_GNU_SYSTEM`` (the System part of DEB_*_GNU_TYPE) + +where * is either ``BUILD`` for specification of the build machine or ``HOST`` +for specification of the host machine. + +Backward compatibility can be provided in the rules file by setting the needed +variables to suitable default values; please refer to the documentation of +:manpage:`dpkg-architecture(1)` for details. + +It is important to understand that the ``DEB_*_ARCH`` string only determines +which Debian architecture we are building on or for. It should not be used to +get the CPU or system information; the GNU style variables should be used for +that. + +4.9.1 :file:`debian/rules` and ``DEB_BUILD_OPTIONS`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.9.1 +`_) + +---- + +.. _ubuntu-policy-variable-substitution: + +4.10 Variable substitution in: :file:`debian/substvars` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.10 +`_) + +When ``dpkg-gencontrol``, ``dpkg-genchanges`` and ``dpkg-source`` generate +control files they perform variable substitutions on their output just before +writing it. Variable substitutions have the form ``${variable}``. The optional +file :file:`debian/substvars` contains variable substitutions to be used; +variables can also be set directly from :file:`debian/rules` using the -V +option to the source packaging commands, and certain predefined variables are +also available. + +The :file:`debian/substvars` file is usually generated and modified dynamically +by :file:`debian/rules` targets, in which case it must be removed by the clean +target. + +See :manpage:`deb-substvars(5)` for full details about source variable +substitutions, including the format of :file:`debian/substvars`. + +---- + +4.11 Optional upstream source location: :file:`debian/watch` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 4.11 +`_) + +This is an optional, recommended control file for the :pkg:`uscan` utility +which defines how to automatically scan ftp or http sites for newly available +updates of the package. This is used by http://dehs.alioth.debian.org/ and +other Debian QA tools to help with quality control and maintenance of the +distribution as a whole. + +---- + +4.12 Generated files list: :file:`debian/files` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.12 +`_) + +---- + +4.13 Convenience copies of code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, Renamed from "Embedded copies of code", see:* `Debian Policy Manual Section 4.13 +`_) + +---- + +.. _ubuntu-policy-source-package-handling: + +4.14 Source package handling: :file:`debian/README.source` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 4.14 +`_) + +---- + +:ref:`← (Chapter 3 - Binary packages) ` | :ref:`(Chapter 5 - Control files and their fields) → ` + +---- + +.. [#f14] + See the file :file:`upgrading-checklist` for information about policy which + has changed between different versions of this document. +.. [#f17] + Mistakes in changelogs are usually best rectified by making a new changelog + entry rather than "rewriting history" by editing old changelog entries. +.. [#f18] + Although there is nothing stopping an author who is also the Ubuntu + maintainer from using this changelog for all their changes, it will have to + be renamed if the Ubuntu and upstream maintainers become different people. + In such a case, however, it might be better to maintain the package as a + non-native package. +.. [#f19] + To be precise, the string should match the following Perl regular + expression: + ``/closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i`` + + Then all of the bug numbers listed will be closed by the archive maintenance + script (katie) using the version of the changelog entry. +.. [#f20] + To be precise, the string should match the following Perl regular expression: + + ``/lp:\s+\#\d+(?:,\s*\#\d+)*/i`` + + Then all of the bug numbers listed will be closed by the archive + maintenance software using the version of the changelog entry. +.. [#f21] + This is generated by date -R. +.. [#f23] + This is not currently detected when building source packages, but only when + extracting them. + + Hard links may be permitted at some point in the future, but would require a + fair amount of work. +.. [#f24] + Setgid directories are allowed. +.. [#f25] + Another common way to do this is for ``build`` to depend on ``build-stamp`` + and to do nothing else, and for the ``build-stamp`` target to do the + building and to ``touch build-stamp`` on completion. This is especially + useful if the build routine creates a file or directory called + :file:`build`; in such a case, ``build`` will need to be listed as a phony + target (i.e., as a dependency of the ``.PHONY`` target). See the + documentation of :pkg:`make` for more information on phony targets. + +.. [#f26] + The :pkg:`fakeroot` package often allows one to build a package correctly + even without being root. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/5-control-files.rst b/docs/how-ubuntu-is-made/ubuntu-policy/5-control-files.rst new file mode 100644 index 000000000..9df94c6ca --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/5-control-files.rst @@ -0,0 +1,623 @@ +.. _chapter-5-control-files: + +Chapter 5 - Control files and their fields +------------------------------------------- + +(*Modifies*: `Debian Policy Manual, Chapter 5 +`_) + +The package management system manipulates data represented in a common format, +known as *control data*, stored in *control files*. Control files are used for +source packages, binary packages and the :file:`.changes` files which control +the installation of uploaded files [#f32]_. + +---- + +5.1 Syntax of control files +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 5.1 +`_) + +A control file consists of one or more paragraphs of fields [#f33]_. The +paragraphs are separated by blank lines. Some control files allow only one +paragraph; others allow several, in which case each paragraph usually refers to +a different package. (For example, in source packages, the first paragraph +refers to the source package, and later paragraphs refer to binary packages +generated from the source.) + +Each paragraph consists of a series of data fields; each field consists of the field name, followed by a colon and then the data/value associated with that field. It ends at the end of the (logical) line. Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon. For example, a field might be: + +.. code-block:: none + + Package: libc6 + +the field name is ``Package`` and the field value ``libc6``. + +Many fields' values may span several lines; in this case each continuation line +must start with a space or a tab. Any trailing spaces or tabs at the end of +individual lines of a field value are ignored. + +In fields where it is specified that lines may not wrap, only a single line of +data is allowed and whitespace is not significant in a field body. Whitespace +must not appear inside names (of packages, architectures, files or anything +else) or version numbers, or between the characters of multi-character version +relationships. + +Field names are not case-sensitive, but it is usual to capitalize the field +names using mixed case as shown below. + +Blank lines, or lines consisting only of spaces and tabs, are not allowed +within field values or between fields - that would mean a new paragraph. + +All control files must be encoded in UTF-8. + +---- + +5.2 Source package control files -- :file:`debian/control` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 5.2 +`_) + +The :file:`debian/control` contains the most vital (and version-independent) +information about the source package and about the binary packages it creates. + +The first paragraph of the control file contains information about the source +package in general. The subsequent sets each describe a binary package that the +source tree builds. + +The fields in the general paragraph (the first one, for the source package) +are: + +- :ref:`Source ` (mandatory) + +- :ref:`Maintainer ` (mandatory) + +- :ref:`Uploaders ` (optional) + +- :ref:`Section ` (recommended) + +- :ref:`Priority ` (recommended) + +- :ref:`Build-Depends et al ` + +- :ref:`Standards-Version ` (recommended) + +- :ref:`Homepage ` (optional) + +The fields in the binary package paragraphs are: + +- :ref:`Package ` (mandatory) + +- :ref:`Architecture ` (mandatory) + +- :ref:`Section ` (recommended) + +- :ref:`Priority ` (recommended) + +- :ref:`Essential ` (optional) + +- :ref:`Depends et al ` (recommended) + +- :ref:`Description ` (mandatory) + +- :ref:`Homepage ` (optional) + +The syntax and semantics of the fields are described below. + +These fields are used by ``dpkg-gencontrol`` to generate control files for +binary packages (see below), by dpkg-genchanges to generate the +:file:`.changes` file to accompany the upload, and by ``dpkg-source`` when it +creates the :file:`.dsc` source control file as part of a source archive. Many +fields are permitted to span multiple lines in :file:`debian/control` but not +in any other control file. These tools are responsible for removing the line +breaks from such fields when using fields from :file:`debian/control` to +generate other control files. + +The fields here may contain variable references - their values will be +substituted by ``dpkg-gencontrol``, ``dpkg-genchanges`` or ``dpkg-source`` when +they generate output control files. See :ref:`Variable substitutions: +debian/substvars, Section 4.10 ` for +details. + +In addition to the control file syntax described above, this file may also +contain comment lines starting with ``#`` without any preceding whitespace. All +such lines are ignored, even in the middle of continuation lines for a +multiline field, and do not end a multiline field. + +---- + +5.3 Binary package control files -- :file:`DEBIAN/control` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 5.3 +`_) + +The :file:`DEBIAN/control` file contains the most vital (and version-dependent) information about a binary package. + +The fields in this file are: + +- :ref:`Package ` (mandatory) + +- :ref:`Source ` + +- :ref:`Version ` (mandatory) + +- :ref:`Section ` (recommended) + +- :ref:`Priority ` (recommended) + +- :ref:`Architecture ` (mandatory) + +- :ref:`Essential ` + +- :ref:`Depends et al ` + +- :ref:`Installed-Size ` + +- :ref:`Maintainer ` (mandatory) + +- :ref:`Description ` (mandatory) + +- :ref:`Homepage ` + +---- + +5.4 Debian source control files -- :file:`.dsc` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 5.4 +`_) + +This file contains a series of fields, identified and separated just like the +fields in the control file of a binary package. The fields are listed below; +their syntax is described above, in :ref:`Control files and their fields (from +old Packaging Manual), Appendix D `. + +- :ref:`Format ` (mandatory) + +- :ref:`Source ` (mandatory) + +- :ref:`Version ` (mandatory) + +- :ref:`Maintainer ` (mandatory) + +- :ref:`Uploaders ` + +- :ref:`Binary ` + +- :ref:`Architecture ` + +- :ref:`Build-Depends et al ` + +- :ref:`Standards-Version ` + (recommended) + +- :ref:`Files ` (mandatory) + +Homepage + +The source package control file is generated by ``dpkg-source`` when it builds +the source archive, from other files in the source package, described above. +When unpacking, it is checked against the files and directories in the other +parts of the source package. + +---- + +5.5 Debian upload changes control files -- :file:`.changes` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: This section is significantly different to the current + Debian Policy Manual. + +(*Modifies*: `Debian Policy Manual, Section 5.5 +`_) + +The :file:`.changes` files are used by the Ubuntu archive maintenance software +to process updates to packages. They contain one paragraph which contains +information from the :file:`debian/control` file and other data about the source +package gathered via :file:`debian/changelog` and :file:`debian/rules`. + +The fields in this file are: + +- :ref:`Format ` (mandatory) + +- :ref:`Date ` (mandatory) + +- :ref:`Source ` (mandatory) + +- :ref:`Binary ` (mandatory) + +- :ref:`Architecture ` (mandatory) + +- :ref:`Version ` (mandatory) + +- :ref:`Distribution ` (mandatory) + +- :ref:`Urgency ` (recommended) + +- :ref:`Maintainer ` (mandatory) + +- :ref:`Changed-By ` + +- :ref:`Description ` (mandatory) + +- :ref:`Closes ` + +- :ref:`Launchpad-Bugs-Fixed ` + +- :ref:`Changes ` (mandatory) + +- :ref:`Files ` (mandatory) + +---- + +5.6 List of fields +~~~~~~~~~~~~~~~~~~ + +| + +.. _ubuntu-policy-source-field: + +5.6.1 ``Source`` +^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.1 +`_) + +.. _ubuntu-policy-maintainer-field: + +5.6.2 ``Maintainer`` +^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.2 +`_) + +.. _ubuntu-policy-uploaders-field: + +5.6.3 ``Uploaders`` +^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 5.6.3 +`_) + +List of the names and email addresses of co-maintainers of the package, if any. +If the package has other maintainers beside the one named in the +:ref:`Maintainer field `, their names and email +addresses should be listed here. The format is the same as that of the +Maintainer tag, and multiple entries should be comma separated. Currently, this +field is restricted to a single line of data. This is an optional field. + +Any parser that interprets the Uploaders field in :file:`debian/control` must +permit it to span multiple lines. Line breaks in an Uploaders field that spans +multiple lines are not significant and the semantics of the field are the same +as if the line breaks had not been present. + +.. _ubuntu-policy-changed-by-field: + +5.6.4 ``Changed-By`` +^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.4 +`_) + +.. _ubuntu-policy-section-field: + +5.6.5 ``Section`` +^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.5 +`_) + +.. _ubuntu-policy-priority-field: + +5.6.6 ``Priority`` +^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.6 +`_) + +.. _ubuntu-policy-package-field: + +5.6.7 ``Package`` +^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 5.6.7 +`_) + +The name of the binary package. + +Package names must consist only of lower case letters (``a-z``), digits +(``0-9``), plus (``+``) and minus (``-``) signs, and periods (``.``). They must +be at least two characters long and must start with an alphanumeric character. + +.. _ubuntu-policy-architecture-field: + +5.6.8 ``Architecture`` +^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.8 +`_) + +.. _ubuntu-policy-essential-field: + +5.6.9 ``Essential`` +^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.9 +`_) + +5.6.10 Package interrelationship fields: ``Depends``, ``Pre-Depends``, ``Recommends``, ``Suggests``, ``Breaks``, ``Conflicts``, ``Provides``, ``Replaces``, ``Enhances`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.10 +`_) + +.. _ubuntu-policy-standards-version-field: + +5.6.11 ``Standards-Version`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 5.6.11 +`_) + +The most recent version of the standards (the policy manual and associated +texts) with which the package complies. + +The version number has four components: major and minor version number and +major and minor patch level. When the standards change in a way that requires +every package to change the major number will be changed. Significant changes +that will require work in many packages will be signaled by a change to the +minor number. The major patch level will be changed for any change to the +meaning of the standards, however small; the minor patch level will be changed +when only cosmetic, typographical or other edits are made which neither change +the meaning of the document nor affect the contents of packages. + +Thus only the first three components of the policy version are significant in +the *Standards-Version* control field, and so either these three components or +the all four components may be specified. [#f37]_ + +Ubuntu: Packages should not include the Ubuntu revision of the policy manual +(e.g. "ubuntu1" in "3.8.0.1ubuntu1") in their *Standards-Version* field. This +tends to create unnecessary diffs relative to Debian. For the same reason, +Ubuntu developers should not generally change the *Standards-Version* field in +packages originating in Debian. + +.. _ubuntu-policy-version-field: + +5.6.12 ``Version`` +^^^^^^^^^^^^^^^^^^ + + **Editor's note**: This subsubsection lacks additional subsubsubsections + that exist in the current Debian Policy Manual. + +(*Modifies*: `Debian Policy Manual, Section 5.6.12 +`_) + +The version number of a package. The format is: +[*epoch*:] *upstream_version* [-*debian_revision*] + +The three components here are: + +*epoch* + This is a single (generally small) unsigned integer. It may be omitted, in + which case zero is assumed. If it is omitted then the *upstream_version* may + not contain any colons. + + It is provided to allow mistakes in the version numbers of older versions + of a package, and also a package's previous version numbering schemes, to + be left behind. + +*upstream_version* + This is the main part of the version number. It is usually the version + number of the original ("upstream") package from which the :file:`.deb` + file has been made, if this is applicable. Usually this will be in the same + format as that specified by the upstream author(s); however, it may need to + be reformatted to fit into the package management system's format and + comparison scheme. + + The comparison behavior of the package management system with respect to + the *upstream_version* is described below. The *upstream_version* portion + of the version number is mandatory. + + The *upstream_version* may contain only alphanumerics [#f38]_ and the + characters . + - : ~ (full stop, plus, hyphen, colon, tilde) and should + start with a digit. If there is no *debian_revision* then hyphens are not + allowed; if there is no *epoch* then colons are not allowed. + +*debian_revision* + This part of the version number specifies the version of the Ubuntu package + based on the upstream version. It may contain only alphanumerics and the + characters + . ~ (plus, full stop, tilde) and is compared in the same way + as the *upstream_version* is. + + It is optional; if it isn't present then the *upstream_version* may not + contain a hyphen. This format represents the case where a piece of software + was written specifically to be turned into a Debian or Ubuntu package, and + so there is only one "debianisation" of it and therefore no revision + indication is required. + + It is conventional to restart the *debian_revision* at 1 each time the + upstream_version is increased. + + The package management system will break the version number apart at the + last hyphen in the string (if there is one) to determine the + *upstream_version* and *debian_revision*. The absence of a + *debian_revision* is equivalent to a *debian_revision* of 0. + +Ubuntu: The string "ubuntu" in a version number instructs the archive +management software not to copy newer versions of the package from Debian +automatically. It should therefore be used when modifying packages relative to +Debian, taking care that the Ubuntu version number compares less than the next +expected version in Debian. For example, the first Ubuntu modification of +version ``1.0-1`` in Debian would be ``1.0-1ubuntu1``. + +When comparing two version numbers, first the *epoch* of each are compared, then +the *upstream_version* if *epoch* is equal, and then *debian_revision* if +*upstream_version* is also equal. *epoch* is compared numerically. The +*upstream_version* and *debian_revision* parts are compared by the package +management system using the following algorithm: + + The strings are compared from left to right. + + First the initial part of each string consisting entirely of non-digit + characters is determined. These two parts (one of which may be empty) are + compared lexically. If a difference is found it is returned. The lexical + comparison is a comparison of ASCII values modified so that all the letters + sort earlier than all the non-letters and so that a tilde sorts before + anything, even the end of a part. For example, the following parts are in + sorted order from earliest to latest: ~~, ~~a, ~, the empty part, a. + [#f39]_ + + Then the initial part of the remainder of each string which consists + entirely of digit characters is determined. The numerical values of these + two parts are compared, and any difference found is returned as the result + of the comparison. For these purposes an empty string (which can only occur + at the end of one or both version strings being compared) counts as zero. + + These two steps (comparing and removing initial non-digit strings and + initial digit strings) are repeated until a difference is found or both + strings are exhausted. + + Note that the purpose of epochs is to allow us to leave behind mistakes in + version numbering, and to cope with situations where the version numbering + scheme changes. It is not intended to cope with version numbers containing + strings of letters which the package management system cannot interpret + (such as ``ALPHA`` or ``pre-``), or with silly orderings (the author of + this manual has heard of a package whose versions went ``1.1, 1.2, 1.3, 1, + 2.1, 2.2, 2`` and so forth). + +.. _ubuntu-policy-description-field: + +5.6.13 ``Description`` +^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.13 +`_) + +.. _ubuntu-policy-distribution-field: + +5.6.14 ``Distribution`` +^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.14 +`_) + +.. _ubuntu-policy-date-field: + +5.6.15 ``Date`` +^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.15 +`_) + +.. _ubuntu-policy-format-field: + +5.6.16 ``Format`` +^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 5.6.16 +`_) + +This field specifies a format revision for the file. The most current format +described in the Policy Manual is version **1.8**. The syntax of the format +value is the same as that of a package version number except that no epoch or +Debian revision is allowed - see :ref:`Version, Section 5.6.12 +`. + +.. _ubuntu-policy-urgency-field: + +5.6.17 ``Urgency`` +^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.17 +`_) + +.. _ubuntu-policy-changes-field: + +5.6.18 ``Changes`` +^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.18 +`_) + +.. _ubuntu-policy-binary-field: + +5.6.19 ``Binary`` +^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.19 +`_) + +.. _ubuntu-policy-installed-size-field: + +5.6.20 ``Installed-Size`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.20 +`_) + +.. _ubuntu-policy-files-field: + +5.6.21 ``Files`` +^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.21 +`_) + +.. _ubuntu-policy-closes-field: + +5.6.22 ``Closes`` +^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.22 +`_) + +.. _ubuntu-policy-launchpad-bugs-fixed-field: + +5.6.23 ``Launchpad-Bugs-Fixed`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A space-separated list of Launchpad bug report numbers that the upload governed +by the :file:`.changes` file closes. + +.. _ubuntu-policy-homepage-field: + +5.6.24 ``Homepage`` +^^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.6.24 +`_) + +---- + +5.7 User-defined fields +~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 5.7 +`_) + +---- + +:doc:`← (Chapter 4 - Source packages) <4-source-packages>` | :ref:`(Chapter 6 - Package maintainer scripts) → ` + +---- + +.. [#f32] + :pkg:`dpkg`'s internal databases are in a similar format. +.. [#f33] + The paragraphs are also sometimes referred to as stanzas. +.. [#f37] + In the past, people specified the full version number in the + Standards-Version field, for example "2.3.0.0". Since minor patch-level + changes don't introduce new policy, it was thought it would be better to + relax policy and only require the first 3 components to be specified, in + this example "2.3.0". All four components may still be used if someone + wishes to do so. +.. [#f38] + Alphanumerics are ``A-Za-z0-9`` only. +.. [#f39] + One common use of ``~`` is for upstream pre-releases. For example, + ``1.0~beta1~svn1245`` sorts earlier than ``1.0~beta1``, which sorts earlier + than ``1.0``. diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/6-package-maintainer-scripts.rst b/docs/how-ubuntu-is-made/ubuntu-policy/6-package-maintainer-scripts.rst new file mode 100644 index 000000000..ca5cff107 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/6-package-maintainer-scripts.rst @@ -0,0 +1,9 @@ +.. _chapter-6-package-maintainer-scripts: + +Chapter 6 - Package maintainer scripts and installation procedure +----------------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual Chapter 6 +`_) + +:ref:`← (Chapter 5 - Control files and their fields) ` | :ref:`(Chapter 7 - Declaring dependencies) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/7-declaring-relationships.rst b/docs/how-ubuntu-is-made/ubuntu-policy/7-declaring-relationships.rst new file mode 100644 index 000000000..fc65055c4 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/7-declaring-relationships.rst @@ -0,0 +1,105 @@ +.. _chapter-7-declaring-relationships: + +Chapter 7 - Declaring relationships between packages +---------------------------------------------------- + +.. _ubuntu-policy-syntax-of-relationship-fields: + +7.1 Syntax of relationship fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.1 +`_) + +---- + +.. _ubuntu-policy-binary-deps: + +7.2 Binary Dependencies - ``Depends``, ``Recommends``, ``Suggests``, ``Enhances``, and ``Pre-Depends`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.2 +`_) + +---- + +7.3 Packages which break other packages - ``Breaks`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: This section should be considered outdated as it was + written before the stable release of Debian supported ``Breaks``. The use + of ``Breaks`` is now common in Debian and Ubuntu packages, and the issues + mentioned in this section are no longer relevant. Consider sharing it with + the Debian Policy Manual, and updating it to reflect the current state of + affairs. + +(*Modifies*: `Debian Policy Manual, Section 7.3 +`_) + +Using ``Breaks`` may cause problems for upgrades from older versions of Debian +and should not be used until the stable release of Debian supports ``Breaks``. + +Ubuntu: ``Breaks`` may safely be used in Ubuntu packages, as all supported upgrade +paths to current releases involve upgrading :pkg:`dpkg` to a version that +supports ``Breaks``. + +When one binary package declares that it breaks another, :pkg:`dpkg` will +refuse to allow the package which declares ``Breaks`` be installed unless the +broken package is deconfigured first, and it will refuse to allow the broken +package to be reconfigured. + +A package will not be regarded as causing breakage merely because its +configuration files are still installed; it must be at least half-installed. + +A special exception is made for packages which declare that they break their +own package name or a virtual package which they provide (see below): this does +not count as a real breakage. + +Normally a ``Breaks`` entry will have an "earlier than" version clause; such a +``Breaks`` is introduced in the version of an (implicit or explicit) dependency +which violates an assumption or reveals a bug in earlier versions of the broken +package. This use of ``Breaks`` will inform higher-level package management +tools that broken package must be upgraded before the new one. + +If the breaking package also overwrites some files from the older package, it +should use ``Replaces`` (not ``Conflicts``) to ensure this goes smoothly. + +---- + +.. _ubuntu-policy-conflicting-binary-packages: + +7.4 Conflicting binary packages - ``Conflicts`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.4 +`_) + +---- + +7.5 Virtual packages - ``Provides`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.5 +`_) + +---- + +7.6 Replacing files from other packages - ``Replaces`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.6 +`_) + +---- + +.. _ubuntu-policy-build-depends: + +7.7 Declaring relationships between source packages - ``Build-Depends``, ``Build-Depends-Indep``, ``Build-Conflicts``, ``Build-Conflicts-Indep`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 7.7 +`_) + +---- + +:ref:`← (Chapter 6 - Package maintainer scripts) ` | :ref:`(Chapter 8 - Shared libraries) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/8-shared-libraries.rst b/docs/how-ubuntu-is-made/ubuntu-policy/8-shared-libraries.rst new file mode 100644 index 000000000..4ac2d7e80 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/8-shared-libraries.rst @@ -0,0 +1,469 @@ +.. _chapter-8-shared-libraries: + +Chapter 8 - Shared libraries +---------------------------- + + **Editor's note**: This chapter is similar to the current Debian Policy + Manual Chapter 8, but has some differences in its content. Review is + suggested. + +(*Modifies*: `Debian Policy Manual, Chapter 8 +`_) + +Packages containing shared libraries must be constructed with a little care to +make sure that the shared library is always available. This is especially +important for packages whose shared libraries are vitally important, such as +the C library (currently ``libc6``). + +Packages involving shared libraries should be split up into several binary +packages. This section mostly deals with how this separation is to be +accomplished; rules for files within the shared library packages are in +:ref:`Libraries, Section 10.2 ` instead. + +---- + +8.1 Run-time shared libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Modifies*: `Debian Policy Manual, Section 8.1 +`_) + +The run-time shared library needs to be placed in a package whose name changes +whenever the shared object version changes. [#f50]_ The most common mechanism +is to place it in a package called :pkg:`librarynamesoversion`, where +``soversion`` is the version number in the soname of the shared library +[#f51]_. Alternatively, if it would be confusing to directly append +``soversion`` to ``libraryname`` (e.g. because ``libraryname`` itself ends in a +number), you may use :pkg:`libraryname-soversion` and +:pkg:`libraryname-soversion-dev` instead. + +If you have several shared libraries built from the same source tree you may +lump them all together into a single shared library package, provided that you +change all of their sonames at once (so that you don't get filename clashes if +you try to install different versions of the combined shared libraries +package). + +The package should install the shared libraries under their normal names. For +example, the :pkg:`libgdbm3` package should install :file:`libgdbm.so.3.0.0` as +:file:`/usr/lib/libgdbm.so.3.0.0`. The files should not be renamed or re-linked +by any ``prerm`` or ``postrm`` scripts; :pkg:`dpkg` will take care of renaming +things safely without affecting running programs, and attempts to interfere +with this are likely to lead to problems. + +Shared libraries should not be installed executable, since the dynamic linker +does not require this and trying to execute a shared library usually results in +a core dump. + +The run-time library package should include the symbolic link that ``ldconfig`` +would create for the shared libraries. For example, the :pkg:`libgdbm3` package +should include a symbolic link from :file:`/usr/lib/libgdbm.so.3` to +:file:`libgdbm.so.3.0.0`. This is needed so that the dynamic linker (for +example :file:`ld.so` or :file:`ld-linux.so.*`) can find the library between +the time that dpkg installs it and the time that ``ldconfig`` is run in the +``postinst`` script. [#f52]_ + +---- + +8.1.1 ``ldconfig`` +^^^^^^^^^^^^^^^^^^ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 8.1.1 +`_) + +---- + +8.2 Shared library support files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 8.2 +`_) + +---- + +8.3 Static libraries +~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian, see:* `Debian Policy Manual, Section 8.3 +`_) + +---- + +8.4 Development files +~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: This section contradicts the current Debian + Policy Manual regarding package names. Review is suggested. + +(*Modifies*: `Debian Policy Manual, Section 8.4 +`_) + +The development files associated to a shared library need to be placed in a +package called :pkg:`librarynamesoversion-dev`, or if you prefer only to support one +development version at a time, :pkg:`libraryname-dev`. + +In case several development versions of a library exist, you may need to use +:pkg:`dpkg`'s Conflicts mechanism (see :ref:`Conflicting binary packages - +Conflicts, Section 7.4 `) to ensure +that the user only installs one development version at a time (as different +development versions are likely to have the same header files in them, which +would cause a filename clash if both were installed). + +The development package should contain a symlink for the associated shared +library without a version number. For example, the :pkg:`libgdbm-dev` package +should include a symlink from :file:`/usr/lib/libgdbm.so` to +:file:`libgdbm.so.3.0.0`. This symlink is needed by the linker (``ld``) when +compiling packages, as it will only look for :file:`libgdbm.so` when compiling +dynamically. + +---- + +8.5 Dependencies between the packages of the same library +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(*Shared with Debian:* `Debian Policy Manual, Section 8.5 +`_) + +---- + +8.6 Dependencies between the library and other packages - the ``shlibs`` system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + **Editor's note**: ``shlibs`` has largely been superseded by the + ``symbols`` system. + +(*Modifies*: `Debian Policy Manual, Section 8.6 +`_) + + If a package contains a binary or library which links to a shared library, we + must ensure that when the package is installed on the system, all of the + libraries needed are also installed. This requirement led to the creation of + the ``shlibs`` system, which is very simple in its design: any package which + *provides* a shared library also provides information on the package + dependencies required to ensure the presence of this library, and any package + which *uses* a shared library uses this information to determine the + dependencies it requires. The files which contain the mapping from shared + libraries to the necessary dependency information are called ``shlibs`` files. + +Thus, when a package is built which contains any shared libraries, it must +provide a ``shlibs`` file for other packages to use, and when a package is +built which contains any shared libraries or compiled binaries, it must run +:ref:`dpkg-shlibdeps ` on these to +determine the libraries used and hence the dependencies needed by this +package. [#f57]_ + +In the following sections, we will first describe where the various ``shlibs`` +files are to be found, then how to use :ref:`dpkg-shlibdeps +`, and finally the ``shlibs``` file +format and how to create them if your package contains a shared library. + +8.6.1 The ``shlibs`` files present on the system +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 8.6.4.1 +`_) + +There are several places where shlibs files are found. The following list gives +them in the order in which they are read by dpkg-shlibdeps. (The first one +which gives the required information is used.) + +:file:`debian/shlibs.local` + This lists overrides for this package. Its use is described below (see + :ref:`Writing the debian/shlibs.local file, Section 8.6.5 + `). + +:file:`/etc/dpkg/shlibs.override` + This lists global overrides. This list is normally empty. It is maintained + by the local system administrator. + +:file:`DEBIAN/shlibs` files in the "build directory" + When packages are being built, any :file:`debian/shlibs` files are copied + into the control file area of the temporary build directory and given the + name shlibs. These files give details of any shared libraries included in + the package. [#f58]_ + +:file:`/var/lib/dpkg/info/*.shlibs` + These are the shlibs files corresponding to all of the packages installed + on the system, and are maintained by the relevant package maintainers. + +:file:`/etc/dpkg/shlibs.default` + This file lists any shared libraries whose packages have failed to provide + correct ``shlibs`` files. It was used when the ``shlibs`` setup was first + introduced, but it is now normally empty. It is maintained by the :pkg:`dpkg` + maintainer. + +8.6.2 How to use ``dpkg-shlibdeps`` and the ``shlibs`` files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Put a call to :ref:`dpkg-shlibdeps ` +into your :file:`debian/rules` file. If your package contains only compiled +binaries and libraries (but no scripts), you can use a command such as: + +.. code-block:: bash + + dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ + debian/tmp/usr/lib/* + +Otherwise, you will need to explicitly list the compiled binaries and +libraries. [#f59]_ + +This command puts the dependency information into the :file:`debian/substvars` +file, which is then used by ``dpkg-gencontrol``. You will need to place a +``${shlibs:Depends}`` variable in the ``Depends`` field in the control file for +this to work. + +If ``dpkg-shlibdeps`` doesn't complain, you're done. If it does complain you +might need to create your own :file:`debian/shlibs.local` file, as explained +below (see `Writing the debian/shlibs.local file, Section 8.6.5 +`). + +If you have multiple binary packages, you will need to call ``dpkg-shlibdeps`` +on each one which contains compiled libraries or binaries. In such a case, you +will need to use the ``-T`` option to the :pkg:`dpkg` utilities to specify a different +substvars file. + +If you are creating a udeb for use in the Debian Installer, you will need to +specify that ``dpkg-shlibdeps`` should use the dependency line of type ``udeb`` +by adding ``-tudeb`` as option [#f60]_. If there is no dependency line of type +``udeb`` in the :file:`shlibs` file, ``dpkg-shlibdeps`` will fall back to the +regular dependency line. + +For more details on ``dpkg-shlibdeps``, please see :ref:`dpkg-shlibdeps - +calculates shared library dependencies, Section C.1.4 +` and :manpage:`dpkg-shlibdeps(1)`. + +8.6.3 The ``shlibs`` File Format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 8.6.4.2 +`_) + +Each ``shlibs`` file has the same format. Lines beginning with ``#`` are +considered to be comments and are ignored. Each line is of the form: + +.. code-block:: none + + [type: ]library-name soname-version dependencies ... + +We will explain this by reference to the example of the :pkg:`zlib1g` package, +which (at the time of writing) installs the shared library +:file:`/usr/lib/libz.so.1.1.3`. + +*type* is an optional element that indicates the type of package for which the +line is valid. The only type currently in use is udeb. The colon and space +after the type are required. + +*library-name* is the name of the shared library, in this case :pkg:`libz`. +(This must match the name part of the soname, see below.) + +*soname-version* is the version part of the soname of the library. The soname +is the thing that must exactly match for the library to be recognized by the +dynamic linker, and is usually of the form ``name.so.major-version``, in our +example, :file:`libz.so.1`. [#f61]_ The version part is the part which comes +after ``.so.``, so in our case, it is 1. + +*dependencies* has the same syntax as a dependency field in a binary package +control file. It should give details of which packages are required to satisfy +a binary built against the version of the library contained in the package. See +:ref:`Syntax of relationship fields, Section 7.1 +` for details. + +In our example, if the first version of the :pkg:`zlib1g` package which +contained a minor number of at least ``1.3`` was ``1:1.1.3-1``, then the +``shlibs`` entry for this library could say: + +.. code-block:: none + + libz 1 zlib1g (>= 1:1.1.3) + +The version-specific dependency is to avoid warnings from the dynamic linker +about using older shared libraries with newer binaries. + +As :pkg:`zlib1g` also provides a udeb containing the shared library, there +would also be a second line: + +.. code-block:: none + + udeb: libz 1 zlib1g-udeb (>= 1:1.1.3) + +8.6.4 Providing a ``shlibs`` file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +(*Modifies*: `Debian Policy Manual, Section 8.6.4.3 +`_) + +If your package provides a shared library, you need to create a ``shlibs`` file +following the format described above. It is usual to call this file +:file:`debian/shlibs` (but if you have multiple binary packages, you might want +to call it :file:`debian/shlibs.package` instead). Then let +:file:`debian/rules` install it in the control area: + +.. code-block:: none + + install -m644 debian/shlibs debian/tmp/DEBIAN + +or, in the case of a multi-binary package: + +.. code-block:: none + + install -m644 debian/shlibs.package debian/package/DEBIAN/shlibs + +An alternative way of doing this is to create the ``shlibs`` file in the +control area directly from :file:`debian/rules` without using a +:file:`debian/shlibs` file at all, [#f62]_ since the :file:`debian/shlibs` file +itself is ignored by ``dpkg-shlibdeps``. + +As dpkg-shlibdeps reads the :file:`DEBIAN/shlibs` files in all of the binary +packages being built from this source package, all of the :file:`DEBIAN/shlibs` +files should be installed before ``dpkg-shlibdeps`` is called on any of the +binary packages. + +.. _ubuntu-policy-writing-the-debian-shlibs-local-file: + +8.6.5 Writing the ``debian/shlibs.local`` file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This file is intended only as a *temporary* fix if your binaries or libraries +depend on a library whose package does not yet provide a correct ``shlibs`` +file. + +We will assume that you are trying to package a binary ``foo``. When you try +running ``dpkg-shlibdeps`` you get the following error message (``-O`` displays +the dependency information on stdout instead of writing it to +:file:`debian/substvars`, and the lines have been wrapped for ease of reading): + +.. code-block:: shell + + $ dpkg-shlibdeps -O debian/tmp/usr/bin/foo + dpkg-shlibdeps: warning: unable to find dependency + information for shared library libbar (soname 1, + path /usr/lib/libbar.so.1, dependency field Depends) + shlibs:Depends=libc6 (>= 2.2.2-2) + +You can then run ``ldd`` on the binary to find the full location of the library +concerned: + +.. code-block:: shell + + $ ldd foo + libbar.so.1 => /usr/lib/libbar.so.1 (0x4001e000) + libc.so.6 => /lib/libc.so.6 (0x40032000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) + +So the ``foo`` binary depends on the ``libbar`` shared library, but no package +seems to provide a :file:``*.shlibs`` file handling :file:`libbar.so.1` in +:file:`/var/lib/dpkg/info/`. Let's determine the package responsible: + +.. code-block:: shell + + $ dpkg -S /usr/lib/libbar.so.1 + bar1: /usr/lib/libbar.so.1 + $ dpkg -s bar1 | grep Version + Version: 1.0-1 + +This tells us that the :pkg:`bar1` package, version ``1.0-1``, is the one we +are using. Now we can file a bug against the :pkg:`bar1` package and create our +own :file:`debian/shlibs.local` to locally fix the problem. Including the +following line into your :file:`debian/shlibs.local` file: + +.. code-block:: none + + libbar 1 bar1 (>= 1.0-1) + +should allow the package build to work. + +As soon as the maintainer of :pkg:`bar1` provides a correct ``shlibs`` file, +you should remove this line from your :file:`debian/shlibs.local` file. (You +should probably also then have a versioned ``Build-Depends`` on :pkg:`bar1` to +help ensure that others do not have the same problem building your package.) + +---- + +:ref:`← (Chapter 7 - Declaring relationships) ` | :ref:`(Chapter 9 - The Operating System) → ` + +---- + +.. [#f50] + Since it is common place to install several versions of a package that just + provides shared libraries, it is a good idea that the library package should + not contain any extraneous non-versioned files, unless they happen to be in + versioned directories. +.. [#f51] + The soname is the shared object name: it's the thing that has to match + exactly between building an executable and running it for the dynamic linker + to be able run the program. For example, if the soname of the library is + :file:`libfoo.so.6`, the library package would be called :pkg:`libfoo6`. +.. [#f52] + The package management system requires the library to be placed before the + symbolic link pointing to it in the :file:`.deb` file. This is so that when + :pkg:`dpkg` comes to install the symlink (overwriting the previous symlink + pointing at an older version of the library), the new shared library is + already in place. In the past, this was achieved by creating the library in + the temporary packaging directory before creating the symlink. + Unfortunately, this was not always effective, since the building of the tar + file in the :file:`.deb` depended on the behavior of the underlying file + system. Some file systems (such as reiserfs) reorder the files so that the + order of creation is forgotten. Since version 1.7.0, :pkg:`dpkg` reorders + the files itself as necessary when building a package. Thus it is no longer + important to concern oneself with the order of file creation. +.. [#f57] + In the past, the shared libraries linked to were determined by calling + ``ldd``, but now ``objdump`` is used to do this. The only change this makes + to package building is that ``dpkg-shlibdeps`` must also be run on shared + libraries, whereas in the past this was unnecessary. The rest of this + footnote explains the advantage that this method gives. + + We say that a binary ``foo`` directly uses a library ``libbar`` if it is + explicitly linked with that library (that is, it uses the flag ``-lbar`` + during the linking stage). Other libraries that are needed by ``libbar`` are + linked indirectly to ``foo``, and the dynamic linker will load them + automatically when it loads ``libbar``. A package should depend on the + libraries it directly uses, and the dependencies for those libraries should + automatically pull in the other libraries. + + Unfortunately, the ``ldd`` program shows both the directly and indirectly + used libraries, meaning that the dependencies determined included both + direct and indirect dependencies. The use of ``objdump`` avoids this problem + by determining only the directly used libraries. + + A good example of where this helps is the following. We could update + ``libimlib`` with a new version that supports a new graphics format called + ``dgf`` (but retaining the same major version number). If we used the old + ``ldd`` method, every package that uses ``libimlib`` would need to be + recompiled so it would also depend on ``libdgf`` or it wouldn't run due to + missing symbols. However with the new system, packages using ``libimlib`` + can rely on ``libimlib`` itself having the dependency on ``libdgf`` and so + they would not need rebuilding. +.. [#f58] + An example may help here. Let us say that the source package foo generates + two binary packages, :pkg:`libfoo2` and :pkg:`foo-runtime`. When building + the binary packages, the two packages are created in the directories + :file:`debian/libfoo2` and :file:`debian/foo-runtime` respectively. + (:file:`debian/tmp` could be used instead of one of these.) Since + :pkg:`libfoo2` provides the :pkg:`libfoo` shared library, it will require a + ``shlibs`` file, which will be installed in + :file:`debian/libfoo2/DEBIAN/shlibs`, eventually to become + :file:`/var/lib/dpkg/info/libfoo2.shlibs`. Then when ``dpkg-shlibdeps`` is + run on the executable :file:`debian/foo-runtime/usr/bin/foo-prog`, it will + examine the :file:`debian/libfoo2/DEBIAN/shlibs` file to determine whether + :pkg:`foo-prog`'s library dependencies are satisfied by any of the libraries + provided by :pkg:`libfoo2`. For this reason, ``dpkg-shlibdeps`` must only be + run once all of the individual binary packages' ``shlibs`` files have been + installed into the build directory. +.. [#f59] + If you are using ``debhelper``, the ``dh_shlibdeps`` program will do this + work for you. It will also correctly handle multi-binary packages. +.. [#f60] + ``dh_shlibdeps`` from the ``debhelper`` suite will automatically add this option if + it knows it is processing a udeb. +.. [#f61] + This can be determined using the command + + .. code-block:: shell + + objdump -p /usr/lib/libz.so.1.1.3 | grep SONAME +.. [#f62] + This is what ``dh_makeshlibs`` in the ``debhelper`` suite does. If your + package also has a udeb that provides a shared library, ``dh_makeshlibs`` + can automatically generate the udeb: lines if you specify the name of the + udeb with the ``--add-udeb`` option. + diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/9-the-operating-system.rst b/docs/how-ubuntu-is-made/ubuntu-policy/9-the-operating-system.rst new file mode 100644 index 000000000..cc881cfec --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/9-the-operating-system.rst @@ -0,0 +1,14 @@ +.. _chapter-9-the-operating-system: + +Chapter 9 - The Operating System +-------------------------------- + + **Editor's note**: This chapter is significantly outdated in the Ubuntu + policy (uses FHS version 2.3 when Debian is 3.0) and as such is currently + considered shared with Debian. It should be reviewed to reflect the current + state of affairs in Ubuntu. + +(*Shared with Debian, see:* `Debian Policy Manual Chapter 9 +`_) + +:ref:`← (Chapter 8 - Shared libraries) ` | :ref:`(Chapter 10 - Files) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-a.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-a.rst new file mode 100644 index 000000000..786ce6401 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-a.rst @@ -0,0 +1,9 @@ +.. _appendix-a: + +Appendix A - Introduction and scope of these appendices +------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 1 +`_) + +:ref:`← (Chapter 12 - Documentation) ` | :ref:`(Appendix B) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-b.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-b.rst new file mode 100644 index 000000000..5918b6164 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-b.rst @@ -0,0 +1,9 @@ +.. _appendix-b: + +Appendix B - Binary packages (from old Packaging Manual) +-------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 2 +`_) + +:ref:`← (Appendix A) ` | :ref:`(Appendix C) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-c.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-c.rst new file mode 100644 index 000000000..3c4032590 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-c.rst @@ -0,0 +1,10 @@ +.. _ubuntu-policy-appendix-c-dkpg-shlibdeps: +.. _appendix-c: + +Appendix C - Source packages (from old Packaging Manual) +-------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 3 +`_) + +:ref:`← (Appendix B) ` | :ref:`(Appendix D) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-d.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-d.rst new file mode 100644 index 000000000..6517efe04 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-d.rst @@ -0,0 +1,10 @@ +.. _ubuntu-policy-appendix-d-control-files: +.. _appendix-d: + +Appendix D - Control files and their fields (from old Packaging Manual) +----------------------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 4 +`_) + +:ref:`← (Appendix C) ` | :ref:`(Appendix E) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-e.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-e.rst new file mode 100644 index 000000000..67515d46c --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-e.rst @@ -0,0 +1,9 @@ +.. _appendix-e: + +Appendix E - Configuration file handling (from old Packaging Manual) +-------------------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 5 +`_) + +:ref:`← (Appendix D) ` | :ref:`(Appendix F) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-f.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-f.rst new file mode 100644 index 000000000..32d2653e1 --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-f.rst @@ -0,0 +1,9 @@ +.. _appendix-f: + +Appendix F - Alternative versions of an interface - ``update-alternatives`` (from old Packaging Manual) +------------------------------------------------------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 6 +`_) + +:ref:`← (Appendix E) ` | :ref:`(Appendix G) → ` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/appendix-g.rst b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-g.rst new file mode 100644 index 000000000..efe6e544f --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/appendix-g.rst @@ -0,0 +1,10 @@ +.. _appendix-g: + +Appendix G - Diversions - overriding a package's version of a file (from old Packaging Manual) +---------------------------------------------------------------------------------------------- + +(*Shared with Debian, see:* `Debian Policy Manual, Appendix 7 +`_) + +:ref:`← (Appendix F) ` | :ref:`(Ubuntu Policy Manual) → +` diff --git a/docs/how-ubuntu-is-made/ubuntu-policy/index.rst b/docs/how-ubuntu-is-made/ubuntu-policy/index.rst new file mode 100644 index 000000000..971c4215f --- /dev/null +++ b/docs/how-ubuntu-is-made/ubuntu-policy/index.rst @@ -0,0 +1,100 @@ +.. _ubuntu-policy: + +Ubuntu Policy Manual +==================== + +:Authors: The Debian Policy Mailing List; The Ubuntu Developers Mailing List +:Version: 4.7.3 + +---- + + +.. _ubuntu-policy-abstract: + +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 `_ +and if not stated otherwise, the requirements of that apply to Ubuntu as well. + +---- + +Copyright notice +---------------- + + +Copyright © 1996,1997,1998 Ian Jackson and Christian Schwarz. + +This file has been modified by Simon Johnsson on Feb 26, 2026. + +:**Modifications**: + + - Change distribution method from the :pkg:`ubuntu-policy` package to + Ubuntu docs website. + - Omit section content equal to the Debian Policy Manual, and refer to the + Debian Policy Manual instead, noted as "(*Shared with Debian, see:* + `Debian Policy Manual`) and update :ref:`ubuntu-policy-abstract` to + reflect this change. + - Mark chapters and sections different to the Debian Policy Manual with + "(*Modifies*: Debian Policy Manual, ``chapter/section``)". + - Add "**Editor's note:**" to areas that are outdated, need + clarification, and/or re-review. + - Update number of packages in :ref:`chapter-2-ubuntu-archive`. + - Update format version in :ref:`Section 5.6.16 Format + `. + +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 +:file:`/usr/share/common-licenses/GPL` in the Debian GNU/Linux distribution or on the +World Wide Web at `the GNU General Public Licence +`_. + +---- + +Contents +-------- + +.. admonition:: Chapters + + .. toctree:: + :maxdepth: 3 + + 1. About this manual <1-about-this-manual> + 2. The Ubuntu Archive <2-ubuntu-archive> + 3. Binary Packages <3-binary-packages> + 4. Source Packages <4-source-packages> + 5. Control files and their fields <5-control-files> + 6. Package maintainer scripts and installation procedure <6-package-maintainer-scripts> + 7. Declaring relationships between packages <7-declaring-relationships> + 8. Shared libraries <8-shared-libraries> + 9. The Operating System <9-the-operating-system> + 10. Files <10-files> + 11. Customized programs <11-customized-programs> + 12. Documentation <12-documentation> + +.. admonition:: Appendices + + .. toctree:: + :maxdepth: 3 + + A. Introduction and scope of these appendices + B. Binary packages + C. Source packages + D. Control files and their fields + E. Configuration file handling + F. Alternative versions of an interface - ``update-alternatives`` + G. Diversions - overriding a package's version of a file + + +:ref:`← (Appendix G) ` | :ref:`(Chapter 1 - About this manual) → `