Update developer guide, bug 380731.

svn path=/trunk/; revision=828

1 files changed, 88 insertions, 58 deletions

diff --git a/doc/developer-guide.txt b/doc/developer-guide.txt
index 69dcdd3..0900064 100644
--- a/doc/developer-guide.txt
+++ b/doc/developer-guide.txt
@@ -28,86 +28,112 @@ something that can be copied rather than reinvented).
 A Simple Module
 ---------------
 
-It's easiest to illustrate by example. Here's a simple module, named
-``cow.eselect``. It has two actions, ``moo`` and ``think``, plus the
-standard ``help``, ``usage`` and ``version`` actions, and is installed
-to ``$(datadir)/eselect/modules/`` ::
-
+It's easiest to illustrate by example. Here's a simplified version of
+the ``kernel.eselect`` module. It has three actions, ``show``, ``list``,
+and ``set``, plus the standard ``help``, ``usage`` and ``version``
+actions, and is installed to ``$(datadir)/eselect/modules/`` ::
 
     # -*-eselect-*-  vim: ft=eselect
     # Copyright 2005-2011 Gentoo Foundation
-    # Distributed under the terms of the GNU GPL v2 or later
+    # Distributed under the terms of the GNU General Public License v2 or later
     # $Id: $
 
-    DESCRIPTION="Do things to a cow"
-    MAINTAINER="ciaranm@gentoo.org"
+    DESCRIPTION="Manage the /usr/src/linux symlink"
+    MAINTAINER="eselect@gentoo.org"
     SVN_DATE='$Date: $'
     VERSION=$(svn_date_to_version "${SVN_DATE}")
 
-    ### moo action
+    # find a list of kernel symlink targets
+    find_targets() {
+        local f
+        for f in "${EROOT}"/usr/src/linux-[[:digit:]]*; do
+            [[ -d ${f} ]] && basename "${f}"
+        done
+    }
 
-    describe_moo() {
-        echo "Say moo"
+    # remove the kernel symlink
+    remove_symlink() {
+        rm "${EROOT}/usr/src/linux"
     }
 
-    describe_moo_parameters() {
-        echo "<text>"
+    # set the kernel symlink
+    set_symlink() {
+        local target=$1
+
+        if is_number "${target}"; then
+            local targets=( $(find_targets) )
+            target=${targets[target-1]}
+        fi
+
+        [[ -z ${target} || ! -d ${EROOT}/usr/src/${target} ]] \
+            && die -q "Target \"$1\" doesn't appear to be valid!"
+
+        ln -s "${target}" "${EROOT}/usr/src/linux"
     }
 
-    describe_moo_options() {
-        echo "text : Text to display (optional)"
-        echo "--dead : Use a dead cow"
-        echo "--borg : Use a borged cow"
+    ### show action ###
+
+    describe_show() {
+        echo "Show the current kernel symlink"
     }
 
-    do_moo() {
-        local params=
-        while [[ ${1#--} != ${1} ]] ; do
-            if [[ "--dead" == ${1} ]] ; then
-                shift
-                params="${params} -d"
-            elif [[ "--borg" == "${1}" ]] ; then
-                shift
-                params="${params} -b"
-            elif [[ "--" == "${1}" ]] ; then
-                break
-            else
-                die -q "Unknown parameter ${1}"
-            fi
-        done
+    do_show() {
+        write_list_start "Current kernel symlink:"
+        if [[ -L ${EROOT}/usr/src/linux ]]; then
+            local kernel=$(canonicalise "${EROOT}/usr/src/linux")
+            write_kv_list_entry "${kernel%/}" ""
+        else
+            write_kv_list_entry "(unset)" ""
+        fi
+    }
+
+    ### list action ###
 
-        echo "${@:-I am a cow}" | cowsay ${params}
+    describe_list() {
+        echo "List available kernel symlink targets"
     }
 
-    ### think action
+    do_list() {
+        local i targets=( $(find_targets) )
 
-    describe_think() {
-        echo "Show a pensive cow"
+        write_list_start "Available kernel symlink targets:"
+        for (( i = 0; i < ${#targets[@]}; i++ )); do
+            # highlight the target where the symlink is pointing to
+            [[ ${targets[i]} = \
+                $(basename "$(canonicalise "${EROOT}/usr/src/linux")") ]] \
+                && targets[i]=$(highlight_marker "${targets[i]}")
+        done
+        write_numbered_list -m "(none found)" "${targets[@]}"
     }
 
-    describe_think_parameters() {
-        echo "<text>"
+    ### set action ###
+
+    describe_set() {
+        echo "Set a new kernel symlink target"
     }
 
-    describe_think_options() {
-        echo "text : Text to display"
-        echo "--sheep : Use a sheep rather than a cow"
+    describe_set_parameters() {
+        echo "<target>"
     }
 
-    do_think() {
-        local params=
-        while [[ ${1#--} != ${1} ]] ; do
-            if [[ "--sheep" == ${1} ]] ; then
-                shift
-                params="${params} -f sheep"
-            elif [[ "--" == "${1}" ]] ; then
-                break
-            else
-                die -q "Unknown parameter ${1}"
-            fi
-        done
+    describe_set_options() {
+        echo "target : Target name or number (from 'list' action)"
+    }
 
-        echo "${@:-Am I a cow?}" | cowthink ${params}
+    do_set() {
+        [[ -z $1 ]] && die -q "You didn't tell me what to set the symlink to"
+        [[ $# -gt 1 ]] && die -q "Too many parameters"
+
+        if [[ -L ${EROOT}/usr/src/linux ]]; then
+            # existing symlink
+            remove_symlink || die -q "Couldn't remove existing symlink"
+            set_symlink "$1" || die -q "Couldn't set a new symlink"
+        elif [[ -e ${EROOT}/usr/src/linux ]]; then
+            # we have something strange
+            die -q "${EROOT}/usr/src/linux exists but is not a symlink"
+        else
+            set_symlink "$1" || die -q "Couldn't set a new symlink"
+        fi
     }
 
 As you can see, the format is fairly similar to that of an ebuild -- it
@@ -131,8 +157,13 @@ used for ``eselect modulename help``, for example.
 The ``describe_action_options`` and ``describe_action_parameters``
 functions are optional.
 
-.. Note:: If eselect is invoked as ``cow-config`` or ``cow-update`` (for
-  example, via a symlink), it will automatically select the cow module.
+All eselect modules are required to support the ``ROOT`` variable.
+For prefix support, variables ``EPREFIX`` and ``EROOT`` are also defined
+and have the same meaning as in ebuilds.
+
+.. Note:: If eselect is invoked as ``foo-config`` or ``foo-update``
+  (for example, via a symlink), it will automatically execute the foo
+  module.
 
 All modules contributed to eselect should have a header indicating
 copyright. This must be an exact copy of the header in the above
@@ -144,8 +175,7 @@ Standard Action Names
 The following list contains suggested allowed names for actions.
 If there is no suitable name on the list for your task, it is best to
 ask for the list to be updated -- for consistency, it would be nice to
-have a standardised list of action names. (The cow module, being a silly
-demonstration module, is exempt.)
+have a standardised list of action names.
 
 help
     Display a help message. Automatic.