aboutsummaryrefslogtreecommitdiffstats
path: root/usermanual/reference
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2006-08-09 08:08:10 +0000
committerJamie Lenehan <lenehan@twibble.org>2006-08-09 08:08:10 +0000
commit68d6a668b7ec8099fa4e38d96e77fc84b976058d (patch)
tree8c2bb309d17690aa3a775fb05f8aa9f8d7871577 /usermanual/reference
parentedf65bcf35a668272da37227f41a33a8f5952f37 (diff)
downloadopenembedded-68d6a668b7ec8099fa4e38d96e77fc84b976058d.tar.gz
openembedded-68d6a668b7ec8099fa4e38d96e77fc84b976058d.tar.bz2
openembedded-68d6a668b7ec8099fa4e38d96e77fc84b976058d.zip
usermanual: Add a "Reference" section to the manual. Document the distutils,
update-alternatives and update-rc.d classes in the reference section. Each is documented in a seperate file so they can be easily moved elsewhere and so it's easier to edit seperate class reference information.
Diffstat (limited to 'usermanual/reference')
-rw-r--r--usermanual/reference/.mtn2git_empty0
-rw-r--r--usermanual/reference/class_distutils.xml46
-rw-r--r--usermanual/reference/class_update-alternatives.xml241
-rw-r--r--usermanual/reference/class_update-rc.d.xml134
4 files changed, 421 insertions, 0 deletions
diff --git a/usermanual/reference/.mtn2git_empty b/usermanual/reference/.mtn2git_empty
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/usermanual/reference/.mtn2git_empty
diff --git a/usermanual/reference/class_distutils.xml b/usermanual/reference/class_distutils.xml
new file mode 100644
index 0000000000..cf9a307f0e
--- /dev/null
+++ b/usermanual/reference/class_distutils.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+ <title>distutils</title>
+
+ <para>Distutils is a standard python system for building and installing
+ modules. This class is used to automate the building of python modules that
+ use the distutils system.</para>
+
+ <para>Any python package that requires the standard python commands to build
+ and install: <screen>python setup.py build
+python setup.py install</screen>is using distutils and can use this class.
+ </para>
+
+ <para>The distutils class will perform the build and install actions on the
+ setup.py package as required for building distutils packages, including
+ setting all the required parameters for cross compiling. It'll also do the
+ following:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Adds python-native to DEPENDS to ensure that python is built and
+ installed on the build host. This also ensure that the version of python
+ that is used during package creation matches the version of python that
+ will be installed on the target.</para>
+ </listitem>
+
+ <listitem>
+ <para>Adds python-core to RDEPENDS to ensure that the python-core is
+ installed when this module is installed. Note that you need to manually
+ add any other python module dependencies to RDEPENDS.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following example from the moin recipe shows how simple this can
+ make a python package:<screen>DESCRIPTION = "A full fledged WikiWiki system written in Python"
+LICENSE = "GPL"
+SECTION = "base"
+PRIORITY = "optional"
+MAINTAINER = "Your name &lt;yname@example.com&gt;"
+PR = "r1"
+
+SRC_URI = "${SOURCEFORGE_MIRROR}/moin/moin-${PV}.tar.gz"
+
+inherit distutils</screen>The header, source location and the inherit are all
+ that is required.</para>
+</section> \ No newline at end of file
diff --git a/usermanual/reference/class_update-alternatives.xml b/usermanual/reference/class_update-alternatives.xml
new file mode 100644
index 0000000000..82039222a8
--- /dev/null
+++ b/usermanual/reference/class_update-alternatives.xml
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+ <title>update-alternatives</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 ensure 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
diff --git a/usermanual/reference/class_update-rc.d.xml b/usermanual/reference/class_update-rc.d.xml
new file mode 100644
index 0000000000..d5089e5247
--- /dev/null
+++ b/usermanual/reference/class_update-rc.d.xml
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+ <title>update-rc.d</title>
+
+ <para>Services which need to be started during boot need to be registered
+ using the update-rc.d command. These services are required to have an init
+ script which is installed into <command>/etc/init.d</command> that can be
+ used to start and stop the service.</para>
+
+ <para>The following examples show a service being manually stopped and
+ started using it's init script:<screen>root@titan:/etc# /etc/init.d/syslog stop
+Stopping syslogd/klogd: stopped syslogd (pid 1551).
+stopped klogd (pid 1553).
+done
+root@titan:/etc# /etc/init.d/syslog start
+Starting syslogd/klogd: done
+root@titan:/etc#</screen>The update-rc.d class takes care of the following
+ automatically:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Registers the service with the system during postinst so it will
+ be automatically started on boot;</para>
+ </listitem>
+
+ <listitem>
+ <para>Stops the service during prerm so it will no longer be running
+ after being removed;</para>
+ </listitem>
+
+ <listitem>
+ <para>Unregisters the service during prerm so there will be no attempts
+ to start the removed service during boot;</para>
+ </listitem>
+
+ <listitem>
+ <para>Adds a build and run time dependency on the update-rc.d package
+ which it uses to register and unregister the services.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Usage is very simple, as shown by this example from dropbear:<screen>INITSCRIPT_NAME = "dropbear"
+INITSCRIPT_PARAMS = "defaults 10"
+
+inherit autotools update-rc.d</screen></para>
+
+ <para>where the variables are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>INITSCRIPT_NAME</term>
+
+ <listitem>
+ <para>The name of the init script, which the package will have
+ installed into /etc/init.d</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_PARAMS</term>
+
+ <listitem>
+ <para>The parameters to pass to the update-rc.d call during
+ installation. Typically this will be the work default followed by
+ either single number or a pair of numbers representing the start/stop
+ sequence number (both are set to the same if only one number is
+ supplied.)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The help from update-rc.d shows show the required parameters:<screen>root@titan:/etc# update-rc.d -h
+usage: update-rc.d [-n] [-f] [-r &lt;root&gt;] &lt;basename&gt; remove
+ update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; defaults [NN | sNN kNN]
+ update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; start|stop NN runlvl [runlvl] [...] .
+ -n: not really
+ -f: force
+ -r: alternate root path (default is /)
+ -s: invoke start methods if appropriate to current runlevel
+root@titan:/etc#</screen>The start and stop sequence numbers need to ensure
+ that the the service is started at the appropriate time relative to other
+ services, such as waiting for any service that it depends on before starting
+ (networking for example). Unless the service is a system or security related
+ service it's better to be started as late as possible.</para>
+
+ <section>
+ <title>Multiple update-rc.d packages</title>
+
+ <para>Define multiple init scripts within the one recipe is also supported
+ but note that each init script must be in it's own package. You cannot
+ have multiple init scripts in a single package. The following example is
+ from the quagga recipe:<screen># Main init script starts all deamons
+# Seperate init script for watchquagga
+INITSCRIPT_PACKAGES = "${PN} ${PN}-watchquagga"
+INITSCRIPT_NAME_${PN} = "quagga"
+INITSCRIPT_PARAMS_${PN} = "defaults 15 85"
+INITSCRIPT_NAME_${PN}-watchquagga = "watchquagga"
+INITSCRIPT_PARAMS_${PN}-watchquagga = "defaults 90 10"
+
+inherit autotools update-rc.d</screen> The variables that need to be declared
+ are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>INITSCRIPT_PACKAGES</term>
+
+ <listitem>
+ <para>The names of each package which includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_NAME_x</term>
+
+ <listitem>
+ <para>The same meaning as INITSCRIPT_NAME, but for the package x.
+ This would be repeated for each package that includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_PARAMS_x</term>
+
+ <listitem>
+ <para>The same meaning as INITSCRIPT_PARAMS, but for the package x.
+ This would be repeated for each package that includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</section> \ No newline at end of file