eselect 1.0 released 附用户指南和开发指南

fei

eselect 1.0 released

Version 1.0 of eselect, the modular configuration framework, has been released. For developers, eselect simplifies the creation of -config and -update tools in the same way that the original ebuild simplified building software. For end users, eselect provides a more consistent interface and, as a side effect, implements part of GLEP 24 by making it easy to find available configuration tools. Interested users may install app-admin/eselect, if they do not have it already. There is also a user guide and a developer guide available online.
eselect User Guide
Content:

1. Introduction

A Brief Overview

eselect is a tool for administration and configuration on Gentoo systems. It will modify the system's behaviour and should be used with care by the system administrator. eselect is a modular framework for writing configuration utilities. It consists of:

    * A main program called eselect.
    * Various modules (*.eselect files) which carry out different tasks.
    * Several libraries which help ensure consistent behaviour and simplify the creation of new modules.

A modules provides several actions. Actions typically either display some information (list and show are common) or update the system somehow (for example, set and update). Each module also provides help and usage actions which explains how to use the module.

Note: Some modules install symlinks to the main program. eselect handles these intelligently. For example, it realises that profile-config list should be treated as if the user had run eselect profile list.

Advantages for end users and System Administrators

For system administrators and end users, tools written as eselect modules offer several advantages over the traditional "write each tool from scratch" approach:

    * Consistent UI - eselect modules provide a consistent user interface. Thanks to eselect's action framework, there is no longer any need to remember or look up dozens of -x style switches for each tool. The output format used by modules is also standardised.
    * Consistent Help format - All eselect modules provide easily accessible help documentation via the help and usage actions.
    * Consistent tool naming - There is no need to remember dozens of foo-config and update-blah names. To see a list of available tools, simply run eselect with no arguments. Of course the foo-config style are still available (via symlinks) if you prefer them.
    * Guaranteed Support for $ROOT - For those of you using $ROOT, you will not have to worry about whether a particular tool can handle it. Support for $ROOT is required for all eselect modules.

Advantages for Developers and Package Maintainers

Writing your tool as an eselect module rather than starting freom scratch gives you various benefits:

    * Faster Development time - Much of the work has already been done for you. eselect provides a series of libraries for common tasks, and the main eselect program handles most of the hard work for you. All you need to do is provide the actions and any domain specific functions you require.
    * Automatic Actions - The help and usage actions are automatically generated from your actions, so there is no need to spend time worrying about keeping these written up to date.
    * Easy, Consistent Behaviour - Because most of the input, output and command line handling is split off into library functions, writing a "standard" module which behaves consistently with other tools is very simple.
    * Familiar Format - For Gentoo developers, the eselect module format will be very familiar -- it is a bash file with a structure that is quite similar to ebuilds.

2. Using eselect

Usage

eselect should be called as shown below.

Code Listing 2.1: eselect - General Syntax

# eselect [<global options>] <module> <action> <options>

eselect features consistently name actions amongst most of its modules. There is only one global option as of now; --no-color, which asks eselect to stop showing colored output, which is the default. The following are the standard action names -- each modules may provied a subset of these actions:

    * help - Print the modules help screen.
    * usage - Print information on how to invoke the modules actions.
    * version - Print the modules version and other useful information.
    * list - Prints a set of selectable options.
    * show - Prints the currently active configuration(s).
    * set - Select one of the options offered by list.
    * enable - Enable one of the module specific features.
    * disable - Disable one of the module specific features.
    * update - Like set, but automatically selects an option rather than taking a parameter.
    * scan - Gather information about the system and store it for future usage by the module.

A typical session will look like the following for most modules:

Code Listing 2.2: Example eselect session

(Find out options for a module)
# eselect <module> list
These selections are available:
        [1]<first>
        [2]<second>
(Set an option)
# eselect <module> set <first>
(Display the current config)
# eselect <module> show
Active Selection:
        <item1>

You can usually set items either by name or number.
eselect Developer Reference
Content:

1. Introduction

About eselect

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

Note: This document assumes some basic familiarity with eselect. Please read the eselect User Guide in case you do not know the basics of eselect.

2. 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/.

Code Listing 2.1: cow.eselect code

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

DESCRIPTION="Do things to a cow"
MAINTAINER="foo@gentoo.org"
SVN_DATE='$Date: $'
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_actions_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.

3. Utility Functions

Introduction

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
    * Test Functions

To use any of the other functions, you have to first inherit the corresponding library file.

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.

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_ Function

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 the code listing shown below.

Code Listing 3.1: highlight example

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.

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 shown below.

Code Listing 3.2: svn_date_to_version usage

SVN_DATE='$Date: 2005/11/07 07:02:55 $'
VERSION=$(svn_date_to_version "${SVN_DATE}" )
(Now turn on the 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 add_config Function

The add_config function adds an item to an already stored value in the modules configuration file. It uses load_config/store_config internally and should be invoked as add_config filename key item.

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. It uses uname to determine the architecture.

Portage Functions

These are implemented in libs/portage.bash.

The arch Function

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

The portageq Function

The portageq function transparently wraps the corresponding Portage script whilst redirecting stderr to /dev/null.