Project:Eselect/User guide

Introduction
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.
 * Various modules ( files) which carry out different tasks.
 * Several libraries which help ensure consistent behaviour and simplify the creation of new modules.

A module provides several actions. Actions typically either display some information ( and actions are common) or update the system somehow (for example,  and ). Each module also provides and  actions which explain how to use the module.

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 user interface
 * 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 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 and  actions.


 * Consistent tool naming
 * There is no need to remember dozens of and  names. To see a list of available tools, simply run  with no arguments. Of course the  style are still available (via symlinks) if you prefer them.


 * Guaranteed support for $ROOT
 * For those of you using, you will not have to worry about whether a particular tool can handle it. Support for is required for all eselect modules.

Advantages for developers and package maintainers
Writing your tool as an eselect module rather than starting from 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 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 and  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 file with a structure that is quite similar to ebuilds.

Using eselect
eselect should be called as shown below.

eselect features consistently named actions among most of its modules. There are only two global options as of now;, which makes eselect’s output shorter (e.g., to use it as input for other programs); and , which controls coloured output. The following are standard action names – each module may provide a subset of these actions:


 * help
 * Print the module’s help screen.


 * usage
 * Print information on how to invoke the module’s actions.


 * version
 * Print the module’s version and other useful information.


 * list
 * Print a set of selectable options.


 * show
 * Print the currently active configuration(s).


 * set
 * Select one of the options offered by.


 * unset
 * Deselect the currently active option.


 * update
 * Like, but automatically selects an option rather than taking a parameter.


 * enable
 * Enable one of the module specific features.


 * disable
 * Disable one of the module specific features.


 * 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:

You can usually set items either by name or number.

This page was converted from and is kept in sync with the eselect User Guide by Ciaran McCreesh, Danny van Dyk, Ulrich Müller, and Shyam Mani. It is dual-licensed under or.