docs: import usermanual from org.openembedded.documentation.

org.openembedded.documentation is deprecated now; please do all updates here!

1 files changed, 241 insertions, 0 deletions

diff --git a/docs/usermanual/reference/class_update-alternatives.xml b/docs/usermanual/reference/class_update-alternatives.xml
new file mode 100644
index 0000000000..cd86e3e6ab
--- /dev/null
+++ b/docs/usermanual/reference/class_update-alternatives.xml
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="update-alternatives_class" xreflabel="update-alternatives class">
+  <title>update-alternatives class</title>
+
+  <para>Some commands are available from multiple sources. As an example we
+  have <command>/bin/sh</command> available from <emphasis>busybox</emphasis>
+  and from <emphasis>bash</emphasis>. The busybox version is better from a
+  size perspective, but limited in functionality, while the bash version is
+  much larger but also provides far more features. The alternatives system is
+  designed to handle the situation where two commands are provided by two, or
+  more, packages. It ensures that one of the alternatives is always the
+  currently selected one and ensures that there are no problems with
+  installing and/or removing the various alternatives.</para>
+
+  <para>The update-alternatives class is used to register a command provided
+  by a package that may have an alternative implementation in a some other
+  package.</para>
+
+  <para>In the following sections we'll use the <command>/bin/ping</command>
+  command as an example. This command is available as a basic version from
+  busybox and as a more advanced version from iputils.</para>
+
+  <section>
+    <title>Naming of the alternative commands</title>
+
+    <para>When supplying alternative commands the target command itself is not
+    installed directly by any of the available alternatives. This is to ensure
+    that no package will replace files that were installed by one of the other
+    available alternative packages. The alternatives system will create a
+    symlink for the target command that points to the required
+    alternative.</para>
+
+    <para>For the <command>/bin/ping</command> case this means that neither
+    busybox nor iputils should actually install a command called
+    <command>/bin/ping</command>. Instead we see that the iputils recipe
+    installs it's version of ping as
+    <command>/bin/ping.iputils</command>:<screen>do_install () {
+    install -m 0755 -d ${D}${base_bindir} ${D}${bindir} ${D}${mandir}/man8
+    # SUID root programs
+    install -m 4755 ping ${D}${base_bindir}/ping.${PN}
+    ...
+}</screen></para>
+
+    <para>If you were to look at the busybox recipe you would see that it also
+    doesn't install a command called <command>/bin/ping</command>, instead it
+    installs it's command as <command>/bin/busybox</command>.</para>
+
+    <para>The important point to note is that neither package is installing an
+    actual <command>/bin/ping</command> target command.</para>
+  </section>
+
+  <section>
+    <title>How alternatives work</title>
+
+    <para>Before proceeding lets take a look at how alternatives are handled.
+    If we have a base image that includes only busybox then look at
+    <command>/bin/ping</command> we see that it is a symlink to
+    busybox:</para>
+
+    <para><screen>root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx    1 root     root            7 May  3  2006 /bin/ping -&gt; busybox</screen></para>
+
+    <para>This is what is expected since the busybox version of ping is the
+    only one installed on the system. Note again that it is only a symlink and
+    not an actual command.</para>
+
+    <para>If the iputils version of ping is now installed and we look at the
+    <command>/bin/ping</command> command again we see that it has been changed
+    to a symlink pointing at the iputils version of ping -
+    <command>/bin/ping.iptils</command>:</para>
+
+    <para><screen>root@titan:/etc# ipkg install iputils-ping
+Installing iputils-ping (20020927-r2) to root...
+Downloading http://nynaeve/ipkg-titan-glibc//iputils-ping_20020927-r2_sh4.ipk
+Configuring iputils-ping
+update-alternatives: Linking //bin/ping to ping.iputils
+root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx    1 root     root           12 May 13  2006 /bin/ping -&gt; ping.iputils</screen></para>
+
+    <para>The iputils version is considered to be the more fully featured
+    version of ping and is therefore the default when both versions are
+    installed.</para>
+
+    <para>What happens if the iputils-ping package is removed now? The symlink
+    should be changed to point back at the busybox version:</para>
+
+    <para><screen>root@titan:/etc# ipkg remove iputils-ping
+Removing package iputils-ping from root...
+update-alternatives: Linking //bin/ping to busybox
+root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx    1 root     root            7 May 13  2006 /bin/ping -&gt; busybox</screen></para>
+
+    <para>This simple example shows that the alternatives system is taking
+    care of ensuring the symlink is pointing to the correct version of the
+    command without any special interaction from the end users.</para>
+  </section>
+
+  <section>
+    <title>The update-alternatives command</title>
+
+    <para>Available alternatives need to be registered with the alternatives
+    system. This is handled by the <command>update-alternatives</command>
+    command. The help from the command shows it's usage options:<screen>root@titan:/etc# update-alternatives --help
+update-alternatives: help:
+
+Usage: update-alternatives --install &lt;link&gt; &lt;name&gt; &lt;path&gt; &lt;priority&gt;
+       update-alternatives --remove &lt;name&gt; &lt;path&gt;
+       update-alternatives --help
+&lt;link&gt; is the link pointing to the provided path (ie. /usr/bin/foo).
+&lt;name&gt; is the name in /usr/lib/ipkg/alternatives/alternatives (ie. foo)
+&lt;path&gt; is the name referred to (ie. /usr/bin/foo-extra-spiffy)
+&lt;priority&gt; is an integer; options with higher numbers are chosen.
+</screen></para>
+
+    <para>During postinst the update-alternatives command needs to be called
+    with the install option and during postrm it needs to be called with the
+    remove option.</para>
+
+    <para>The iputils recipe actual codes this directly (rather than using the
+    class) so we can see an example of the command being called:<screen>pkg_postinst_${PN}-ping () {
+    update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100
+}
+pkg_prerm_${PN}-ping () {
+    update-alternatives --remove ping ping.${PN}
+}</screen></para>
+
+    <para>In both cases the name that the alternatives are registered against,
+    <command>"ping"</command>, is passed in and the path to the iputils
+    version of the command, <command>"ping.${PN}"</command>. For the install
+    case the actual command name (where the symlink will be made from) and a
+    priority value are also supplied.</para>
+  </section>
+
+  <section>
+    <title>Priority of the alternatives</title>
+
+    <para>So why did the alternatives system prefer the iputils version of
+    ping over the busybox version? It's because of the relative priorities of
+    the available alternatives. When iputils calls update-alternatives the
+    last parameter passed is a priority:<screen> update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100</screen></para>
+
+    <para>So iputils is specifying a priority of 100 and if you look at
+    busybox you'll see it specifies a priority of 50 for ping. The alternative
+    with the highest priority value is the one that update-alternatives will
+    select as the version to actual use. In this particular situation the
+    authors have selected a higher priority for iputils since it is the more
+    capable version of ping and would not normally be installed unless
+    explicitly requested.</para>
+  </section>
+
+  <section>
+    <title>Tracking of the installed alternatives</title>
+
+    <para>You can actually see which alternatives are available and what their
+    priority is on a target system. Here we have an example in which both
+    busybox and iptuils-ping packages are installed: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping
+/bin/ping
+busybox 50
+ping.iputils 100</screen>If we remove iputils-ping, then we see that
+    alternatives file is updated to reflect this: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping
+/bin/ping
+busybox 50
+root@titan:/etc#</screen></para>
+
+    <para>The file lists the command first, and then each of the available
+    alternatives and their relative priorities.</para>
+  </section>
+
+  <section>
+    <title>Using the update-alternatives class</title>
+
+    <para>Neither busybox nor iputils actually use the update-alternatives
+    class - they call the update-alternatives functions directly. They need to
+    call the command directly since they need to register multiple
+    alternatives and the class does not support this. The class can only be
+    used when you have only a single alternative to register.</para>
+
+    <para>To use the class you need to inherent update-alternatives and then
+    define the name, path, link and priority as show in the following example
+    from the jamvm recipe:</para>
+
+    <para><screen>inherit autotools update-alternatives
+
+ALTERNATIVE_NAME = "java"
+ALTERNATIVE_PATH = "${bindir}/jamvm"
+ALTERNATIVE_LINK = "${bindir}/java"
+ALTERNATIVE_PRIORITY = "10"
+</screen></para>
+
+    <para>where the variables to be specified are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>ALTERNATIVE_NAME [Required]</term>
+
+        <listitem>
+          <para>The name that the alternative is registered against and needs
+          to be the same for all alternatives registering this command.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ALTERNATIVE_PATH [Required]</term>
+
+        <listitem>
+          <para>The path of the installed alternative. (This was iputils.ping
+          in the example used previously).</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ALTERNATIVE_LINK [Optional]</term>
+
+        <listitem>
+          <para>The name of the actual command. This is what the symlink will
+          be called and is the actual command that the use runs. The default
+          value is: <command>"${bindir}/${ALTERNATIVE_NAME}"</command></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ALTERNATIVE_PRIORITY [Optional]</term>
+
+        <listitem>
+          <para>The priority of this alternative. The alternative with the
+          highest valued priority will be selected as the default. The default
+          value is: <command>"10"</command>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The actual postinst and postrm commands that are registered by the
+    class are:<screen>update_alternatives_postinst() {
+    update-alternatives --install ${ALTERNATIVE_LINK} ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} ${ALTERNATIVE_PRIORITY}
+}
+
+update_alternatives_postrm() {
+    update-alternatives --remove ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH}
+}</screen></para>
+  </section>
+</section>
\ No newline at end of file