====== MaintainerScripts ======

[[http://women.alioth.debian.org/wiki/index.php/English/MaintainerScripts]]

This explanation is intended to show how maintainer scripts work, in a more graphical manner than the one explained in the [[http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html#s-mscriptsinstact|Debian Policy]]. It's not intended as a replacement, but as a clarification.

For that purpose, this is going to be illustrated with several diagrams (made with [[http://www.gnome.org/projects/dia/|dia]]). In the figures, the maintainer scripts called and their params are showed inside boxes, the possible outcomes ("OK" or "FAILED") lead to different consequences. External actions to the maintainer scripts are showed in italics, while the package ending status is showed in bold.

===== Installation =====

Let's start with the most simple example: the installation of a new package, one that wasn't installed first.

{{.maintainer_scripts:install.png}}

Let's explain this figure a little bit: when a package is being installed, first ''preinst install'' is called, then ''postinst configure''. If all goes well, then the status of the package is **Installed**.

But, if something in the preinst install fails, then ''postrm abort-install'' is called. If this goes ok, the user will get an error message, and the package will be left in a **Not Installed** state. But if the ''postrm abort-install'' also fails, the package will be left in a nasty state: **Half Installed, Reinst required**. This means that the package needs to be reinstalled even if you want to remove it.

If something in the ''postinst configure'' fails, then the user is shown an error message, and the package is left in **Failed-Config** state.

The rest of the figures follow the same pattern, the explanations will be less verbose from now on.

===== Removal =====

{{.maintainer_scripts:remove.png}}

When removing a package that was previously installed, if everything goes well, the package will be left in the **Config Files** state, this means that it needs to be purged before it is in the **Not installed** state.

If something goes wrong at the postrm stage, and the ''postinst abort-remove'' script is called, then the package might be left in a strange state: it is still **Installed**, but the files are not there anymore. If any of the processes fails, when the package removal is tried again, it will resume from where it left (i.e. if the prerm worked and the postrm didn't, it'll resume from the postrm).

===== Purging =====

{{.maintainer_scripts:purge.png}}

If a package that is in state **Config Files** has to be purged, the cycle is really simple: the conffiles are deleted and then ''postrm purge'' is called. If it fails, the package is left in the same state, although the conffiles have already been deleted and the deletion won't be attempted again.

===== Removing and Purging =====

{{.maintainer_scripts:remove-purge.png}}

If the package is to be removed and purged at the same time, both diagrams combine, forming a diagram in which the package passes to be **Not installed** if everything goes ok.

Note that there's no way that the package might end-up in a **Config files** state, even if ''postrm purge'' fails.

===== Installing from Config-Files state =====

{{.maintainer_scripts:install-conffiles.png}}

If a package was installed and then removed, but not purged, it's left in **Config-Files** state. If the installation of a new version is attempted at that moment, the order of the scripts will be almost the same as the simple installation ones, but with a slight difference: the scripts receive a second parameter indicating the old version that used to be present.

The other difference is that if ''postrm abort-install'' is called, the package is left in the same state that was before the install was attempted (i.e **Config-Files**).

===== Upgrading =====

{{.maintainer_scripts:upgrade.png}}

The next step in complexity (and it's a big step) is doing an install that is actually upgrading an already installed package.

As you can see from the diagram, if all goes well four scripts are called, but when things go wrong, it gets much more complicated, and the package might be left in many different states.

===== Conflicting packages =====

The only thing left that is in the Policy and not in the previous diagram is when a package is being replaced by one that conflicts with it. I won't deal with it now and here, but if you are willing to do the tests and the diagrams yourself, you are free to edit this page and include them.

===== Sources for the diagrams =====

All this documentation is licensed under the [[wp>General_Public_License|GPL]] license. The diagrams used in this page were made with dia and are available for download at:

  * [[http://www.marga.com.ar/~marga/debian/diagrams/]]
  * {{.maintainer_scripts:install-conffiles.dia}}
  * {{.maintainer_scripts:install.dia}}
  * {{.maintainer_scripts:purge.dia}}
  * {{.maintainer_scripts:remove-purge.dia}}
  * {{.maintainer_scripts:remove.dia}}
  * {{.maintainer_scripts:upgrade.dia}}