Add even more config options and try to handle configuration problems

arising if we upgrade essential or predependencies which need to be
configured before even unpacking packages depending on them.

1 files changed, 62 insertions, 19 deletions

diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index 89de8ea4..808c852a 100644
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -465,28 +465,30 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";};
      </varlistentry>
    </variablelist>
 
-   <refsect2><title>dpkg trigger usage</title>
+   <refsect2><title>dpkg trigger usage (and related options)</title>
      <para>APT can call dpkg in a way so it can make aggressive use of triggers over
      multiply calls of dpkg. Without further options dpkg will use triggers only in between his
-     own run. Activating these options can therefore descrease the time needed to perform the
+     own run. Activating these options can therefore decrease the time needed to perform the
      install / upgrade. Note that it is intended to activate these options per default in the
-     future, but as it changes the way apt calling dpkg drastical it needs a lot more testing.
+     future, but as it changes the way APT calling dpkg drastical it needs a lot more testing.
      <emphasis>These options are therefore currently experimental and should not be used in
      productive environments.</emphasis> Also it breaks the progress reporting so all frontends will
      currently stay around half (or more) of the time in the 100% state while it actually configures
      all packages.</para>
-     <para>If you have understand the current risks and problems with these options, but want
-     to help testing them create a new configuration file with the following three options activated.
-     Please report any bugs and problems you encounter and make sure to note that you have used
-     these options in the reports. Asking dpkg for help could also be useful for debugging proposes,
-     see e.g. <command>dpkg --audit</command>.
+     <para>Note that it is not garanteed that APT will support these options or that these options will
+     not cause (big) trouble in the future. If you have understand the current risks and problems with
+     these options, but are brave enough to help testing them create a new configuration file and test a
+     combination of options. Please report any bugs, problems and improvements you encounter and make sure
+     to note which options you have used in your reports. Asking dpkg for help could also be useful for
+     debugging proposes, see e.g. <command>dpkg --audit</command>. A defensive option combination would be
 <literallayout>DPkg::NoTriggers "true";
-DPkg::NoConfigure "true";
-DPkg::ConfigurePending "true";</literallayout>
-     </para>
+PackageManager::Configure "smart";
+DPkg::ConfigurePending "true";
+DPkg::TriggersPending "true";
+OrderList::Score::Immediate 100;</literallayout></para>
 
      <variablelist>
-       <varlistentry><term>NoTriggers</term>
+       <varlistentry><term>DPkg::NoTriggers</term>
        <listitem><para>Add the no triggers flag to all dpkg calls (expect the ConfigurePending call).
        See &dpkg; if you are interested in what this actually means. In short: dpkg will not run the
        triggers then this flag is present unless it is explicit called to do so in an extra call.
@@ -494,20 +496,61 @@ DPkg::ConfigurePending "true";</literallayout>
        meaning: Previously these option only append --no-triggers to the configure calls to dpkg -
        now apt will add these flag also to the unpack and remove calls.</para></listitem>
        </varlistentry>
-       <varlistentry><term>NoConfigure</term>
-       <listitem><para>Set this option to true will prevent apt to call explicit the configuration
-       for all packages. The packages will only be called to unpack (or remove), so dpkg can handle the
-       configuration process. Activating this option will implicit activate also the next option per
+       <varlistentry><term>PackageManager::Configure</term>
+       <listitem><para>Valid values are "<literal>all</literal>", "<literal>smart</literal>" and "<literal>no</literal>".
+       "<literal>all</literal>" is the default value and causes APT to configure all packages explicit.
+       The "<literal>smart</literal>" way is it to configure only packages which need to be configured before
+       another package can be unpacked (Pre-Depends) and let the rest configure by dpkg with a call generated
+       by the next option. "<literal>no</literal>" on the other hand will not configure anything and totally
+       relay on dpkg for configuration (which will at the moment fail if a Pre-Depends is encountered).
+       Setting this option to another than the all value will implicit activate also the next option per
        default as otherwise the system could end in an unconfigured status which could be unbootable!
        </para></listitem>
        </varlistentry>
-       <varlistentry><term>ConfigurePending</term>
+       <varlistentry><term>DPkg::ConfigurePending</term>
        <listitem><para>If this option is set apt will call <command>dpkg --configure --pending</command>
        to let dpkg handle all required configurations and triggers. This option is activated automatic
-       per default if <literal>NoConfigure</literal> is set, but deactivating could be useful
-       if you want to run APT multiple times in a row - e.g. in an installer. In this sceneries you should
+       per default if the previous option is not set to <literal>all</literal>, but deactivating could be useful
+       if you want to run APT multiple times in a row - e.g. in an installer. In this sceneries you could
        deactivate this option in all but the last run.</para></listitem>
        </varlistentry>
+       <varlistentry><term>DPkg::TriggersPending</term>
+       <listitem><para>Useful for <literal>smart</literal> configuration as a package which has pending
+       triggers is not considered as <literal>installed</literal> and dpkg treats them as <literal>unpacked</literal>
+       currently which is a dealbreaker for Pre-Dependencies (see debbugs #526774). Note that this will
+       process all triggers, not only the triggers needed to configure this package.</para></listitem>
+       </varlistentry>
+       <varlistentry><term>Dpkg::NoConfTriggers</term>
+       <listitem><para>DPkg currently will ignore the --triggers or --no-triggers flag if the trigger
+       is already pending. This option therefore has no real effect as long as dpkg doesn't change
+       his behavior. The option is automatical activated if <literal>DPkg::NoTriggers</literal> is
+       activated. You should use <literal>DPkg::TriggersPending</literal> to take care of these pending
+       triggers.</para></listitem>
+       </varlistentry>
+       <varlistentry><term>PackageManager::UnpackAll</term>
+       <listitem><para>As the configuration can be deferred to be done at the end by dpkg it can be
+       tried to order the unpack series only by critical needs, e.g. by Pre-Depends. Default is true
+       and therefore the "old" method of ordering in verious steps by everything. While both method
+       were present in earlier APT versions the <literal>OrderCritical</literal> method was unused, so
+       this method is very experimental and needs further improvements before becoming really useful.
+       </para></listitem>
+       </varlistentry>
+       <varlistentry><term>OrderList::Score::Immediate</term>
+       <listitem><para>Essential packages (and there dependencies) should be configured immediately
+       after unpacking. It will be a good idea to do this quite early in the upgrade process as these
+       these configure calls require currently also <literal>DPkg::TriggersPending</literal> which
+       will run quite a few triggers (which maybe not needed). Essentials get per default a high score
+       but the immediate flag is relativly low (a package which has a Pre-Depends is higher rated).
+       These option and the others in the same group can be used to change the scoring. The following
+       example shows the settings with there default values.
+       <literallayout>OrderList::Score {
+	Delete 500;
+	Essential 200;
+	Immediate 10;
+	PreDepends 50;
+};</literallayout>
+       </para></listitem>
+       </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>