path: root/doc/developer-guide.txt

============================
eselect Developer Reference
============================

Introduction
============

About eselect
--------------

eselect is a framework for simplifying and introducing consistency to the
various Gentoo ``foo-config`` and ``update-blah`` tools. It is an option for
developers who don't like reinventing the wheel, not a mandatory tool.

Getting Started
===============

Introduction
------------

When porting your application to use the eselect framework, you will generally
need to create a module. Often this can be heavily based upon an existing
module, so check to see whether there is something that does almost what you
need first (symlink handling is a good example of 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/`` ::


    # Copyright 1999-2005 Gentoo Foundation
    # Distributed under the terms of the GNU General Public License v2
    # $Id: $

    DESCRIPTION="Do things to a cow"
    MAINTAINER="ciaranm@gentoo.org"
    SVN_DATE='$Date: 2005-10-16 19:31:47 +0100 (Sun, 16 Oct 2005) $'
    VERSION=$(svn_date_to_version "${SVN_DATE}" )

    ### moo action

    describe_moo() {
        echo "Say moo"
    }

    describe_moo_parameters() {
        echo "<text>"
    }

    describe_moo_options() {
        echo "text : Text to display (optional)"
        echo "--dead : Use a dead cow"
        echo "--borg : Use a borged cow"
    }

    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

        echo "${@:-I am a cow}" | cowsay ${params}
    }

    ### think action

    describe_think() {
        echo "Show a pensive cow"
    }

    describe_think_parameters() {
        echo "<text>"
    }

    describe_think_options() {
        echo "text : Text to display"
        echo "--sheep : Use a sheep rather than a cow"
    }

    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

        echo "${@:-Am I a cow?}" | cowthink ${params}
    }

As you can see, the format is fairly similar to that of an ebuild -- it is a
bash script which is run in a special environment. This is intentional. There
are ``DESCRIPTION`` and ``VERSION`` variables globally which are used by
``eselect`` and some of the default action handlers, and a series of functions.

.. Warning:: In ebuilds, global scope code can cause problems. In eselect
  modules, global scope code is **absolutely forbidden**. Your module *will* be
  sourced for tasks other than running your actions. For example, if
  ``eselect list-modules`` is executed, your module will be sourced to obtain
  the description. Any code being run here would be a very bad thing.

Unlike ebuilds, the function names are not fixed. Any function whose name starts
with ``do_`` is considered to be an action implementation. It is conventional to
have a ``describe_`` function for every ``do_`` function that gives a short
description of the function -- this is 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.

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.)

help
        Display a help message. Automatic.
usage
        Display a usage message. Automatic.
version
        Display the current version. Automatic.
show
        Used to display the current provider of a symlink, or the currently
        installed module, or the current status.
list
        Used to display all available providers of a symlink, or all available
        modules.
set
        Used to set a new provider or a symlink.
enable
        Used to enable an optional feature.
disable
        Used to disable an optional feature.
scan
        Read information off the current filesystem.
update
        Used to automatically select a new provider for a symlink (as opposed to
        ``set``, which generally takes a parameter manually selecting the
        provider) or to gather system information that is vital to further
        actions.

.. Note:: You can override the ``help``, ``usage`` and ``version`` actions. They
  are provided by default by ``lib/default.eselect``. You should only do this
  with a good reason. Removing them is not a good idea, ``eselect`` assumes
  that they exist.

Utility Functions
=================

eselect provides many utility functions. These are useful for standardised
output formatting. Where possible, these should be used, especially for output.
If a standard function is not available for the output format required, consider
implementing one.

The following categories of function are available by default:

* General Utility Functions
* Output Utility Functions
* Manipulation Functions
* Path-Manipulation Functions
* Configuration Functions
* Multilib Functions
* Package-Manager Functions
* Test Functions

To use any of the other functions, you have first to ``inherit`` the corresponding
library file. (cf: `The ``inherit`` Function`_)

General Utility Functions
-------------------------

These are implemented in ``libs/core.bash``.

The ``die`` Function
,,,,,,,,,,,,,,,,,,,,

The ``die`` function (which, unlike its ebuild counterpart, *can* be called from
within subshells) is used to exit with a fatal error. It should be invoked as
``die -q "Message to display"``. If the ``-q`` is not provided, a stacktrace
will be displayed -- this should never happen because of user input error, only
abnormal conditions.

The ``check_do`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,

The ``check_do`` utility function checks that the first parameter is a function,
and then calls it with any additional parameters as its arguments. If the
function does not exist, ``die`` is called. Again, this is mostly internal.

The ``do_action`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``do_action`` utility function is the correct way to call a utility function
which is defined in another module. The first parameter is the action,
additional parameters are passed as arguments.

The ``inherit`` Function
,,,,,,,,,,,,,,,,,,,,,,,,

The ``inherit`` function sources eselect library files based on their name. In
order to source the file ``libs/foo.bash`` you have to add ``inherit foo`` in
global scope of your module.

The ``sed`` Function
,,,,,,,,,,,,,,,,,,,,

The ``sed`` function is a wrapper around GNU sed.

Output Utility Functions
------------------------

These are implemented in ``libs/output.bash``.

The ``write_error_msg`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``write_error_msg`` function displays an error message in the standard
format. It is similar to ``eerror``.

The ``write_warning_msg`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``write_warning_msg`` function displays a warning message in the standard
format. It is similar to ``ewarn``.

The ``write_list_`` Functions
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

To display a list, the ``write_list_`` family of functions should be used. Lists
should always start with a header, which can be displayed using
``write_list_start The Header``.

