From 0b795cfd5d3ffda906ed8667324142c5102d5853 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:26:59 +0000 Subject: [PATCH] * Plug-ins != shared libraries (at last) closes Author: jdg Date: 2001/05/24 11:44:11 * Plug-ins != shared libraries (at last) closes: Bug#66023 * Finished cleanup of chapter 13 --> all done! git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-126 --- debian/changelog | 1 + policy.sgml | 200 ++++++++++++++++++++++----------------- upgrading-checklist.html | 2 + 3 files changed, 116 insertions(+), 87 deletions(-) diff --git a/debian/changelog b/debian/changelog index a9a33c8..d7eb454 100644 --- a/debian/changelog +++ b/debian/changelog @@ -30,6 +30,7 @@ debian-policy (3.5.4.1) unstable; urgency=low to find alternative manpage names closes: Bug#94995 * Correction to meaning of Standards-Version closes: Bug#97072 * Split section 12.8 (X Window System) into subsections for readability + * Plug-ins != shared libraries (at last) closes: Bug#66023 -- diff --git a/policy.sgml b/policy.sgml index 33ad04f..0a2a161 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1076,7 +1076,7 @@ debconf, which conforms to the Debian Configuration management specification, version 2 or higher. These are included in the - debconf_specification files in the + debconf_specification files in the debian-policy package. You may also find this file on the FTP site ftp.debian.org in @@ -1112,7 +1112,7 @@

Packages which use the Debian Configuration management specification may contain an additional - config script and a templates + config script and a templates file in their control archive. The config script might be run before the preinst script, and before the package is unpacked or any of its @@ -5455,6 +5455,34 @@ strip --strip-unneeded your-lib building a separate package to support debugging.

+

+ Shared object files (often .so files) that are not + public libraries, that is, they are not meant to be linked + to by third party executables (binaries of other packages), + should be installed in subdirectories of the + /usr/lib directory. Such files are exempt from the + rules that govern ordinary shared libraries, except that + they must not be installed executable and should be + stripped. +

+ A common example are the so-called ``plug-ins'', + internal shared objects that are dynamically loaded by + programs using . +

+ +

+ +

+ Packages containing shared libraries that may be linked to + by other packages' binaries, but which for some + compelling reason can not be installed in + /usr/lib directory, may install the shared library + files in subdirectories of the /usr/lib directory, + in which case they should arrange to add that directory in + /etc/ld.so.conf in the package's post-installation + script, and remove it in the package's post-removal script. +

+

An ever increasing number of packages are using libtool to do their linking. The latest GNU @@ -7218,14 +7246,15 @@ name [`syshostname']:

If no manual page is available for a particular program, - utility, function or configuration file and this is reported as a bug on - debian-bugs, a symbolic link from the requested manual page - to the manual page - may be provided. This symbolic link can be created from + utility, function or configuration file and this is reported + as a bug to the Debian Bug Tracking System, a symbolic link + from the requested manual page to the manual page may be + provided. This symbolic link can be created from debian/rules like this: ln -s ../man7/undocumented.7.gz \ -debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz + debian/tmp/usr/share/man/man[1-9]/requested_manpage.[1-9].gz This manpage claims that the lack of a manpage has been reported as a bug, so you may only do this if it really has @@ -7281,12 +7310,13 @@ debian/tmp/usr/share/man/man[1-9]/the_requested_manpage.[1-9].gz They should be compressed with gzip -9.

- Your package should call install-info to update the Info - dir - file, in its postinst script: + Your package should call install-info to update + the Info dir file in its postinst + script when called with a configure argument, for + example: install-info --quiet --section Development Development \ -/usr/share/info/foobar.info + /usr/share/info/foobar.info

@@ -7301,7 +7331,8 @@ install-info --quiet --section Development Development \ the second is used when creating a new one.

- You should remove the entries in the prerm script: + You should remove the entries in the prerm + script when called with a remove argument: install-info --quiet --remove /usr/share/info/foobar.info

@@ -7309,7 +7340,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

If install-info cannot find a description entry in the Info file you must supply one. See for details.

+ name="install-info" section="8"> for details.

@@ -7318,7 +7349,7 @@ install-info --quiet --remove /usr/share/info/foobar.info

Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. - Text documentation should be installed in a directory + Text documentation should be installed in the directory /usr/share/doc/package, where package is the name of the package, and compressed with gzip -9 unless it is small.

@@ -7344,8 +7375,8 @@ install-info --quiet --remove /usr/share/info/foobar.info delete them without causing any programs to break. Any files that are referenced by programs but are also useful as standalone documentation should be installed under - /usr/share/package/ and symlinked in - /usr/share/doc/package/. + /usr/share/package/ with symbolic links + from /usr/share/doc/package/.

@@ -7368,20 +7399,25 @@ install-info --quiet --remove /usr/share/info/foobar.info it cannot be contained in the package itself due to problems with dpkg. One reasonable way to accomplish this is to put the following in the package's - postinst: + postinst +

+ The debhelper script + dh_installdocs does this automatically. +

+ : if [ "$1" = "configure" ]; then - if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \ - -a -d /usr/share/doc/#PACKAGE# ]; then - ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE# + if [ -d /usr/doc -a ! -e /usr/doc/package \ + -a -d /usr/share/doc/package ]; then + ln -sf ../share/doc/package /usr/doc/package fi fi - And the following in the package's prerm: + and the following in the package's prerm: if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \ - -a -L /usr/doc/#PACKAGE# ]; then - rm -f /usr/doc/#PACKAGE# + -a -L /usr/doc/package ]; then + rm -f /usr/doc/package fi

@@ -7396,20 +7432,23 @@ fi

If your package comes with extensive documentation in a - mark up format that can be converted to various other formats + markup format that can be converted to various other formats you should if possible ship HTML versions in a binary package, in the directory - /usr/share/doc/appropriate package or its - subdirectories. -

The rationale: The important thing here is that HTML + /usr/share/doc/appropriate-package or + its subdirectories. +

+ The rationale: The important thing here is that HTML docs should be available in some package, not - necessarily in the main binary package, though.

+ necessarily in the main binary package. +

- Other formats such as PostScript may be provided at your - option.

+ Other formats such as PostScript may be provided at the + package maintainer's discretion. +

@@ -7418,8 +7457,9 @@ fi

Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file - /usr/share/doc/package/copyright. This file must - neither be compressed nor be a symbolic link.

+ /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 @@ -7431,44 +7471,27 @@ fi

A copy of the file which will be installed in - /usr/share/doc/package/copyright should be - in debian/copyright.

- + /usr/share/doc/package/copyright should + be in debian/copyright in the source package. +

- /usr/share/doc/package may be a symbolic link to a - directory in /usr/share/doc only if two packages both come from - the same source and the first package has a "Depends" - relationship on the second. These rules are important - because copyrights must be extractable by mechanical - means.

+ /usr/share/doc/package may be a symbolic + link to another directory in /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 Artistic license, the GNU GPL, and the GNU LGPL should refer to the - files /usr/share/common-licenses/BSD, - /usr/share/common-licenses/Artistic, - /usr/share/common-licenses/GPL, and - /usr/share/common-licenses/LGPL. -

- Why "licenses" and not "copyright"? Because - /usr/doc/copyright used to contain all the - copyright files, plus the four common licenses GPL, - LGPL, Artistic and BSD. Now individual copyright files - for packages are no longer in a common directory. Once - /usr/doc/copyright is almost empty it makes - sense to rename "copyright" to "licenses" -

-

- Why "common-licenses" and not "licenses"? Because if I - put just "licenses" I'm sure I will receive a bug report - saying "license foo is not included in the licenses - directory. They are not all the licenses, just a few - common ones. I could use /usr/share/doc/common-licenses - but I think this is too long, and, after all, the GPL - does not "document" anything, it is merely a license. -

- + files /usr/share/common-licenses/BSD, + /usr/share/common-licenses/Artistic, + /usr/share/common-licenses/GPL, and + /usr/share/common-licenses/LGPL respectively, + rather than quoting them in the copyright file.

@@ -7486,46 +7509,49 @@ fi should be installed in a directory /usr/share/doc/package/examples. These files should not be referenced by any program: they're there - for the benefit of the system administrator and users, as - documentation only. Architecture-specific example files + for the benefit of the system administrator and users as + documentation only. Architecture-specific example files should be installed in a directory - /usr/lib/package/examples, and files in - /usr/share/doc/package/examples symlink - to files in it. Or the latter directory may be a symlink to - the former.

+ /usr/lib/package/examples with symbolic + links to them from + /usr/share/doc/package/examples, or the + latter directory itself may be a symbolic link to the + former. +

Changelog files

- Packages that are not Debian-native must contain a copy of - debian/changelog file from the Debian source tree - in /usr/share/doc/package as - changelog.Debian.gz. If an upstream changelog is + Packages that are not Debian-native must contain a + compressed copy of the debian/changelog file from + the Debian source tree in + /usr/share/doc/package with the name + changelog.Debian.gz. If an upstream changelog is available, it should be accessible as /usr/share/doc/package/changelog.gz in - plain text. If the upstream changelog is distributed in + plain text. If the upstream changelog is distributed in HTML, it should be made available in that form as /usr/share/doc/package/changelog.html.gz - and the changelog.gz should be generated using, eg, - lynx -dump -nolist. If the upstream changelog files - do not already conform to this naming convention, then this - may be achieved either by renaming the files, or adding a - symbolic link, at the maintainer's discretion. + and a plain text changelog.gz should be generated + from it using, for example, lynx -dump -nolist. If + the upstream changelog files do not already conform to this + naming convention, then this may be achieved either by + renaming the files, or by adding a symbolic link, at the + maintainer's discretion.

- Rationale: People should not have to look into two - places for upstream changelogs merely because they are - in HTML format. + Rationale: People should not have to look in places for + upstream changelogs merely because they are given + different names or are distributed in HTML format.

-

- All these files should be installed compressed using gzip -9, - as they will become large with time even if they start out - small. + All of these files should be installed compressed using + gzip -9, as they will become large with time even + if they start out small.

diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 329f8a6..3a27deb 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -65,6 +65,8 @@ picking your way through this list. dpkg-statoverride; this does not have the weight of policy - Clarify Standards-Version: you don't need to rebuild your packages just to change the Standards-Version! + - Plugins are no longer bound by all the rules of shared + libraries [11.2] - X Windows related things: * Clarification of priority levels of X Window System related packages [12.8.1] -- 2.39.2