From efac5ae0f24ae1331d9afe0b9bbba8e2484a4189 Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:09:22 +0000 Subject: [PATCH] * There have been numerous changes since the last major change, and Author: srivasta Date: 2001/01/29 04:04:59 * There have been numerous changes since the last major change, and peole have had tiome now to review the recent changes, so I am updating the policy minor version to reflect the quantity and magnitude of changes since 3.2.1 * More spelling corrections, thanks to "Christian T. Steigies" * Added mention of DEB_BUILD_OPTIONS in upgrading checklist. closes: Bug#83924 * Fixed some typos. closes: Bug#83960 * Policy now mentions preinst scripts. closes: Bug#80342 * [AMENDMENT 2000/12/26] allow/document use of Debian Configuration management system (debconf) closes: Bug#80347 * Yet more typo fixes closes: Bug#82743 * document the fact that x font utilities have moved to the package xutils, closes: Bug#82966 * Fixed the date in the virtual package list closes: Bug#83438 * Cleaned up some ephemeral informative foornotes of the polic. Thanks to Branden Robinson closes: Bug#83065 * Corrected reference to the mime policy. closes: Bug#79891 * Corrected reference to the menu policy. closes: Bug#75925 * Added a note to the effect that the example make snippet used to illustrate the DEB_BUILD_OPTIONS environment variable is merely informative, and expanded the example to dismiss any confusion about potential failure due to accidentally trying to strip scripts. closes: Bug#80506 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-70 --- debconf_spec/Makefile | 12 ++ debconf_spec/debconf_specification.xml | 283 +++++++++++++++++++++++++ debconf_spec/html.dsl | 29 +++ debconf_spec/include/commands.xml | 273 ++++++++++++++++++++++++ debconf_spec/include/priorities.xml | 40 ++++ debconf_spec/include/statuscodes.xml | 41 ++++ debconf_spec/include/types.xml | 75 +++++++ debian/changelog | 30 +++ debian/rules | 34 +-- policy.sgml | 249 +++++++++++++--------- upgrading-checklist.html | 15 +- virtual-package-names-list.txt | 2 +- 12 files changed, 963 insertions(+), 120 deletions(-) create mode 100644 debconf_spec/Makefile create mode 100644 debconf_spec/debconf_specification.xml create mode 100644 debconf_spec/html.dsl create mode 100644 debconf_spec/include/commands.xml create mode 100644 debconf_spec/include/priorities.xml create mode 100644 debconf_spec/include/statuscodes.xml create mode 100644 debconf_spec/include/types.xml diff --git a/debconf_spec/Makefile b/debconf_spec/Makefile new file mode 100644 index 0000000..59b0dd7 --- /dev/null +++ b/debconf_spec/Makefile @@ -0,0 +1,12 @@ +all: debconf_specification.txt debconf_specification.html + +%.html: %.xml html.dsl + jade -V nochunks -t sgml -d html.dsl \ + /usr/lib/sgml/declaration/xml.dcl $< > $@ + -tidy -i -m -f /dev/null $@ + +%.txt: %.html + links -dump $< | perl -pe 's/[\r\0]//g' > $@ + +clean: + rm -f *.css *.html *.txt diff --git a/debconf_spec/debconf_specification.xml b/debconf_spec/debconf_specification.xml new file mode 100644 index 0000000..f74791a --- /dev/null +++ b/debconf_spec/debconf_specification.xml @@ -0,0 +1,283 @@ + + + + + +]> +
+ + + + Configuration management + revision 7.0 + + + Wichert + + + Akkerman + + + + The Debian Project + +
wakkerma@debian.org
+ + + + + Joey + + + Hess + + + + The Debian Project + +
joeyh@debian.org
+ + + + + 1998 + + + 1999 + + + 2000 + + + Wichert Akkerman and Joey Hess + + + + + This text is copyright by the authors under the terms of the + BSD license, sans advertising clause. + + + + + + + Introduction + + + Configuration management is quickly becoming a very important issue. + Having programs which do cool stuff is great, but we need to store + their configuration as well. We see more and more different + configuration systems being introduced all the time, which is not very + practical. This text introduces a general configuration management + system which flexible enough to be used for all kinds of applications. + + + + + + Configuration Data + + + + The configuration space + + + All configuration information is stored in what I call the + configuration space. This is a database with a special design + which resembles the method we look at configuration information. + This is done by defining a hierarchy of information. Each package + receives its own space in the hierarchy. Each package is free to + use a flat space, or divide its space further into + sub-hierarchies. If multiple packages share a common purpose they + may use a shared toplevel hierarchy, preferably with the same name + as a shared (virtual) package name (for example, both + mutt and elm + can use mail-reader, + strn and nn + could use news-reader). This + shared tree can also be used as a default, ie a variable + news-reader/nntpserver can be used by + strn if strn/nntpserver + does not exist. + + + Each variable in the configuration space has some information + associated with it. Most importantly, it has a value. It also may + have a set of flags and a set of substitution data. + + + + + + + Templates + + + Each variable in the configuration space is associated with some + meta-data. The minimum meta-data associated with a variable is: + long and short description, type, and default value. The meta-data + is essentially static; the protocol described below does not allow it + to be changed. + + + The meta-data exists in a space with similar naming + properties to the configuration space described above, and typically + one variable in the configuration space will have associated with it + metadata with the same name in the meta-data space. However, this need + not be the case; many different variables can all be associated with + the same meta-data. In effect the meta-data serves as a template + for the configuration variable. + + + + Template information + + + So, what do we need to store in a variable template? Of course we + need a name to identify the template. Template names are made up of + components separated by the character `/' (slash). + Each component is limited to alphanumerics and `+' `-' `.' + (plus, minus, full stop). + + + A type is also needed so data can be verified. Here is a table + of common types; implementations are free to make up more. + &type_table; + + + Of course a default value is useful as well, and + finally we need a description of the variable. We actually use two + descriptions: a short one (limited to 50 characters or so) and an + extended one. + + + The extended description may be word-wrapped by the + FrontEnd. To make separate paragraphs in it, use . + on a line by itself to separate them. Text in the extended + description that is prefaced by additional whitespace will not be + wordwrapped. Both the description and extended + description may have substitutions embedded in them. Ie, + ${foo}. These will be expanded when the + descriptions are displayed. + + + This information is stored in a template file that consists of + stanzas in a rfc-822 compliant format, separated by blank lines. + Here is an example: + +Template: hostname +Type: string +Default: debian +Description: unqualified hostname for this computer + This is the name by which this computer will be known on the network. It + has to be a unique name in your domain. + +Template: domain +Type: string +Description: domain for this computer + This is the domain your computer is a member of. Typically it is + something like "mycompany.com" or "myuniversity.edu". + + + + + + + Configuration frontends + + + Of course applications can use the database and meta-database directly. + But there should be a simple system to interact with the user that is + simple and modular enough to be used with systems ranging from + shell-scripts to Fortran programs. To do this we define a general + frontend that can be driven using the simplest and most common form of + communication: stdin and stdout. + + + Using this simple form of communication gives us a great advantage: it + becomes easy to change the frontend. That means the user can switch + between a console, a graphical or even a web-interface at will. + + + Besides being able to switch between types of frontends there is + another important aspect of a good user interface: user friendliness. + We have to account for the fact that some users know more then others + and change the information we show or ask from the user. We do this by + giving everything a priority and giving the user control over what + kind of questions he wants to see. Experts can request to see + everything, while novices get the option of only seeing only important + questions. Finally there is an option to simply skip all questions, so + it becomes possible to do automatic configuration using default values + or values that are downloaded into the database from a remote + location. This makes it simple for example to install and manage + clusters or lab rooms or do installs for dummies. + + + + + Communication with the frontend + + + This communication between the frontend and the application should be + as simple as possible. Since most IO implementations default to + line-buffered IO, so we use a simple language where each command is + exactly one line. + + + After sending each command to stdout, the client + should read one line from stdin. This is the response to the command, + and it will be in the form of a number followed by whitespace and an + optional string of text. The number is the status code, while the + text provides additional information. + &statuscodes_table; + + + Here are the currently supported commands. + + + &command_list; + + + + + Debian install-time configuration + + + Debian has had an excellent packaging system for a long time now. There is + one thing missing though: a system to handle the configuration of + packages so we don't have to stop the installation every time a package + needs some data from the user or wants to show some information. + + + We want to make a package which does not break older dpkg's, and we + want to be able to get the configuration information before the package + is unpacked. To do this we add two new files, config and templates, to + the control.tar.gz of a .deb package. Since all installation-software + (apt, dselect, dpkg) download the package before installing it, we can + extract this before the package is unpacked. + + + The templates file lists the templates for variables that this package + uses. This is done using the format as used in the example in the + section on templates. + + + The config-file contains a new element, which I call the configmodule. + This is a program that will determine the configuration before the + package is unpacked. This means it is run before + the preinst, and before the package is unpacked! This is done to make + sure that we can use the desired configuration in the preinst if + necessary. + + + How does the configmodule get its information? The configmodule + needs a way to retrieve information from the configuration space, ask + the user for information if necessary, etc. But we don't want to + implement a user interface for each package. To solve this we use a + separate frontend as specified in the section on frontends. + + +
diff --git a/debconf_spec/html.dsl b/debconf_spec/html.dsl new file mode 100644 index 0000000..2774825 --- /dev/null +++ b/debconf_spec/html.dsl @@ -0,0 +1,29 @@ + +]> + + + + + +(define %generate-article-toc% #t) +(define %generate-article-titlepage% #t) +(define %generate-legalnotice-link% #t) +(define (article-titlepage-recto-elements) + (list (normalize "title") + (normalize "subtitle") + (normalize "authorgroup") + (normalize "author") + (normalize "releaseinfo") + (normalize "copyright") + (normalize "pubdate") + (normalize "revhistory") + (normalize "legalnotice") + (normalize "abstract"))) + + + + + + + diff --git a/debconf_spec/include/commands.xml b/debconf_spec/include/commands.xml new file mode 100644 index 0000000..dde75a2 --- /dev/null +++ b/debconf_spec/include/commands.xml @@ -0,0 +1,273 @@ + + + VERSION + number + + + This exchanges with the frontend the protocol version + number that is being used. The current version is + 2.0. Versions in the 2.x series will be + backwards-compatible. You may specify the protocol version + number you are speaking. The frontend will return the version + of the protocol it speaks. If the version you specify is too + low, this command will return the numeric return code + 30. + + + + + CAPB + capabilities + + + This exchanges with the frontend a list of supported capabilities + Capabilities both the frontend and your confmodule support may be + used; the capabilities supported by the frontend are returned by + this command. + + Currently used capabilities + + + + capability + description + + + + + backup + + Backing up to a previous step is supported. + + + + multiselect + + The multiselect data type is supported. For compatability + reasons, you should not ask questions of this type unless + this capability is returned. + + + + +
+ + + + + TITLE + string + + + You can use this command to set a title in the + frontend. This may appear in different ways, depending on the + frontend being used, for example it might change the title + of the frontend's window. If you don't specify anything, a + title will automatically be generated. + + + + + STOP + + + This command tells the frontend you're done talking to it. Typically + the frontend can detect the termination of your program and this + command is not necessary. + + + + + INPUT + priority + question + + + This tells the frontend to display a question (or other type of + item) to the user. question is the name of the + item to display, all other information about the item is retrieved + from the templates described previously. + priority is how important it is that the + user be prompted. The frontend need only ask this question if the + priority is high enough. The question is not displayed until a go + command is given. This allows us to ask multiple questions in a single + screen. Once a question has been displayed to the user and the user has + provided input, the frontend will set the + seen flag. + &priority_table; + + + Note that the frontend decides if the user is actually + prompted or not. If the user has already answered a + question, they are normally not asked it again even if + input is called again. And if the user is ignoring low + priority items, they will not see them. In either of + these cases, this command returns the numeric return code + 30. + + + + + BEGINBLOCK + + + + + ENDBLOCK + + + Some frontends are able to display a number of items to + the user at once. To do this, they need to be given blocks + of input commands, enclosed in the BEGINBLOCK and ENDBLOCK + commands. Blocks can be nested and very advanced frontends + may use this as a user interface hint. + + + + There is an implicit block around any set of INPUT commands + that are not enclosed in an explicit block. + + + + + + GO + + + Shows the current set of accumulated items to the user and lets + them fill in values, etc. If the backup capability is supported + and the user indicates they want to back up a step, this command + returns the numeric return code 30. + + + + + CLEAR + + + Clears the accumulated set of INPUT commands without displaying + them to the user. + + + + + GET question + + + Ask the frontend to tell you how the user answered a question. The + value is returned to you. + + + + + SET + question + value + + + Set the answer of a question to a value. + + + + + RESET question + + + Reset the question to its default value. This includes + resetting flags to their defaults. + + + + + SUBST + question + key + value + + + Questions (and other items) can have substitutions embedded in their + descriptions. These substitutions look like + "${key}". When the question is displayed, + the substitutions are replaced with their values. This + command can be used to set the value of a substitution. + + + + + FGET + question + flag + + + Questions (and other items) can have flags associated with them. The + flags have a value of "true" or + "false". This command returns + the value of a flag. + + + + + FSET + question + flag + value + + + This sets the state of a flag on a question. Valid + states for the flag are "true" and + "false". + + + One common flag is the + "seen" flag. It is normally only set if + a user already seen a question. + Typically, frontends only display questions to users if they have the + seen flag set to "false". Sometimes you want the user to see a + question again -- in these cases you can set the seen flag to + false to force the frontend to redisplay it. + + + + + METAGET + question + field + + + This returns the value of any field of a question (the description, for + example). + + + + + REGISTER + template + question + + + This creates a new question that is bound to a + template. By default each template has an associated + question with the same name. However, any number of + questions can really be associated with a template, and + this lets you create more such questions. + + + + + UNREGISTER + question + + + This removes a question from the database. + + + + + PURGE + + + Call this in your postinst when your package is + purged. It removes all templates and questions your + package has generated. + + diff --git a/debconf_spec/include/priorities.xml b/debconf_spec/include/priorities.xml new file mode 100644 index 0000000..114a9c7 --- /dev/null +++ b/debconf_spec/include/priorities.xml @@ -0,0 +1,40 @@ + + Supported priorities + + + + Priority + Description + + + + + low + + Very trivial items that have defaults that + will work in the vast majority of cases. + + + + medium + + Normal items that have reasonable defaults. + + + + high + + Items that don't have a reasonable + default. + + + + critical + + Items that will probably break + the system without user intervention. + + + + +
diff --git a/debconf_spec/include/statuscodes.xml b/debconf_spec/include/statuscodes.xml new file mode 100644 index 0000000..060d273 --- /dev/null +++ b/debconf_spec/include/statuscodes.xml @@ -0,0 +1,41 @@ + +Numeric status codes + + + + Range + Description + + + + + 0 + success + + + 1-9 + reserved + + + 10-19 + invalid parameters + + + 20-29 + syntax errors + + + 30-99 + command-specific return codes + + + 100-109 + internal errors + + + 110-255 + reserved + + + +
diff --git a/debconf_spec/include/types.xml b/debconf_spec/include/types.xml new file mode 100644 index 0000000..4112ee1 --- /dev/null +++ b/debconf_spec/include/types.xml @@ -0,0 +1,75 @@ + + Available data types + + + + Type + Description + + + + + string + Holds any arbitrary string of data. + + + boolean + + Holds "true" or "false". + + + + select + + Holds one of a finite number of possible values. These + values must be specified in a field named + Choices:. Separate the possible values + with commas and spaces, like this: + + Choices: yes, no, maybe + + + + + multiselect + + Just like the select data type, except the user can choose any + number of items from the list. This means that the + Default: field and the actual value of the + question may be a comma and space delimited list of values, + just like the Choices: field. + + + + note + + This template is a note that can be displayed to the user. As + opposed to text, it is something important, that the user really + should see. If it is not possible to display it, it might be + saved to a log file or mailbox for them to see later. + + + + text + + This template is a scrap of text that can be displayed to + the user. It's intended to be used for mostly cosmetic + reasons, touching up around other questions that are asked + at the same time. Unlike a note, it isn't treated as + something the user should definitely see. Less complex frontends + may refuse to ever display this type of element. + + + + password + + Holds a password. Use with caution. Be aware that the password + the user enters will be written to a database. You + should consider clearing that value out of the database as soon + as is possible. + + + + +
+ diff --git a/debian/changelog b/debian/changelog index 89bd2d2..9416ba7 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,33 @@ +debian-policy (3.5.0.0) unstable; urgency=low + + * There have been numerous changes since the last major change, and + peole have had tiome now to review the recent changes, so I am + updating the policy minor version to reflect the quantity and + magnitude of changes since 3.2.1 + * More spelling corrections, thanks to "Christian T. Steigies" + + * Added mention of DEB_BUILD_OPTIONS in upgrading checklist. + closes: Bug#83924 + * Fixed some typos. closes: Bug#83960 + * Policy now mentions preinst scripts. closes: Bug#80342 + * [AMENDMENT 2000/12/26] allow/document use of Debian Configuration + management system (debconf) closes: Bug#80347 + * Yet more typo fixes closes: Bug#82743 + * document the fact that x font utilities have moved to the package + xutils, closes: Bug#82966 + * Fixed the date in the virtual package list closes: Bug#83438 + * Cleaned up some ephemeral informative foornotes of the polic. Thanks + to Branden Robinson closes: Bug#83065 + * Corrected reference to the mime policy. closes: Bug#79891 + * Corrected reference to the menu policy. closes: Bug#75925 + * Added a note to the effect that the example make snippet used to + illustrate the DEB_BUILD_OPTIONS environment variable is merely + informative, and expanded the example to dismiss any confusion about + potential failure due to accidentally trying to strip scripts. + closes: Bug#80506 + + -- Manoj Srivastava Sun, 28 Jan 2001 21:59:16 -0600 + debian-policy (3.2.1.2) unstable; urgency=low * The minimal change in version number is so that people can test and diff --git a/debian/rules b/debian/rules index 16072c2..ce6cb50 100755 --- a/debian/rules +++ b/debian/rules @@ -44,7 +44,10 @@ FILES_TO_CLEAN = debian/files debian/buildinfo debian/substvars \ menu-policy.text.gz \ policy-process.text.gz policy-process.pdf.gz \ proposal.text.gz menu-policy.pdf.gz proposal.pdf.gz \ - mime-policy.text.gz mime-policy.pdf.gz + mime-policy.text.gz mime-policy.pdf.gz \ + debconf_spec/debconf_specification.html \ + debconf_spec/debconf_specification.txt.gz \ + STAMPS_TO_CLEAN = stamp-policy stamp-build stamp-configure DIRS_TO_CLEAN = debian/tmp policy.html fhs \ menu-policy.html mime-policy.html \ @@ -72,10 +75,14 @@ POLICY_FILES =policy.text.gz policy.sgml virtual-package-names-list.text \ version.ent proposal.sgml proposal.text.gz \ menu-policy.sgml menu-policy.text.gz \ mime-policy.sgml mime-policy.text.gz \ - policy-process.text.gz policy-process.sgml + policy-process.text.gz policy-process.sgml \ + debconf_spec/debconf_specification.html \ + debconf_spec/debconf_specification.txt.gz BYHAND_FILES =policy.text.gz libc6-migration.text \ virtual-package-names-list.text menu-policy.text.gz \ - mime-policy.text.gz + mime-policy.text.gz policy.ps.gz policy.pdf.gz \ + policy.html.tar.gz \ + debconf_spec/debconf_specification.txt.gz install_file = /usr/bin/install -p -o root -g root -m 644 @@ -107,6 +114,8 @@ stamp-build: GROFF_TMAC_PATH=. cd fhs && $(MAKE) fhs.ps fhs.pdf fhs.txt lynx -dump fhs-changes-2.1.html > fhs/fhs-changes-2.1.text lynx -dump upgrading-checklist.html > upgrading-checklist.text + $(MAKE) -c debconf_spec all + gzip -9f debconf_spec/debconf_specification.txt touch stamp-build configure: stamp-configure @@ -171,19 +180,14 @@ stamp-policy: build chmod -R go=rX debian/tmp dpkg --build debian/tmp .. debiandoc2latexps policy.sgml - mv policy.ps ../ - gzip -9qvf ../policy.ps - debiandoc2latexpdf policy.sgml - mv policy.pdf ../ - gzip -9qfv ../policy.pdf - GZIP=-9v tar zcf ../policy.html.tar.gz policy.html + gzip -9qvf policy.ps + debiandoc2latexpdf policy.sgml + gzip -9qfv policy.pdf + GZIP=-9v tar zcf policy.html.tar.gz policy.html $(install_file) version.ent $(DOCDIR)/ - dpkg-distaddfile -fdebian/files policy.ps.gz byhand - - dpkg-distaddfile -fdebian/files policy.pdf.gz byhand - - dpkg-distaddfile -fdebian/files policy.html.tar.gz byhand - - for i in $(BYHAND_FILES); do \ - $(install_file) $$i .. ; \ - dpkg-distaddfile -fdebian/files $$i byhand - ; \ + for i in $(BYHAND_FILES); do \ + $(install_file) $$i .. ; \ + dpkg-distaddfile -fdebian/files `filename $$i` byhand - ; \ done touch stamp-policy diff --git a/policy.sgml b/policy.sgml index 54a1173..5e3b5ca 100644 --- a/policy.sgml +++ b/policy.sgml @@ -902,17 +902,110 @@ the part of a user installing many packages. This means, amongst other things, using the --quiet option on install-info.

- +

- Packages should try to minimize the amount of prompting - they need to do, and they should ensure that the user will - only ever be asked each question once. This means that - packages should try to use appropriate shared - configuration files (such as /etc/papersize and - /etc/news/server), rather than each prompting for - their own list of required pieces of information.

- + Errors which occur during the execution of an installation + script must be checked and the installation must not + continue after an error. +

+

+ Note, that , in general applies to package + maintainer scripts, too. +

+ +

+ You should not use dpkg-divert' on a file + belonging to another package without consulting the + maintainer of that package first. +

+

+ All packages which supply an instance of a common command + name (or, in general, filename) should generally use + update-alternatives, so that they may be + installed together. If update-alternatives + is not used, then each package must use + Conflicts to ensure that other packages are + de-installed. (In this case, it may be appropriate to + specify a conflict against earlier versions of something + that previously did not use + update-alternatives - this is an exception to + the usual rule that this not allowed). +

+ + + + Prompting in maintainer scripts +

+ Package maintainer scripts may prompt the user if + necessary. Prompting may be accomplished by hand, or by + communicating with a program, such as + debconf, which conforms to the Debian + Configuration management specification, version 2 or + higher. (Included in the + debconf_specification files in the + debian-policy package.) + You may also find this file on the FTP site + ftp.debian.org in + /debian/doc/package-developer/debconf_specification.txt.gz + or your local mirror. + +

+ 2.5% of Debian packages + [] + use debconf to prompt the user at install time, and + this number is growing daily. The benefits of using + debconf are briefly explained at + ; + they include preconfiguration, (mostly) + noninteractive installation, elimination of + redundant prompting, consistency of user interface, + etc. +

+

+ With this increasing number of packages using + debconf, plus the existance of a nascent second + implementation of the Debian configuration + management system (cdebconf), and + the stabalization of the protocol these things use, + the time has finally come to reflect the use of + these things in policy. + +

+ +

+

+ Packages which use the Debian Configuration management + specification may contain an additional + config script and a templates + file in their control archive. The config + script can be run before the preinst, and before the + package is unpacked or any of its dependancies or + pre-dependancies are satisfied, so it must work using + only the tools present in the Essential + packages. + +

+ Debconf or another tool that implements the Debian + Configuration management specification will also be + installed, and any versioned dependancies on it will + be satisfied before preconfiguration begins. +

+ +

+ +

+ Packages should try to minimize the amount of prompting + they need to do, and they should ensure that the user + will only ever be asked each question once. This means + that packages should try to use appropriate shared + configuration files (such as /etc/papersize and + /etc/news/server), and shared debconf variables + rather than each prompting for their own list of + required pieces of information. +

+ +

It also means that an upgrade should not ask the same questions again, unless the user has used dpkg --purge to remove the package's configuration. The @@ -922,54 +1015,30 @@ documented.

- If a package has a vitally important piece of information - to pass to the user (such as "don't run me as I am, you - must edit the following configuration files first or you - risk your system emitting badly-formatted messages"), it - should display this in the postinst script - and prompt the user to hit return to acknowledge the - message. Copyright messages do not count as vitally - important (they belong in - /usr/share/doc/package/copyright); neither - do instructions on how to use a program (these should be - in on line documentation, where all the users can see - them).

+ If a package has a vitally important piece of + information to pass to the user (such as "don't run me + as I am, you must edit the following configuration files + first or you risk your system emitting badly-formatted + messages"), it should display this in the + config or postinst script and + prompt the user to hit return to acknowledge the + message. Copyright messages do not count as vitally + important (they belong in + /usr/share/doc/package/copyright); + neither do instructions on how to use a program (these + should be in on line documentation, where all the users + can see them).

Any necessary prompting should almost always be confined - to the post-installation script, and should be protected - with a conditional so that unnecessary prompting doesn't - happen if a package's installation fails and the - postinst is called with + to the config or postinst + script. If it is done in the postinst, it + should be protected with a conditional so that unnecessary + prompting doesn't happen if a package's installation fails + and the postinst is called with abort-upgrade, abort-remove or abort-deconfigure.

-

- Errors which occur during the execution of an installation - script should be checked and the installation should not - continue after an error.

- -

- Note, that , in general applies to - package maintainer scripts, too.

- -

- You should not use dpkg-divert on a file - belonging to another package without consulting the maintainer - of that package first.

- -

- All packages which supply an instance of a common command - name (or, in general, filename) should generally use - update-alternatives, so that they may be - installed together. If update-alternatives - is not used, then each package must use Conflicts - to ensure that other packages are de-installed. (In this - case, it may be appropriate to specify a conflict against - earlier versions of something that previously did not use - update-alternatives -- this is an exception to - the usual rule that this not allowed). -

@@ -2239,7 +2308,7 @@

- Broadly speaking the is called before + Broadly speaking the preinst is called before (a particular version of) a package is installed, and the postinst afterwards; the prerm before (a version of) a package is removed and the @@ -3647,7 +3716,7 @@ The foo binary depends on the libbar shared library, but no package seems to provide a *.shlibs file in - var/lib/dpkg/info/. Let's determine the package + var/lib/dpkg/info/. Let's determine the package responsible:

@@ -4498,7 +4567,7 @@

Menu entries should follow the current menu policy as defined in the file ftp.debian.org in - /debian/doc/package-developer/menu-policy.txt + /debian/doc/package-developer/menu-policy.text.gz or your local mirror. In addition, it is included in the debian-policy package.

@@ -4534,7 +4603,7 @@ compose, edit or print MIME types should register themselves as such following the current MIME support policy as defined in the file found on ftp.debian.org in - /debian/doc/package-developer/mime_policy.txt + /debian/doc/package-developer/mime-policy.text.gz or your local mirror. In addition, it is included in the debian-policy package.

@@ -4807,17 +4876,28 @@

+ CFLAGS = -O2 -Wall INSTALL = install + INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 + INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 + INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 + INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS))) CFLAGS += -g endif ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) - INSTALL += -s + INSTALL_PROGRAM += -s endif -

+ + + Please note that the above example is merely informative, + and is not a policy mandate. You may have to massage this + example in order to make it work for your package. + +

It is up to the package maintainer to decide what @@ -5736,7 +5816,7 @@ - Mail transport agents + Mail transport, delivery and user agents

Debian packages which process electronic mail, whether @@ -5756,7 +5836,7 @@ All Debian MUAs, MTAs, MDAs and other mailbox accessing programs (like IMAP daemons) must lock the mailbox in an NFS-safe way. This means that fcntl() locking must - to be combined with dot locking. To avoid dead locks, a + be combined with dot locking. To avoid deadlocks, a program should use fcntl() first and dot locking after this or alternatively implement the two locking methods in a non blocking way @@ -5878,29 +5958,7 @@ in question is of standard or higher priority, in which case X-specific binaries may be split into a separate package, or alternative versions of the package with X support may be - provided. -

- NOTE The forthcoming major X Window - System release shall probably change this - drastically. -

-

- This seems to be more what people want. It will enable - packages like vim-tty to become legal if they are - promoted to standard priority. Also, that X client in - mtools can be split into its own package and made - optional. -

-

- This paves the way for xlib6g and xfree86-common to be - moved from standard to optional, if all - Xlib dependent packages are moved from standard to - optional priority (or if non-Xlib-linked versions are - retained in standard). That, however is up to the - affected package maintainers and the archive - maintainers, and is not mandated by this policy. -

- + provided.

@@ -5911,15 +5969,12 @@ virtual package xserver.

- Rationale: implement current practice, and provide an - actual policy for usage of the "xserver" virtual package - which appears in the virtual packages list. - In a nutshell, X servers that interface directly with - the display and input hardware or via another subsystem - (e.g., GGI) should provide xserver. Things like Xvfb, - Xnest, and Xprt should not. NOTE The - forthcoming major X Window System release shall probably - change this drastically. + This implements current practice, and provides an actual + policy for usage of the "xserver" virtual package which + appears in the virtual packages list. In a nutshell, X + servers that interface directly with the display and input + hardware or via another subsystem (e.g., GGI) should provide + xserver. Things like Xvfb, Xnest, and Xprt should not.

@@ -5978,7 +6033,7 @@ BDF fonts should be converted to PCF fonts with the bdftopcf utility (available in the - xbase-clients package, gzipped, and + xutils package, gzipped, and placed in a directory that corresponds to their resolution: @@ -6063,7 +6118,7 @@ Font packages must declare a dependency on - xbase-clients and, in the package + xutils and, in the package post-installation and post-removal scripts, invoke the mkfontdir command on each directory into which they installed fonts. @@ -6071,8 +6126,8 @@ Font packages that provide one or more fonts.scale files as described above must declare a - versioned dependency on xbase-clients (>= - 3.3.3.1-5) and invoke update-fonts-scale on each + versioned dependency on xutils (>= + 4.0.2) and invoke update-fonts-scale on each directory into which they installed fonts before invoking mkfontdir on that directory. This invocation must occur in both the @@ -6081,8 +6136,8 @@ Font packages that provide one or more fonts.alias files as described above must - declare a versioned dependency on xbase-clients - (>= 3.3.3.1-5) and, in the package + declare a versioned dependency on xutils + (>= 4.0.2) and, in the package post-installation and post-removal scripts, invoke update-fonts-alias on each directory into which they installed fonts. diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 91a344b..451b373 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -7,9 +7,9 @@ Created On : Thu Oct 29 20:54:48 1998 Created On Node : tiamat.datasync.com Last Modified By : Manoj Srivastava - Last Modified On : Thu Jan 18 01:32:14 2001 + Last Modified On : Fri Jan 19 14:01:36 2001 Last Machine Used: glaurung.green-gryphon.com - Update Count : 14 + Update Count : 15 Status : Unknown, Use with caution! HISTORY : Description : @@ -71,7 +71,8 @@ Manual. Policy Manual: - By default executables should not be built with the debugging option -g. Instead, it is recommended to support building the - package with debugging information optionally. + package with debugging information optionally. Please look at the + examples using DEB_BUILD_OPTIONS in the policy manual. - Policy for packages where the upstream uses html changelog files has been expanded. In short, a plain text changelog file should always be generated for the upstream changes. @@ -82,7 +83,7 @@ Manual. - Policy for packages providing an X terminal emulator has been codified (use virtual package x-terminal-emulator) - Policy for packages providing an X window manager has been - codified (use virtual package x-window-anager, and also as an + codified (use virtual package x-window-manager, and also as an alternative for /usr/bin/x-window-manager. The policy has guidelines on how to calculate priority) - Policy for packages providing an X fonts has been @@ -163,7 +164,7 @@ Manual. - The location of the GPL has changed to /usr/share/common-licenses. This may require changing the copyright files to point to the correct location of the GPL and - other major licences + other major licenses - Packages that use libtool to create shared libraries must include the .la files in the -dev packages. - Use logrotate to rotate log files @@ -190,9 +191,9 @@ Manual. and owners") to Section 4.9. All subsections of the old Section 5 after 5.5 were moved down to fill in the number gap. - - Modified the section about changelog files to accomodate + - Modified the section about changelog files to accommodate upstream changelogs which were formatted as HTML/ These - upstream chagelog files should now be accessible as + upstream changelog files should now be accessible as /usr/doc/package/changelog.html.gz + Symlinks are permissible to link the real, or upstream, changelog name to the Debian mandated name. diff --git a/virtual-package-names-list.txt b/virtual-package-names-list.txt index 34dde65..fdb6d5b 100644 --- a/virtual-package-names-list.txt +++ b/virtual-package-names-list.txt @@ -190,7 +190,7 @@ Manoj Srivastava Added rsh-client Added telnet-client Manoj Srivastava - 16 January 1001 Added rsh server + 16 January 2001 Added rsh server Added telnet-server -- 2.39.5