To display a numbered list, the ``write_numbered_list_entry`` function should be
used for each item. The first parameter is the list item number, the second is
the list item text (remember to quote this).

To display a keyword/value list, the ``write_kv_list_entry`` function should be
used. The first parameter is the key, the second the value.

The ``write_numbered_list`` function is a wrapper around
``write_numbered_list_entry`` that handles the numbering automatically. Each
parameter passed is displayed as a numbered list item, the first with index 1,
the second with index 2 and so on.

If -p is passed as the first argument to these functions, 'plain' highlighting
is used.

The ``highlight`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``highlight`` utility function can be used to emphasise some text which is
to be displayed by any of the above functions. A typical invocation might look
like: ::

         write_list_start "This is $(highlight list) example"
         write_kv_list_entry "First" "This is the first"
         write_kv_list_entry "$(highlight Second)" "This is the $(highlight second) entry"
         write_kv_list_entry "Third" "$(highlight The end)"

The ``highlight_warning`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``highlight_warning`` function is like ``highlight``, but for warnings. It
displays the text in question in red.

The ``space`` Function
,,,,,,,,,,,,,,,,,,,,,,

The ``space`` utility function takes a single integer parameter. It displays
that many space characters.

Test Functions
--------------

These are implemented in ``libs/tests.bash``.

The ``has`` Function
,,,,,,,,,,,,,,,,,,,,

The ``has`` utility function is like portage's ``hasq``. It returns true if and
only if the first parameter is equal to any of the remaining parameters.

The ``is_function`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``is_function`` utility function returns true if and only if its parameter
exists and is a function. This is mostly used internally, but may have some use
for modules.

The ``is_number`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,

Returns true if and only if the parameter is a positive whole number.

Path-Manipulation Functions
---------------------------

These are implemented in ``libs/path-manipulation``.

The ``basename`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,

The ``basename`` function is a transparent bash-only replacement for the external
``basename`` application.

The ``dirname`` Function
,,,,,,,,,,,,,,,,,,,,,,,,

The ``dirname`` function is a transparent bash-only replacement for the external
``dirname`` application.

The ``canonicalise`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``canonicalise`` function is a wrapper to either GNU readlink or realpath.

Manipulation Functions
----------------------

These are implemented in ``libs/manip.bash``.

The ``svn_date_to_version`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``svn_date_to_version`` function can be used instead of manually keeping
track of ``VERSION``. It is safe to use in global scope. The canonical usage is
as follows: ::

    SVN_DATE='$Date: $'
    VERSION=$(svn_date_to_version "${SVN_DATE}" )

Then turn on SVN keyword expansion for the module: ::

    svn propset svn:keywords "Date" modules/foo.eselect

Configuration Functions
-----------------------

These are implemented in ``libs/config.bash``.

The ``store_config`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``store_config`` function saves a key/value pair in a given
configuration file which is passed as first argument. This file
is a bash script consisting only of key/value pairs and should not be altered
manually. Comments in the file will be deleted each time ``store_config`` is
called. The function is invoked as ``store_config filename key value``.

The ``load_config`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``load_config`` function loads a stored value from the module's
configuration file. It is invoked as ``load_config filename key``
and prints the associated value.

The ``append_config`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``append_config`` function appends an item to an already stored value in the
modules configuration file. It uses ``load_config`` / ``store_config``
internally and should be invoked as ``append_config filename key item``. Note that
the item will not be appended if it occurs in the key's value already.

Multilib Functions
------------------

These are implemented in ``libs/multilib.bash``.

The ``list_libdirs`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``list_libdirs`` function returns a set of valid libdirs for the used
architecture. By default it uses /etc/ld.so.conf to obtain all valid libdirs. If
this fails due to a missing or broken file, this function uses ``uname`` to
determine the architecture.

Package-Manager Functions
-------------------------

These are implemented in ``libs/package-manager.bash``.

The ``arch`` Function
,,,,,,,,,,,,,,,,,,,,,

The ``arch`` function returns the correct value of ${ARCH} for the current
system. If the package manager cannot provide this information, ``arch`` falls
back to a ``uname -m`` and ``uname -s`` based lookup-table.

The ``envvar`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,

The ``envvar`` function retrieves the contents of a configuration-environemnt
variable for a given package. The syntax is ``envvar ${package-name}
${var-name}``.

The ``best_version`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``best_version`` Function returns the highest available version for a
given package dep atom.

The ``has_version`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``has_version`` function checks whether a given versioned package dep atom
is installed.

The ``get_repositories`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``get_repositories`` function returns a list of repositories known to the
package manager.

The ``get_repo_news_dir`` Function
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,

The ``get_repo_news_dir`` function returns the directory where to find GLEP 42
news items for a given repository.

A Basic Skeleton Library
========================

The ``libs/skel.bash`` library provides for a simple eselect module to switch
between implementations of anything that installs to a ``lib*`` directory
(i.e., lib, lib32, lib64). This will satisfy the requirements for most cases in
which one must switch between providers of a certain library or any package
installing a library.

Creating a simple module
------------------------

To use this library, all you need to do is create an eselect module containing
settings for the MODULE and IFACE variables. The MODULE variable is the name
used to refer to the implementations being switched in help text. The IFACE
variable indicates the subdirectory of /etc/env.d/ in which eselect files for
these implementations will be stored.

Each package must install a symlink map using the ``add`` action. The map must
use relative symlinks, one source-destination mapping per line in the form
``source destination``. The source must be relative to the destination, not
absolute. Instead of using ``lib`` or ``lib64`` etc., you must use @LIBDIR@.
The ``libs/skel.bash`` library detects the proper library directory at runtime.

.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : ..