Bug#582109: debian-policy: document triggers where appropriate
Le Fri, Aug 16, 2013 at 10:10:51AM +0900, Charles Plessy a écrit : Le Sun, Aug 04, 2013 at 09:14:09AM +0900, Charles Plessy a écrit : Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit : If I end up with time to work on it, what I would probably do is to split the patch into smaller changes that can be considered and applied independently, which would hopefully be less intimidating for area experts to review. Hi Jonathan, I have split the patch in the following parts: 0001-Document-Dpkg-states.patch 0002-Document-postinst-triggered.patch 0003-Document-concepts-syntax-and-control-information-fil.patch 0004-Detail-the-two-trigger-kinds-explicit-and-file.patch 0005-Details-about-Dpkg-states-when-processing-triggers.patch 0006-Document-the-behaviour-of-triggers-when-packages-are.patch Hi Jonathan and everybody, how about starting with 0001-Document-Dpkg-states.patch ? It documents the Dpkg states without intrusive normative changes. Hi all, this is the last call for integrating Dpkg triggers in the next update of the Policy. (3.9.5), that I inted to upload before the end of October. Cheers, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Sun, Aug 04, 2013 at 09:14:09AM +0900, Charles Plessy a écrit : Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit : If I end up with time to work on it, what I would probably do is to split the patch into smaller changes that can be considered and applied independently, which would hopefully be less intimidating for area experts to review. Hi Jonathan, I have split the patch in the following parts: 0001-Document-Dpkg-states.patch 0002-Document-postinst-triggered.patch 0003-Document-concepts-syntax-and-control-information-fil.patch 0004-Detail-the-two-trigger-kinds-explicit-and-file.patch 0005-Details-about-Dpkg-states-when-processing-triggers.patch 0006-Document-the-behaviour-of-triggers-when-packages-are.patch Hi Jonathan and everybody, how about starting with 0001-Document-Dpkg-states.patch ? It documents the Dpkg states without intrusive normative changes. From 5d3279e10152d6ecb8b2b4bf226f7e7a380228e1 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sun, 4 Aug 2013 07:17:03 +0900 Subject: [PATCH 1/6] Document Dpkg states. --- policy.sgml | 47 +++ upgrading-checklist.sgml | 4 2 files changed, 51 insertions(+) diff --git a/policy.sgml b/policy.sgml index cb1093f..e3598f1 100644 --- a/policy.sgml +++ b/policy.sgml @@ -3959,6 +3959,53 @@ Checksums-Sha256: /p p + Dpkg defines the following states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and its configuration or the processing + of one of its triggers has not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + /p + + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml index 0a111d4..41a1e84 100644 --- a/upgrading-checklist.sgml +++ b/upgrading-checklist.sgml @@ -55,6 +55,10 @@ Unreleased. itemNew section documenting the ttPackage-Type/tt field in source package control files. /item +tag6.1/tag + itemThe Dpkg states are now documented. The Policy has been proofread + and occurences of Failed-Config have been corrected to Half-Configured. + /item tag11.5.2/tag itemStop recommending to serve HTML documents from file/usr/share/doc/varpackage/var/file. -- 1.8.4.rc0 Have a nice day, -- Charles -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Thu, Jul 25, 2013 at 08:00:55AM +0900, Charles Plessy a écrit : does the current patch (attached) address your concerns ? If yes, would you second it ? Hi all, I would like to make one more call for feedback. Needless to say, I am annoyed that despite we had mutiple persons who commented in that thread, and five Policy editors with a fresh delegation, nothing is moving forward. Julien, Guillem, could you confirm if we can go ahead without further input from you ? To the other Policy editors: given the glacial pace of the work, would it possible for at least one of you to book one hour in your calendar within for instance the next two months, to ensure that one more person can be in position of seconding the patch or requesting further corrections ? Have a nice week-end, -- Charles -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Thu, Jul 25, 2013 at 08:00:55 +0900, Charles Plessy wrote: does the current patch (attached) address your concerns ? If yes, would you second it ? Sorry, I don't feel confident to second anything trigger-related. Cheers, Julien signature.asc Description: Digital signature
Bug#582109: debian-policy: document triggers where appropriate
Charles Plessy wrote: Le Thu, Jul 25, 2013 at 08:00:55AM +0900, Charles Plessy a écrit : does the current patch (attached) address your concerns ? If yes, would you second it ? Hi all, I would like to make one more call for feedback. Sorry for the long silence. My feeling is that the patch is not ready yet. I know that without some more specific list of concerns that is not a very useful thing to say, but that's what I have. In other words, I don't think it's ready for seconds. If I end up with time to work on it, what I would probably do is to split the patch into smaller changes that can be considered and applied independently, which would hopefully be less intimidating for area experts to review. For example, a patch adding documentation of the non-trigger Dpkg states and how the package installation procedure interacts with them should be uncontroversial and easy to review. With triggers, one of the hardest parts to document is how packagers are supposed to deal with the dependencies may not be configured bug. Mentioning the bug as you have is good, but giving some practical advice about how to work around it (Do not rely on a sane state being present is not practical advice because it doesn't say what to do when your dependencies are missing) would be better. Maybe policy should only define the -noawait variant for now? Thanks, and sorry I do not have something more useful to offer, Jonathan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Sat, Aug 03, 2013 at 09:41:59AM -0700, Jonathan Nieder a écrit : If I end up with time to work on it, what I would probably do is to split the patch into smaller changes that can be considered and applied independently, which would hopefully be less intimidating for area experts to review. Hi Jonathan, I have split the patch in the following parts: 0001-Document-Dpkg-states.patch 0002-Document-postinst-triggered.patch 0003-Document-concepts-syntax-and-control-information-fil.patch 0004-Detail-the-two-trigger-kinds-explicit-and-file.patch 0005-Details-about-Dpkg-states-when-processing-triggers.patch 0006-Document-the-behaviour-of-triggers-when-packages-are.patch I could not cut in smaller pieces, as it would separate informations that would lose a lot of context if they are not added together. With triggers, one of the hardest parts to document is how packagers are supposed to deal with the dependencies may not be configured bug. Mentioning the bug as you have is good, but giving some practical advice about how to work around it (Do not rely on a sane state being present is not practical advice because it doesn't say what to do when your dependencies are missing) would be better. Maybe policy should only define the -noawait variant for now? In the current patch, the -noawait variant is recommended. I think that the Policy should not hide information about a feature in the hope that less people use it. I think that it is important that the Policy stays a neutral reference. About the Dpkg bug, I think that we should consider the whole section about the postinst script. In the paragraph above the description of postinst triggered it already mentions consider the correct error handling approach if those actions fail. I think that this is also the current practice for postinst configure, where often I sed that commands are tested for their availability before being run. Lastly, the current patch also mentions Pre-Depends, which is a robust last-ressort solution. In the existing documentation of the dpkg triggers, the bug of dpkg is not mentionned, so I think that this patch to the Policy represents a progress compared with the current situation. I still do not understand why there is so much reluctance in enhancing our documentation. Have a nice Sunday, -- Charles Plessy Tsurumi, Kanagawa, Japan From 5d3279e10152d6ecb8b2b4bf226f7e7a380228e1 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sun, 4 Aug 2013 07:17:03 +0900 Subject: [PATCH 1/6] Document Dpkg states. --- policy.sgml | 47 +++ upgrading-checklist.sgml | 4 2 files changed, 51 insertions(+) diff --git a/policy.sgml b/policy.sgml index cb1093f..e3598f1 100644 --- a/policy.sgml +++ b/policy.sgml @@ -3959,6 +3959,53 @@ Checksums-Sha256: /p p + Dpkg defines the following states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and its configuration or the processing + of one of its triggers has not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + /p + + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml index 0a111d4..41a1e84 100644 --- a/upgrading-checklist.sgml +++ b/upgrading-checklist.sgml @@ -55,6 +55,10 @@ Unreleased. itemNew section documenting the ttPackage-Type/tt field in source package control files. /item +tag6.1/tag + itemThe Dpkg states are now documented. The Policy has been proofread + and occurences of Failed-Config have been corrected to Half-Configured. + /item tag11.5.2/tag itemStop recommending to serve HTML documents from file/usr/share/doc/varpackage/var/file. -- 1.8.4.rc0 From e7c1f429ab818b73b20c99605769ca97c5fff2f5 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sun, 4 Aug 2013 07:41:39 +0900 Subject: [PATCH 2/6] Document postinst triggered. --- policy.sgml | 40
Bug#582109: debian-policy: document triggers where appropriate
On Wed, Jul 17, 2013 at 09:27:19 +0200, Raphael Hertzog wrote: Hi, On Wed, 17 Jul 2013, Charles Plessy wrote: About the problem of triggers being called with Depends not satisfied, can you give more explanations or suggest some text for the warning ? Would it be enough to add a notice that the triggered postinst script may be called when the package is Unpacked, which is a state that does not require that the packages that are depended on are configured ? Julien is referring to this bug: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711 It might be fixed for jessie, at least I hope so, but he seems to doubt it. It doesn't really matter whether it's fixed for jessie. Since it's not fixed in wheezy, it's relevant for packages in jessie when they're upgraded. Cheers, Julien signature.asc Description: Digital signature
Bug#582109: debian-policy: document triggers where appropriate
Le Wed, Jul 24, 2013 at 03:58:04PM +0200, Julien Cristau a écrit : On Wed, Jul 17, 2013 at 09:27:19 +0200, Raphael Hertzog wrote: On Wed, 17 Jul 2013, Charles Plessy wrote: About the problem of triggers being called with Depends not satisfied, can you give more explanations or suggest some text for the warning ? Would it be enough to add a notice that the triggered postinst script may be called when the package is Unpacked, which is a state that does not require that the packages that are depended on are configured ? Julien is referring to this bug: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711 It might be fixed for jessie, at least I hope so, but he seems to doubt it. It doesn't really matter whether it's fixed for jessie. Since it's not fixed in wheezy, it's relevant for packages in jessie when they're upgraded. Hi Julien, does the current patch (attached) address your concerns ? If yes, would you second it ? The paragraph on postinst triggers is now as follows. postinst configure was already run and the dependencies ought to be configured. However, dpkg currently suffers of a bug which means that postinst triggered can be called while some dependencies are being upgraded (see bug 671711). Until this bug is absent from the stable release, you should thus only rely on the fact that the dependencies are at least unpacked and were already configured once (similar to what Pre-Depends ensures for preinst maintainer scripts). postinst triggered processes one or more triggers that this package is interested in. In case of failure the package's state becomes Half-Configured and the task associated to the trigger processing will be completed by the postinst configure during the next package's configuration[48]. Have a nice day, -- Charles diff --git a/debian/changelog b/debian/changelog index fe4a858..20e3f84 100644 --- a/debian/changelog +++ b/debian/changelog @@ -33,6 +33,11 @@ debian-policy (3.9.5.0) UNRELEASED; urgency=low Seconded: Charles Plessy ple...@debian.org Seconded: Jonathan Nieder jrnie...@gmail.com Closes: #715804 + * Policy: Document dpkg states and triggers. +Wording: Charles Plessy ple...@debian.org +Seconded: Raphaël Hertzog hert...@debian.org +Seconded: +Closes: #582109 * debconf_spec: Document the 'escape' capability. Wording: Jonathan Nieder jrnie...@gmail.com Seconded: Charles Plessy ple...@debian.org diff --git a/policy.sgml b/policy.sgml index 953d5d2..b846118 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,11 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + filetriggers/file file, which defines the package's interaction with + prgndpkg/prgn's qref id=dpkg-triggerstrigger/qref system. /p p @@ -3959,6 +3961,51 @@ Checksums-Sha256: /p p + Dpkg defines the following states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and its configuration or the processing + of one of its triggers has not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4106,7 +4153,11 @@ Checksums-Sha256: are no circular dependencies involved, all package dependencies will be configured. For behavior in the case of circular dependencies, see the discussion - in ref id=binarydeps. + in ref id=binarydeps. Even when called with + ttconfigure/tt, this script must do whatever actions are +
Bug#582109: debian-policy: document triggers where appropriate
On Mon, 22 Jul 2013, Charles Plessy wrote: Nevertheless, please let me try to refocus on the question of whether the Policy can be updated or not. I believe we can update the policy whatever the status of this specific bug. Here is what is written in the Policy about postinst configure: The files contained in the package will be unpacked. All package dependencies will at least be unpacked. You're missing the important sentence that follows: “If there are no circular dependencies involved, all package dependencies will be configured.” I propose to go ahead with the following: tagvarpostinst/var tttriggered/tt vartrigger-name/var vartrigger-name/var .../tag item My suggestion: prgnpostinst configure/prgn was already run and the dependencies ought to be configured. However, dpkg currently suffers of a bug which means that prgnpostinst triggered/prgn can be called while some dependencies are being upgraded (see bug url id=http://bugs.debian.org/671711; name=671711). You should thus only rely on the fact that the dependencies are at least unpacked and were already configured once (similar to what ttPre-Depends/tt ensures for prgnpreinst/prgn maintainer scripts). I would like to go ahead and close this bug. If Raphaël confirms that he still seconds the patch, I would much appreciate if I could either have support or actionable objection from others (preferably in the form of unless X is done, the patch should not be applied, rather than it would be good to do Y). I maintain my second provided that you fix the above. Cheers, -- Raphaël Hertzog ◈ Debian Developer Discover the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Mon, Jul 22, 2013 at 09:00:59AM +0200, Raphael Hertzog a écrit : I believe we can update the policy whatever the status of this specific bug. You're missing the important sentence that follows: “If there are no circular dependencies involved, all package dependencies will be configured.” Ahem... That is embarassing. Thanks for your patience. Now I understand why I did not understand. My suggestion: prgnpostinst configure/prgn was already run and the dependencies ought to be configured. However, dpkg currently suffers of a bug which means that prgnpostinst triggered/prgn can be called while some dependencies are being upgraded (see bug url id=http://bugs.debian.org/671711; name=671711). You should thus only rely on the fact that the dependencies are at least unpacked and were already configured once (similar to what ttPre-Depends/tt ensures for prgnpreinst/prgn maintainer scripts). I maintain my second provided that you fix the above. Great, and thanks for your suggestion, which I will apply. More seconds or objections from others ? What are the other Policy editors thinking about this patch ? Cheers, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Sat, 20 Jul 2013, Charles Plessy wrote: Can you explain what the bug is and what the correction will be ? Because I The bug is that triggers are run while the dependencies of the triggered package are not satisfied. The fix is not to do that and wait until those dependencies are satisfied (but guillem mentionned that it also needs some cycle breaking code). The misleading point is just like packages in installed. In my understanding, when a package is upgraded, the packages that depend on it stay in the Installed state while the new version of the upgraded package is unpacked and configured. Not just the triggers, but also any other command not related to the dpkg or apt session that would happen to run at that time can fail if they strictly require a function that is not available between unpack and configure. That's true but it's not really comparable. postinst triggered ought to work like postinst configure and there you have the guaranty that the dependencies are configured. I do not see any other solution than applying the same restrictions on postinst triggered as for postinst configure. (PS: after reading the thread again, I just noticed that this also what you wrote in #671711#68). I did not write that. On the contrary, re-read: “The problematic fix is to ensure the same requirements for postinst triggered as for postinst configure. But we could enforce some requirements that would probably solve the issues we saw without introducing cycles.” There are no restrictions for postinst configure (you can rely on dependencies — except if you have a dependency cycle) and there should be no restrictions for postinst triggered. But right now, dpkg doesn't ensure anything. And instead of nothing checked by dpkg, I suggested to ensure some requirements nevertheless but which are less demanding than those used by postinst configure. (PPS: By the way, apart from Manoj's excellent diagrams at http://people.debian.org/~srivasta/MaintainerScripts.html#sec-3.4.3, is there an extensive documentation on how package upgrades are handled by APT and Dpkg ?) I know https://wiki.debian.org/MaintainerScripts too but that's all. Cheers, -- Raphaël Hertzog ◈ Debian Developer Discover the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Sun, Jul 21, 2013 at 09:36:52PM +0200, Raphael Hertzog a écrit : There are no restrictions for postinst configure (you can rely on dependencies — except if you have a dependency cycle) and there should be no restrictions for postinst triggered. But right now, dpkg doesn't ensure anything. And instead of nothing checked by dpkg, I suggested to ensure some requirements nevertheless but which are less demanding than those used by postinst configure. Sorry for the poorly chosen use of the word restrictions here... Nevertheless, please let me try to refocus on the question of whether the Policy can be updated or not. Here is what is written in the Policy about postinst configure: The files contained in the package will be unpacked. All package dependencies will at least be unpacked. The corollary is that there is no guarantee that the dependencies will be configured, and my understanding of #671711 is that it currently applies to postinst triggered as well. I propose to go ahead with the following: tagvarpostinst/var tttriggered/tt vartrigger-name/var vartrigger-name/var .../tag item The files contained in the package will be unpacked. All package dependencies will at least be Unpackedfootnote There is work under way on prgndpkg/prgn to ensure that the requirement on ttpostinst triggered/tt is less demanding than for ttpostinst configure/tt, see the bug number url id=http://bugs.debian.org/671711; name=671711 for details./footnote. I attached a full version of the latest patch. I would like to go ahead and close this bug. If Raphaël confirms that he still seconds the patch, I would much appreciate if I could either have support or actionable objection from others (preferably in the form of unless X is done, the patch should not be applied, rather than it would be good to do Y). Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan diff --git a/policy.sgml b/policy.sgml index 1508231..5308a84 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,11 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + filetriggers/file file, which defines the package's interaction with + prgndpkg/prgn's qref id=dpkg-triggerstrigger/qref system. /p p @@ -3959,6 +3961,51 @@ Checksums-Sha256: /p p + Dpkg defines the following states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and its configuration or the processing + of one of its triggers has not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4106,7 +4153,11 @@ Checksums-Sha256: are no circular dependencies involved, all package dependencies will be configured. For behavior in the case of circular dependencies, see the discussion - in ref id=binarydeps. + in ref id=binarydeps. Even when called with + ttconfigure/tt, this script must do whatever actions are + necessary to deal with any + qref id=dpkg-triggers-intermediate-statestriggers/qref + activation. /item tagvarold-postinst/var ttabort-upgrade/tt @@ -4141,6 +4192,34 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + The files contained in the package will be unpacked. All + package dependencies will at least be
Bug#582109: debian-policy: document triggers where appropriate
Thanks again Raphaël for your prompt feedback. Le Thu, Jul 18, 2013 at 09:00:44AM +0200, Raphael Hertzog a écrit : On Thu, 18 Jul 2013, Charles Plessy wrote: - postinst configure should do at least everything needed by postinst triggers, since in the situations where triggers are dropped, the package is in a state that ensures that postinst configure will be run. Yes, that's pretty important. I haven't checked if this was already documented in your patch, but it definitely is a clear rule in the /usr/share/doc/dpkg-dev/triggers.txt.gz. The current patch adds the following to the paragraph describing postinst configure in section 6.5. Even when called with ttconfigure/tt, this script must do whatever actions are necessary to deal with any qref id=dpkg-triggers-intermediate-statestriggers/qref activation. This is repeated at the end of the new section on triggers. For this reason, the ttpostinst/tt scripts must do whatever actions are necessary to deal with any trigger activation when they are called with ttconfigure/tt. - we could write in section 6.5 of the Policy that for postinst triggers the requirements are the same as for postinst abort-*: The files contained in the package will be unpacked. All package dependencies will at least be Half-Installed and will have previously been configured and not removed. However, dependencies may not be configured or even fully unpacked in some error situations. Why not, but then please add a footnote explaining that this ought to be temporary until the dpkg bug gets fixed. Because it's not really a satisfactory situation. Can you explain what the bug is and what the correction will be ? Because I have the impression that the root of the problem is only that the current documentation is misleading, and that dpkg does exactly what it is expected. From the documentation: Packages in t-awaited and t-pending demand satisfaction of their dependencies just like packages in installed. The misleading point is just like packages in installed. In my understanding, when a package is upgraded, the packages that depend on it stay in the Installed state while the new version of the upgraded package is unpacked and configured. Not just the triggers, but also any other command not related to the dpkg or apt session that would happen to run at that time can fail if they strictly require a function that is not available between unpack and configure. I do not see any other solution than applying the same restrictions on postinst triggered as for postinst configure. (PS: after reading the thread again, I just noticed that this also what you wrote in #671711#68). (PPS: By the way, apart from Manoj's excellent diagrams at http://people.debian.org/~srivasta/MaintainerScripts.html#sec-3.4.3, is there an extensive documentation on how package upgrades are handled by APT and Dpkg ?) In the case of #671711, I wonder if monodoc-browser is simply abusing the triggers mechanism, since the only thing that its postint script does when called with configure is to trigger itself. Altogether, I propose to document that the requirements are the same for postinst triggered as for postinst configure, and go ahead with updating the Policy. In my understanding, the proposed improvements to Dpkg can reduce, but not completely eliminate, the cases where fragile postinst scripts break when triggered. Have a nice week-end, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Thu, 18 Jul 2013, Charles Plessy wrote: Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit : regarding “noawait” triggers, the patch already contains the following, which is new and improved compared to the existing documentation. The tt*-noawait/tt directives should be used unless the packages awaiting triggers can not satisfy ttDepends/tt relationships until the triggers have been processed. By the way, are the “noawait” triggers guaranteed to be executed only after the triggering package has entered the Installed state, or can they be executed at the same time of other triggers as well ? There's no such guaranty. A package that triggers another package only knows that the triggers will be processed at some point in the future. It doesn't know if if will before or after its own configuration (the noawait doesn't change anything here except that the trigger requirement is not recorded). Even with traditional triggers, it's possible that dpkg will configure a package before processing the triggers that it awaits. What this means is just that the end status will be Triggers-Awaited instead Installed. Cheers, -- Raphaël Hertzog ◈ Debian Developer Discover the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hi, On Thu, 18 Jul 2013, Charles Plessy wrote: After reading #671711 and /usr/share/doc/dpkg-dev/triggers.txt.gz, my impression is that a package can not become Unpacked and keep a list of pending triggers, because of the following statements in triggers.txt: 1) Pending triggers are marked never for Unpacked packages in the overview table. 2) The section Details - triggered package mentions that packages in ‘config-failed’ or worse are never considered to have lists of pending triggers. (Where config-failed means Half-Installed). In my understanding of Dpkg states, Unpacked is worse than Half-Installed. There are two consequences to this: - postinst configure should do at least everything needed by postinst triggers, since in the situations where triggers are dropped, the package is in a state that ensures that postinst configure will be run. Yes, that's pretty important. I haven't checked if this was already documented in your patch, but it definitely is a clear rule in the /usr/share/doc/dpkg-dev/triggers.txt.gz. - we could write in section 6.5 of the Policy that for postinst triggers the requirements are the same as for postinst abort-*: The files contained in the package will be unpacked. All package dependencies will at least be Half-Installed and will have previously been configured and not removed. However, dependencies may not be configured or even fully unpacked in some error situations. Why not, but then please add a footnote explaining that this ought to be temporary until the dpkg bug gets fixed. Because it's not really a satisfactory situation. I understand that changes in dpkg can enchance the mechanism to use triggers, thus reducing the risk of having bugs, but I think that in #671711, dpkg is following the specification, unless it failed to clear the list of pending triggers when monodoc-browser became unpacked when it was upgraded. The documentation says Packages in t-awaited and t-pending demand satisfaction of their dependencies just like packages in installed.. This is the part that is not respected in the above bug. So no, it's not really following the specification. Is that correct ? If yes, then I propose to go ahead and apply an improved patch to the policy that mentions the restrictions and requirements on postinst triggers, because it represents an enhancement to the existing documentation. Definitely. jessie development is live, we want to draw the attention of people to review their triggers and do the right thing. Cheers, -- Raphaël Hertzog ◈ Debian Developer Discover the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hi, On Wed, 17 Jul 2013, Charles Plessy wrote: About the problem of triggers being called with Depends not satisfied, can you give more explanations or suggest some text for the warning ? Would it be enough to add a notice that the triggered postinst script may be called when the package is Unpacked, which is a state that does not require that the packages that are depended on are configured ? Julien is referring to this bug: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711 It might be fixed for jessie, at least I hope so, but he seems to doubt it. Also, if you think that triggers will give us problems for the Jessie release, may I suggest that you give it a broad audience on debian-devel ? As a maintainer of a package that has triggers, I am definitely interested to learn if there is something I should give particular attention there. One of the main things to do is to switch as many packages as possible to use the interest-noawait directive when possible. Cheers, -- Raphaël Hertzog ◈ Debian Developer Discover the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Wed, Jul 17, 2013 at 09:27:19AM +0200, Raphael Hertzog a écrit : Julien is referring to this bug: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=671711 It might be fixed for jessie, at least I hope so, but he seems to doubt it. Also, if you think that triggers will give us problems for the Jessie release, may I suggest that you give it a broad audience on debian-devel ? As a maintainer of a package that has triggers, I am definitely interested to learn if there is something I should give particular attention there. One of the main things to do is to switch as many packages as possible to use the interest-noawait directive when possible. Hi all, regarding “noawait” triggers, the patch already contains the following, which is new and improved compared to the existing documentation. The tt*-noawait/tt directives should be used unless the packages awaiting triggers can not satisfy ttDepends/tt relationships until the triggers have been processed. After reading #671711 and /usr/share/doc/dpkg-dev/triggers.txt.gz, my impression is that a package can not become Unpacked and keep a list of pending triggers, because of the following statements in triggers.txt: 1) Pending triggers are marked never for Unpacked packages in the overview table. 2) The section Details - triggered package mentions that packages in ‘config-failed’ or worse are never considered to have lists of pending triggers. (Where config-failed means Half-Installed). In my understanding of Dpkg states, Unpacked is worse than Half-Installed. There are two consequences to this: - postinst configure should do at least everything needed by postinst triggers, since in the situations where triggers are dropped, the package is in a state that ensures that postinst configure will be run. - we could write in section 6.5 of the Policy that for postinst triggers the requirements are the same as for postinst abort-*: The files contained in the package will be unpacked. All package dependencies will at least be Half-Installed and will have previously been configured and not removed. However, dependencies may not be configured or even fully unpacked in some error situations. I understand that changes in dpkg can enchance the mechanism to use triggers, thus reducing the risk of having bugs, but I think that in #671711, dpkg is following the specification, unless it failed to clear the list of pending triggers when monodoc-browser became unpacked when it was upgraded. Is that correct ? If yes, then I propose to go ahead and apply an improved patch to the policy that mentions the restrictions and requirements on postinst triggers, because it represents an enhancement to the existing documentation. Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit : regarding “noawait” triggers, the patch already contains the following, which is new and improved compared to the existing documentation. The tt*-noawait/tt directives should be used unless the packages awaiting triggers can not satisfy ttDepends/tt relationships until the triggers have been processed. By the way, are the “noawait” triggers guaranteed to be executed only after the triggering package has entered the Installed state, or can they be executed at the same time of other triggers as well ? Cheers, -- Charles -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Thu, Jul 18, 2013 at 08:55:20AM +0900, Charles Plessy a écrit : 2) The section Details - triggered package mentions that packages in ‘config-failed’ or worse are never considered to have lists of pending triggers. (Where config-failed means Half-Installed). In my understanding of Dpkg states, Unpacked is worse than Half-Installed. Sorry for the noise: I meant Half-Configured, not Half-Installed. Cheers, -- Charles -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Thu, Jul 4, 2013 at 11:26:01 +0900, Charles Plessy wrote: Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit : On Sun, 12 May 2013, Charles Plessy wrote: I also added through the ttinterst/tt or ttactivate/tt directives after When a configured package activates a trigger. I applied the other changes you proposed as well, with minor rewording: - prgndpkg/prgn keeps a list, ttTriggers-Awaited/tt of - interested packages whose trigger processing is awaited. Every + prgndpkg/prgn keeps a list of interested packages whose trigger + processing is awaited, which is stored in the + ttTriggers-Awaited/tt field in dpkg's status database. Every I attached an updated version of the patch. Thanks, I agree that your improved wording is better. Seconded. Dear all, now that Wheezy is released, I hope that everybody has more time to review the patch to integrate triggers in the Policy and confirm Raphaël's seconding or propose extra corrections or improvements. http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109 That patch has a bunch of typos (I noticed a few in spelling package). Also it doesn't seem to warn against triggers being called with Depends not satisfied, which caused no end of trouble for upgrades to wheezy, and which is probably going to bite us again for jessie. Cheers, Julien signature.asc Description: Digital signature
Bug#582109: debian-policy: document triggers where appropriate
Le Tue, Jul 16, 2013 at 05:09:08PM +0200, Julien Cristau a écrit : On Thu, Jul 4, 2013 at 11:26:01 +0900, Charles Plessy wrote: http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109 That patch has a bunch of typos (I noticed a few in spelling package). Also it doesn't seem to warn against triggers being called with Depends not satisfied, which caused no end of trouble for upgrades to wheezy, and which is probably going to bite us again for jessie. Hi Julien, thank you for your comments and sorry for forgetting to run a spellchecker. I will make the following spelling corrections. s/wich/which/ s/activations/activation/ s/packges/packages/ s/unnecessarly/unnecessarily/ s/mechanims/mechanism/ About the problem of triggers being called with Depends not satisfied, can you give more explanations or suggest some text for the warning ? Would it be enough to add a notice that the triggered postinst script may be called when the package is Unpacked, which is a state that does not require that the packages that are depended on are configured ? Also, if you think that triggers will give us problems for the Jessie release, may I suggest that you give it a broad audience on debian-devel ? As a maintainer of a package that has triggers, I am definitely interested to learn if there is something I should give particular attention there. Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
tag 582109 patch thanks Le Thu, Jul 04, 2013 at 11:26:01AM +0900, Charles Plessy a écrit : now that Wheezy is released, I hope that everybody has more time to review the patch to integrate triggers in the Policy and confirm Raphaël's seconding or propose extra corrections or improvements. http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109 Dear all, I would like to give a firmer call for seconds, so that we can close this issue and move to the next big change: either multi-arch, or the conversion to DocBook XML. Have a nice day, Charles -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit : On Sun, 12 May 2013, Charles Plessy wrote: I also added through the ttinterst/tt or ttactivate/tt directives after When a configured package activates a trigger. I applied the other changes you proposed as well, with minor rewording: - prgndpkg/prgn keeps a list, ttTriggers-Awaited/tt of - interested packages whose trigger processing is awaited. Every + prgndpkg/prgn keeps a list of interested packages whose trigger + processing is awaited, which is stored in the + ttTriggers-Awaited/tt field in dpkg's status database. Every I attached an updated version of the patch. Thanks, I agree that your improved wording is better. Seconded. Dear all, now that Wheezy is released, I hope that everybody has more time to review the patch to integrate triggers in the Policy and confirm Raphaël's seconding or propose extra corrections or improvements. http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=87;filename=policy-triggers.diff;att=1;bug=582109 Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hi, On Thu, 16 May 2013, Charles Plessy wrote: Guillem recently posted on debian-devel about noawait triggers, and I would like to send a link to the patch to the Policy once it gets futher proof-reading and seconds. Or if it takes time, shall I point to this bug log on -devel ? I don't see any harm to mentioning it right now. And maybe point Ian Jackson to it, he might want to review and second it... Cheers, -- Raphaël Hertzog ◈ Debian Developer Get the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Sun, May 12, 2013 at 10:09:17AM +0200, Raphael Hertzog a écrit : Thanks, I agree that your improved wording is better. Seconded. Thanks again. Guillem recently posted on debian-devel about noawait triggers, and I would like to send a link to the patch to the Policy once it gets futher proof-reading and seconds. Or if it takes time, shall I point to this bug log on -devel ? Cheers, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hi, On Sun, 12 May 2013, Charles Plessy wrote: p The tt*-noawait/tt directives should be used unless the packages awaiting triggers can not satisfy ttDepends/tt relationships until the triggers have been processed. In that case, the ttinterest/tt or ttactivate/tt directives should be used, as they will put the triggering packges in the Triggers-Awaited state, which does not satisfy dependencies. Note that pakcages unnecessarly entering this state can cause the s/pakcages/packages/ early processing of triggers or even dependency loops. /p I also added through the ttinterst/tt or ttactivate/tt directives after When a configured package activates a trigger. I applied the other changes you proposed as well, with minor rewording: - prgndpkg/prgn keeps a list, ttTriggers-Awaited/tt of - interested packages whose trigger processing is awaited. Every + prgndpkg/prgn keeps a list of interested packages whose trigger + processing is awaited, which is stored in the + ttTriggers-Awaited/tt field in dpkg's status database. Every I attached an updated version of the patch. Thanks, I agree that your improved wording is better. Seconded. Cheers, -- Raphaël Hertzog ◈ Debian Developer Get the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Wed, Apr 10, 2013 at 12:07:19PM +0200, Raphael Hertzog a écrit : Here are my comments. There's quite a bit of work left. Thanks a lot Raphaël and everybody ! I think that I took care of all of your comments. Here is an updated patch. Among the changes, it introduces sub-section to make the information easier to digest. Cheers, -- Charles diff --git a/policy.sgml b/policy.sgml index 1508231..f7948de 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,11 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + filetriggers/file file, wich defines the package's interaction with + prgndpkg/prgn's qref id=dpkg-triggerstrigger/qref system. /p p @@ -3959,6 +3961,51 @@ Checksums-Sha256: /p p + Dpkg defines the following states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and its configuration or the processing + of one of its triggers has not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4106,7 +4153,11 @@ Checksums-Sha256: are no circular dependencies involved, all package dependencies will be configured. For behavior in the case of circular dependencies, see the discussion - in ref id=binarydeps. + in ref id=binarydeps. Even when called with + ttconfigure/tt, this script must do whatever actions are + necessary to deal with any + qref id=dpkg-triggers-intermediate-statestriggers/qref + activations. /item tagvarold-postinst/var ttabort-upgrade/tt @@ -4141,6 +4192,27 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + Process one or more qref id=dpkg-triggerstriggers/qref that + this package is eminterested/em in. In case of failure the + package's state becomes Half-Configured and the task associated + to the trigger processing will be completed by the + ttpostinst configure/tt during the next package's + configurationfootnote + When an interested package has more than one trigger and wants + to process them differently, the list of triggers can be + examined in a shell script like this: + example +case $2 in +* trigger-name-a *) process-trigger-a ;; +esac/example + Generally each trigger name should be tested for separately, as + the postinst will often be called for several triggers at once. + /footnote. + /item /taglist /p @@ -4694,6 +4766,199 @@ fi /p /sect + + sect id=dpkg-triggers + headingDpkg triggers/heading + + sect1 id=dpkg-triggers-concepts + headingConcepts/heading + + p + Dpkg triggers allow packages to monitor events caused by + the installation, upgrade or removal of other packages. Monitoring + packages are said to be eminterested/em in some triggers. On the + other side, triggers must be emactivated/em to notify the + interested package, which is then said to have empending/em + triggers. The activating package (if any) is said to emawait/em + the processing of the trigger. + p + + p + The purpose of this feature is to to avoid duplication of processing + logic among packages by implementing it in one package and making + sure that all other packages rely on triggers to execute the wanted + code. + /p + + p + Each trigger is named, and at any time zero or more packages may be + eminterested/em in it. For a package to
Bug#582109: debian-policy: document triggers where appropriate
Hi Charles, On Sat, 11 May 2013, Charles Plessy wrote: I think that I took care of all of your comments. Here is an updated patch. Among the changes, it introduces sub-section to make the information easier to digest. Thank you for the work! I have a few fixes and suggestions but otherwise it looks mostly ready. So seconded with the few suggestions below. + p + The filetriggers/file control file contains one directive per + line. Leading and trailing whitespace, everything after the first + hash character (tt#/tt) on any line, and empty lines are ignored. + The following directives are supported. + taglist + tagttinterest/tt vartrigger-name/var/tag + tagttinterest-noawait/tt vartrigger-name/var/tag + item + Specifies that the package is interested in the named trigger. + The ttinterest-noawait/tt variant does not put the + triggering packages in the Triggers-Awaited state. + /item + + tagttactivate/tt vartrigger-name/var/tag + tagttactivate-noawait/tt vartrigger-name/var/tag + item + Specifies that changes to this package's state will activate the + named trigger. The ttactivate-noawait/tt variant does not + put this package in the Triggers-Awaited state. + /item + /taglist + /p Here I would add a small paragraph recommending the usage of the -noawait variants unless they are strictly required. pThe tt*-noawait/tt directives should be used by default to avoid putting packages in the Trigger-Awaited status. Packages should only end up in this intermediary status when they are effectively broken until the awaited triggers have been processed. A package in Trigger-Awaited does not satisfy dependencies, for this reason an excessive and injustified amount of package in this status can lead to early processing of triggers or even to dependency loops./p + p + When a configured package activates a trigger, its state becomes + Triggers-Awaited instead of Installed. For this package, + prgndpkg/prgn keeps a list, ttTriggers-Awaited/tt of missing comma after Triggers-Awaited/tt, but I would rather rewrite it like this: keeps a list of interested packages whose trigger processing is awaited (that list is stored in the ttTriggers-Awaited/tt field in dpkg's status database) + interested packages whose trigger processing is awaited. Every + package in this list either has a nonempty list of pending + triggers, or is in Half-Configured or worse. When a package in + the state Triggers-Pending becomes Installed, Config-Files or + Not-Installed, its entry is removed from the + ttTriggers-Awaited/tt lists of other packages. + /p + + p + When a trigger is activated, the state of every interested package + becomes Triggers-Pending. For each package, prgndpkg/prgn + keeps a list, ttTriggers-Pending/tt, of triggers whose + processing is pending. Repeated activation of the same trigger has Same suggested rewrite as above here. + no additional effect. In general a trigger will not be processed + immediately when it is activated; processing is deferred until it is + convenient. + /p + [...] + Packages in Half-Configured or worse never have pending triggers. + A package is only guaranteed to become notified of a trigger +activation if it is continuously interested in the trigger, and never +in Half-Configured or worse. A package whose postinst is being run weird spacing here + can however acquire pending triggers during that run (ie, a package + can trigger itself). + /p + + p + However, if such a package (between Half-Installed and + Half-Configured inclusive) declares some trigger interests then the + triggering packages will await their configuration (which implies + completion of any necessary trigger processing) or removal. + /p + + p + For this reason, the ttpostinst/tt scripts it must do whatever s/it// + actions are necessary to deal with any trigger activations when they + are called with ttconfigure/tt. + /p + /sect1 + /sect /chapt Cheers, -- Raphaël Hertzog ◈ Debian Developer Get the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hi Raphaël, thanks for the quick feedback. In the list of directives, I have moved the noawait variant on top to better show that they are the default choice. I also reworded your suggestion to make it a positive recommenation: use interest and activate only if you want to put the triggering package in Trigger-Awaited state. Le Sat, May 11, 2013 at 03:09:25PM +0200, Raphael Hertzog a écrit : + p + The filetriggers/file control file contains one directive per + line. Leading and trailing whitespace, everything after the first + hash character (tt#/tt) on any line, and empty lines are ignored. + The following directives are supported. + taglist + tagttinterest/tt vartrigger-name/var/tag + tagttinterest-noawait/tt vartrigger-name/var/tag + item + Specifies that the package is interested in the named trigger. + The ttinterest-noawait/tt variant does not put the + triggering packages in the Triggers-Awaited state. + /item + + tagttactivate/tt vartrigger-name/var/tag + tagttactivate-noawait/tt vartrigger-name/var/tag + item + Specifies that changes to this package's state will activate the + named trigger. The ttactivate-noawait/tt variant does not + put this package in the Triggers-Awaited state. + /item + /taglist + /p Here I would add a small paragraph recommending the usage of the -noawait variants unless they are strictly required. pThe tt*-noawait/tt directives should be used by default to avoid putting packages in the Trigger-Awaited status. Packages should only end up in this intermediary status when they are effectively broken until the awaited triggers have been processed. A package in Trigger-Awaited does not satisfy dependencies, for this reason an excessive and injustified amount of package in this status can lead to early processing of triggers or even to dependency loops./p Here is my proposition: headingSyntax/heading p The filetriggers/file control file contains one directive per line. Leading and trailing whitespace, everything after the first hash character (tt#/tt) on any line, and empty lines are ignored. The following directives are supported. taglist tagttinterest-noawait/tt vartrigger-name/var/tag tagttinterest/tt vartrigger-name/var/tag item Specifies that the package is interested in the named trigger. The ttinterest/tt variant puts the triggering packages in the Triggers-Awaited state, and the ttinterest-noawait/tt variant does not. /item tagttactivate-noawait/tt vartrigger-name/var/tag tagttactivate/tt vartrigger-name/var/tag item Specifies that changes to this package's state will activate the named trigger. The ttactivate/tt variant puts this package in the Triggers-Awaited state, and the ttactivate-noawait/tt variant does not. /item /taglist /p p The tt*-noawait/tt directives should be used unless the packages awaiting triggers can not satisfy ttDepends/tt relationships until the triggers have been processed. In that case, the ttinterest/tt or ttactivate/tt directives should be used, as they will put the triggering packges in the Triggers-Awaited state, which does not satisfy dependencies. Note that pakcages unnecessarly entering this state can cause the early processing of triggers or even dependency loops. /p I also added through the ttinterst/tt or ttactivate/tt directives after When a configured package activates a trigger. I applied the other changes you proposed as well, with minor rewording: - prgndpkg/prgn keeps a list, ttTriggers-Awaited/tt of - interested packages whose trigger processing is awaited. Every + prgndpkg/prgn keeps a list of interested packages whose trigger + processing is awaited, which is stored in the + ttTriggers-Awaited/tt field in dpkg's status database. Every I attached an updated version of the patch. Cheers, -- Charles diff --git a/policy.sgml b/policy.sgml index 1508231..5d53cff 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,11 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's -
Bug#582109: debian-policy: document triggers where appropriate
Hi Charles, On Fri, 15 Mar 2013, Charles Plessy wrote: I am still seeking comments for the attached patch, that describes Dpkg triggers. Here are my comments. There's quite a bit of work left. From 6a7fd0e49cb8dbd025771feb95c2dcafb408c1b8 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sat, 2 Mar 2013 22:48:04 +0900 Subject: [PATCH] Document dpkg triggers. Closes: #582109. --- policy.sgml | 275 ++-- 1 file changed, 268 insertions(+), 7 deletions(-) diff --git a/policy.sgml b/policy.sgml index a41bc1f..c6e1a9e 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,12 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + file filetriggers/file that lists the the filetriggers/file file (invert two words) + qref id=dpkg-triggerstriggers/qref that the package is interested + in. the triggers file (see man deb-triggers) can contain interest directives but also activate ones. So this needs to be reworded. For example “the triggers file wich defines the package's interaction with dpkg's trigger system” + Dpkg defines the folowing states for the packages. + taglist + tagNot-Installed/tag I would use the precise states listed in dpkg(1), i.e. entirely in lowercase. (same for all the states) @@ -4141,6 +4189,26 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + Process one or more qref id=dpkg-triggerstriggers/qref that + this package is eminterested/em in. In case of failure the + package's state becomes ttconfig-failed/tt, so that the trigger + processing will not be attempted again until explicitly + requestedfootnote I don't think that it's marked config-failed to not retry the trigger processing. It's just that we need an error state and that config-failed can be reused for this purpose precisely because anything done by trigger processing is supposed to also be done during normal configuration (so it is effectively retried on next configure). “In case of failure the package's state becomes ttconfig-failed/tt, and the task associated to the trigger processing will be completed by the ttpostinst configure/tt during the next package's configuration.” + When an interested package has more than one trigger and wants + to process them differently, the list of triggers can be can be s/can be can be/can be/ @@ -4694,6 +4762,198 @@ fi /p /sect + + sect id=dpkg-triggers + headingDpkg triggers/heading + + p + A prgndpkg/prgn trigger is a facility that allows events caused + by the installation, upgrade or removal of one package, and of + eminterest/em to another package, to be recorded and + aggregated, and processed later by the interested package. This + feature simplifies various registration and system-update tasks and + reduces duplication of processing. + p “prgndpkg/prgn triggers allows packages to monitor events caused by the installation, upgrade or removal of packages. Monitoring packages are said to be eminterested/em in some triggers. On the other side, triggers must be emactivated/em to record the event notification on the eminterested package/em. The latter is then said to have empending triggers/em and the emactivating/em package (if any) is said to await the processing of the trigger. Thanks to this feature, it's easy to avoid duplication of processing logic among packages by implementing it in one package and making sure that all other packages rely on triggers to execute the wanted code.” + p + Each trigger is named, and at any time zero or more packages may be + eminterested/em in it. Packages declare their interest by + including a filetriggers/file file in their control archive. The triggers file can contain activate directives too so I'd suggest to be more explicit: “For a package to declare its interest in a trigger, it must include one of the ttinterest/tt directives in the filetriggers/file file in its control archive.” Then start a new paragraph describing the syntax of the triggers file. + This file contains one directive per line. Leading and trailing Useless
Bug#582109: debian-policy: document triggers where appropriate
Raphael Hertzog hert...@debian.org writes: On Fri, 15 Mar 2013, Charles Plessy wrote: + Dpkg defines the folowing states for the packages. + taglist +tagNot-Installed/tag I would use the precise states listed in dpkg(1), i.e. entirely in lowercase. (same for all the states) I thought Guillem requested we use the capitalized versions. I think the capitalized versions stand out more and make it clearer that the expected meaning isn't necessarily the plain English meaning of the phrase. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Wed, 10 Apr 2013, Russ Allbery wrote: Raphael Hertzog hert...@debian.org writes: On Fri, 15 Mar 2013, Charles Plessy wrote: +Dpkg defines the folowing states for the packages. +taglist + tagNot-Installed/tag I would use the precise states listed in dpkg(1), i.e. entirely in lowercase. (same for all the states) I thought Guillem requested we use the capitalized versions. I think the capitalized versions stand out more and make it clearer that the expected meaning isn't necessarily the plain English meaning of the phrase. Ok, but then we ought to be consistent and avoid usage of ttconfig-files/tt or ttconfig-failed/tt and other similar mention of states elsewhere. BTW, I just notice that ttconfig-failed/tt in the text was wrong and should refer to Half-Configured. Cheers, -- Raphaël Hertzog ◈ Debian Developer Get the Debian Administrator's Handbook: → http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Fri, 15 Mar 2013, Charles Plessy wrote: + Dpkg defines the folowing states for the packages. + taglist +tagNot-Installed/tag s/folowing/following Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Fri, Mar 15, 2013 at 04:11:19AM +0100, Guillem Jover a écrit : On Fri, 2013-03-15 at 08:37:25 +0900, Charles Plessy wrote: I am still seeking comments for the attached patch, that describes Dpkg triggers. I've not yet allocated a chunk of time to take a look into this, will try to do soonish, although I don't think there's any kind of hurry with this for now. Thanks Guillem, like the other enhancements to the Policy, there is nothing that is strictly urgent. However, I worked with passion on this patch, and I would be very pleased if others could also have a look at it. In particular, for others who would think that it is be better for such a technical patch that the final seconding comes from people who know dpkg very well, I agree, but please do not hesitate to make comments if you see defects, unclear or missing parts, possible improvements, etc. Have a nice day, -- Charles Plessy Debian Med packaging team, http://www.debian.org/devel/debian-med Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Hello everybody, I am still seeking comments for the attached patch, that describes Dpkg triggers. Have a nice day, -- Charles From 6a7fd0e49cb8dbd025771feb95c2dcafb408c1b8 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sat, 2 Mar 2013 22:48:04 +0900 Subject: [PATCH] Document dpkg triggers. Closes: #582109. --- policy.sgml | 275 ++-- 1 file changed, 268 insertions(+), 7 deletions(-) diff --git a/policy.sgml b/policy.sgml index a41bc1f..c6e1a9e 100644 --- a/policy.sgml +++ b/policy.sgml @@ -900,9 +900,12 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + file filetriggers/file that lists the + qref id=dpkg-triggerstriggers/qref that the package is interested + in. /p p @@ -3958,6 +3961,51 @@ Checksums-Sha256: /p p + Dpkg defines the folowing states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and configuration has been started, but + not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4141,6 +4189,26 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + Process one or more qref id=dpkg-triggerstriggers/qref that + this package is eminterested/em in. In case of failure the + package's state becomes ttconfig-failed/tt, so that the trigger + processing will not be attempted again until explicitly + requestedfootnote + When an interested package has more than one trigger and wants + to process them differently, the list of triggers can be can be + examined in a shell script like this: + example +case $2 in +* trigger-name-a *) process-trigger-a ;; +esac/example + Generally each trigger name should be tested for separately, as + the postinst will often be called for several triggers at once. + /footnote. + /item /taglist /p @@ -4694,6 +4762,198 @@ fi /p /sect + + sect id=dpkg-triggers + headingDpkg triggers/heading + + p + A prgndpkg/prgn trigger is a facility that allows events caused + by the installation, upgrade or removal of one package, and of + eminterest/em to another package, to be recorded and + aggregated, and processed later by the interested package. This + feature simplifies various registration and system-update tasks and + reduces duplication of processing. + p + + p + Each trigger is named, and at any time zero or more packages may be + eminterested/em in it. Packages declare their interest by + including a filetriggers/file file in their control archive. + This file contains one directive per line. Leading and trailing + whitespace, everything after the first hash character (tt#/tt) + on any line, and empty lines are ignored. The following directives + are supported. + taglist + tagttinterest/tt vartrigger-name/var/tag + tagttinterest-noawait/tt vartrigger-name/var/tag + item + Specifies that the package is interested in the named trigger. + The emnoawait/em variant does not put the triggering packages + in Triggers-Awaited state, and does not add the + interested package to the ttTriggers-Awaited/tt list of the + triggering package. + /item + + tagttactivate/tt vartrigger-name/var/tag + tagttactivate-noawait/tt vartrigger-name/var/tag + item + Specifies that changes to this package's state
Bug#582109: debian-policy: document triggers where appropriate
Hi Guillem, thank you for your comments (some quoted below). Le Sat, Mar 02, 2013 at 03:37:36PM +0100, Guillem Jover a écrit : This is documented in the dpkg man page (PACKAGE STATES), sorry for not mentioning this before. We unified the states in policy to be all capitalized some time ago, I think it would make sense to follow that convention to not confuse the terminology usage. I'm not sure, if we should mention how to transition from/to states in this description, doing that in a dedicated section on how those transitions happen might be better (this re to the “has been purged”). To simplify things as suggested, I pasted the text from dpkg's manual page (only changing your system to the system, and removed OK.) to the proposed addition to the Policy. I also corrected capitalisation. Can you do the same in the manual pages ? For the markup of the state names, while I am not completely satisfied with having them flanked with quotes instead of either italics or monospaced, I think that we can defer this to the next major release of the Policy. I attached an updated patch. Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan From e2be0cdb4537099cef64745414f8adf97ec43509 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sat, 2 Mar 2013 22:48:04 +0900 Subject: [PATCH] Document dpkg triggers. Closes: #582109. --- policy.sgml | 275 ++-- 1 file changed, 268 insertions(+), 7 deletions(-) diff --git a/policy.sgml b/policy.sgml index d81891c..83eb839 100644 --- a/policy.sgml +++ b/policy.sgml @@ -892,9 +892,12 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + file filetriggers/file that lists the + qref id=dpkg-triggerstriggers/qref that the package is interested + in. /p p @@ -3950,6 +3953,51 @@ Checksums-Sha256: /p p + Dpkg defines the folowing states for the packages. + taglist + tagNot-Installed/tag + item + The package is not installed on the system. + /item + + tagConfig-Files/tag + item + Only the configuration files of the package exist on the system. + /item + + tagHalf-Installed/tag + item + The installation of the package has been started, but not + completed for some reason. + /item + + tagUnpacked/tag + item + The package is unpacked, but not configured. + /item + + tagHalf-Configured/tag + item + The package is unpacked and configuration has been started, but + not yet completed for some reason. + /item + + tagTriggers-Awaited/tag + item + The package awaits trigger processing by another package. + /item + + tagTriggers-Pending/tag + item + The package has been triggered. + /item + + tagInstalled/tag + item + The package is unpacked and configured. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4133,6 +4181,26 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + Process one or more qref id=dpkg-triggerstriggers/qref that + this package is eminterested/em in. In case of failure the + package's state becomes ttconfig-failed/tt, so that the trigger + processing will not be attempted again until explicitly + requestedfootnote + When an interested package has more than one trigger and wants + to process them differently, the list of triggers can be can be + examined in a shell script like this: + example +case $2 in +* trigger-name-a *) process-trigger-a ;; +esac/example + Generally each trigger name should be tested for separately, as + the postinst will often be called for several triggers at once. + /footnote. + /item /taglist /p @@ -4686,6 +4754,198 @@ fi /p /sect + + sect id=dpkg-triggers + headingDpkg triggers/heading + + p + A prgndpkg/prgn trigger is a facility that allows events caused + by the installation, upgrade or removal of one package, and of + eminterest/em to another package, to be recorded and + aggregated, and processed later by the interested package. This + feature simplifies various registration and system-update tasks and + reduces duplication of processing.
Bug#582109: debian-policy: document triggers where appropriate
Le Sun, Feb 24, 2013 at 04:41:55PM +0900, Charles Plessy a écrit : I am having a look at how to document triggers. In order to simplify the explanation and re-use more easily material from the file above, I think that we would benefit from documenting the dpkg states for a package. How about adding the following to the Policy's section 6.1 (Introduction to package maintainer scripts) ? Dpkg defines the folowing states for the packages. taglist tagttnot-installed/tt/tag item The package is not installed or has been purged. /item tagttconfig-files/tt/tag item The package has been removed; its configuration files remain. /item tagtthalf-installed/tt/tag item Errors happened during installation, upgrade or removal. Solving them requires the package to be re-installed. /item tagttunpacked/tt/tag item The files contained in the package have been successfuly unpacked, but the maintainer scripts have not been executed. Thus, the files created by the maintainer scripts are not yet available. /item tagtthalf-configured/tt/tag item The package has been unpacked, and an error occured during the execution of one of its maintainer scripts. /item tagtttriggers-awaited/tt/tag item The package has been unpacked and configured, and its installation activated some prgndpkg/prgn triggers that have not yet been executed. /item tagtttriggers-pending/tt/tag item Some triggers handled by this package have been activated and are not yet executed. /item tagttinstalled/tt/tag item The package is installed, no further action is required. /item /taglist For the half-installed and half-configured, I am not very confident on what I wrote and surely feedback. Have a nice week-end, -- Charles -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Dear all, pasting a lot from /usr/share/doc/dpkg-dev/triggers.txt.gz and deb-triggers(1), I have drafted a patch to the Policy to document triggers. Your comments are very welcome. Have a nice week-end, -- Charles From 04f094a0bfa98643ccead594be9d880439eae0b8 Mon Sep 17 00:00:00 2001 From: Charles Plessy ple...@debian.org Date: Sat, 2 Mar 2013 22:48:04 +0900 Subject: [PATCH] Document dpkg triggers. Closes: #582109. --- policy.sgml | 280 ++-- 1 file changed, 273 insertions(+), 7 deletions(-) diff --git a/policy.sgml b/policy.sgml index d81891c..7d9872d 100644 --- a/policy.sgml +++ b/policy.sgml @@ -892,9 +892,12 @@ zope. the package. Other control information files include the qref id=sharedlibs-symbolsfilesymbols/file file/qref or qref id=sharedlibs-shlibdepsfileshlibs/file file/qref - used to store shared library dependency information and + used to store shared library dependency information, the fileconffiles/file file that lists the package's - configuration files (described in ref id=config-files). + configuration files (described in ref id=config-files), and the + file filetriggers/file that lists the + qref id=dpkg-triggerstriggers/qref that the package is interested + in. /p p @@ -3950,6 +3953,56 @@ Checksums-Sha256: /p p + Dpkg defines the folowing states for the packages. + taglist + tagttnot-installed/tt/tag + item + The package is not installed or has been purged. + /item + + tagttconfig-files/tt/tag + item + The package has been removed; its configuration files remain. + /item + + tagtthalf-installed/tt/tag + item + Errors happened during installation, upgrade or removal. Solving + them requires the package to be re-installed. + /item + + tagttunpacked/tt/tag + item + The files contained in the package have been successfuly unpacked, + but the maintainer scripts have not been executed. Thus, the + files created by the maintainer scripts are not yet available. + /item + + tagtthalf-configured/tt/tag + item + The package has been unpacked, and an error occured during the + execution of one of its maintainer scripts. + /item + + tagtttriggers-awaited/tt/tag + item + The package has been unpacked and configured, and its + installation activated some prgndpkg/prgn triggers that have + not yet been executed. + /item + + tagtttriggers-pending/tt/tag + item + Some triggers handled by this package have been activated and are + not yet executed. + /item + + tagttinstalled/tt/tag + item + The package is installed, no further action is required. + /item + /taglist + p Broadly speaking the prgnpreinst/prgn is called before (a particular version of) a package is unpacked, and the prgnpostinst/prgn afterwards; the prgnprerm/prgn @@ -4133,6 +4186,26 @@ Checksums-Sha256: from the package dependencies are not available is often the best approach. /item + + tagvarpostinst/var tttriggered/tt + vartrigger-name/var vartrigger-name/var .../tag + item + Process one or more qref id=dpkg-triggerstriggers/qref that + this package is eminterested/em in. In case of failure the + package's state becomes ttconfig-failed/tt, so that the trigger + processing will not be attempted again until explicitly + requestedfootnote + When an interested package has more than one trigger and wants + to process them differently, the list of triggers can be can be + examined in a shell script like this: + example +case $2 in +* trigger-name-a *) process-trigger-a ;; +esac/example + Generally each trigger name should be tested for separately, as + the postinst will often be called for several triggers at once. + /footnote. + /item /taglist /p @@ -4686,6 +4759,198 @@ fi /p /sect + + sect id=dpkg-triggers + headingDpkg triggers/heading + + p + A prgndpkg/prgn trigger is a facility that allows events caused + by the installation, upgrade or removal of one package, and of + eminterest/em to another package, to be recorded and + aggregated, and processed later by the interested package. This + feature simplifies various registration and system-update tasks and + reduces duplication of processing. + p + + p + Each trigger is named, and at any time zero or more packages may be + eminterested/em in it. Packages declare their interest by + including a filetriggers/file file in their control archive. + This file contains one directive per line. Leading and trailing + whitespace, everything after the first hash character (tt#/tt) + on any line, and empty lines are ignored. The following directives + are supported. + taglist + tagttinterest/tt vartrigger-name/var/tag + tagttinterest-noawait/tt
Bug#582109: debian-policy: document triggers where appropriate
Hi! On Sat, 2013-03-02 at 18:45:30 +0900, Charles Plessy wrote: Le Sun, Feb 24, 2013 at 04:41:55PM +0900, Charles Plessy a écrit : I am having a look at how to document triggers. In order to simplify the explanation and re-use more easily material from the file above, I think that we would benefit from documenting the dpkg states for a package. This is documented in the dpkg man page (PACKAGE STATES), sorry for not mentioning this before. How about adding the following to the Policy's section 6.1 (Introduction to package maintainer scripts) ? We unified the states in policy to be all capitalized some time ago, I think it would make sense to follow that convention to not confuse the terminology usage. Dpkg defines the folowing states for the packages. taglist tagttnot-installed/tt/tag item The package is not installed or has been purged. /item I'm not sure, if we should mention how to transition from/to states in this description, doing that in a dedicated section on how those transitions happen might be better (this re to the “has been purged”). tagttconfig-files/tt/tag item The package has been removed; its configuration files remain. /item Related to state transitions, I'd talk about the current state (is) not how we got there (has been), here and in all other state descriptions. tagtthalf-installed/tt/tag item Errors happened during installation, upgrade or removal. Solving them requires the package to be re-installed. /item ... or removed. Same comment about state transitions. tagttunpacked/tt/tag item The files contained in the package have been successfuly unpacked, but the maintainer scripts have not been executed. Thus, the files created by the maintainer scripts are not yet available. /item Configuration might involve changing existing files, or changing parameters through existing APIs that change, say, a database on the backend for example, so I'd avoid explicitly mentioning that files might not be available, as that's not really comprehensive. tagtthalf-configured/tt/tag item The package has been unpacked, and an error occured during the execution of one of its maintainer scripts. /item Same comment about state transitions. This state could also happen during removal for example. tagtttriggers-awaited/tt/tag item The package has been unpacked and configured, and its installation activated some prgndpkg/prgn triggers that have not yet been executed. /item I'd say that the triggers need to be processed, and not executed. Also do we need to say that those are dpkg triggers, I'd say they are just package triggers. tagtttriggers-pending/tt/tag item Some triggers handled by this package have been activated and are not yet executed. /item Same comment about executed → processed. tagttinstalled/tt/tag item The package is installed, no further action is required. /item /taglist The “no further action is required” seems a bit confusing, to me it reads as there's nothing else to be done to the package ever again, not even upgrades or removals. :) Hope that helps. Thanks, Guillem -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Le Tue, May 18, 2010 at 02:50:02PM +0200, Raphaël Hertzog a écrit : The policy needs to be updated to take into account the dpkg triggers. At the very least it needs to document the new invocations of the postinst in chapter 6 (postinst triggered ...) see /usr/share/doc/dpkg-dev/triggers.txt.gz Dear all, I am having a look at how to document triggers. In order to simplify the explanation and re-use more easily material from the file above, I think that we would benefit from documenting the dpkg states for a package. The manual page of dpkg-query indicates: - Not-installed - Config-files - Half-installed - Unpacked - Half-configured - Triggers-awaiting - Triggers-pending - Installed The documentation in /usr/share/doc/dpkg-dev/triggers.txt.gz also mentions config-failed. I will look for a comprehensive list but if you already have the answer one please let me know. I wonder where to add this information: either in chapter 3 (binary packages) or chapter 6 (Package maintainer scripts and installation procedure). What do you think ? Have a nice Sunday, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
Package: debian-policy Version: 3.8.4.0 Severity: normal The policy needs to be updated to take into account the dpkg triggers. At the very least it needs to document the new invocations of the postinst in chapter 6 (postinst triggered ...) see /usr/share/doc/dpkg-dev/triggers.txt.gz -- System Information: Debian Release: squeeze/sid APT prefers unstable APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (150, 'experimental') Architecture: i386 (x86_64) Kernel: Linux 2.6.32-5-amd64 (SMP w/2 CPU cores) Locale: LANG=fr_FR.UTF-8, LC_CTYPE=fr_FR.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash debian-policy depends on no packages. debian-policy recommends no packages. Versions of packages debian-policy suggests: ii doc-base 0.9.5 utilities to manage online documen -- no debconf information -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#582109: debian-policy: document triggers where appropriate
On Tue, May 18, 2010 at 02:50:02PM +0200, Raphaël Hertzog wrote: Package: debian-policy Version: 3.8.4.0 Severity: normal The policy needs to be updated to take into account the dpkg triggers. At the very least it needs to document the new invocations of the postinst in chapter 6 (postinst triggered ...) see /usr/share/doc/dpkg-dev/triggers.txt.gz and for those who want a slightly less dense description, i wrote something up a while back that you can feel free to borrow from: http://www.seanius.net/blog/2009/09/dpkg-triggers-howto/ (though i am not volunteering to do the policy writing myself) sean signature.asc Description: Digital signature
