Project:Eselect/Developer guide

About eselect
eselect is a framework for simplifying and introducing consistency to the various and  tools. It is an option for developers who don’t like reinventing the wheel, not a mandatory tool.

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 simplified version of the module. It has three actions,, , and , plus the standard , , and actions, and is installed to.

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 and  variables globally which are used by  and some of the default action handlers, and a series of functions.

Unlike ebuilds, the function names are not fixed. Any function whose name starts with is considered to be an action implementation. It is conventional to have a function for every  function that gives a short description of the function – this is used for, for example. The and  functions are optional.

All eselect modules are required to support the variable. For prefix support, variables and  are also defined and have the same meaning as in ebuilds.

All modules contributed to eselect should have a header indicating copyright. This must be an exact copy of the header in the above example (except for the years, of course).

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.


 * help
 * Display a help message. Automatic.


 * usage
 * Display a usage message. Automatic.


 * version
 * Display the current version. Automatic.


 * list
 * Used to display all available providers of a symlink, or all available modules.


 * show
 * Used to display the current provider of a symlink, or the currently installed module, or the current status.


 * set
 * Used to set a new provider or a symlink.


 * unset
 * Used to unset the current provider, or to remove a symlink.


 * update
 * Used to automatically select a new provider for a symlink (as opposed to, which generally takes a parameter manually selecting the provider) or to gather system information that is vital to further actions.


 * enable
 * Used to enable an optional feature.


 * disable
 * Used to disable an optional feature.


 * scan
 * Read information off the current filesystem.

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
 * Test Functions
 * Path-Manipulation Functions
 * Manipulation Functions
 * Configuration Functions
 * Multilib Functions
 * Package-Manager Functions

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

General Utility Functions
These are implemented in.


 * die
 * The 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 . If the  is not provided, a stacktrace will be displayed – this should never happen because of user input error, only abnormal conditions.


 * check_do
 * The 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,  is called. Again, this is mostly internal.


 * do_action
 * The 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.


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


 * sed
 * The function is a wrapper around GNU.

Output Utility Functions
These are implemented in.

 write_error_msg  The function displays an error message in the standard format. It is similar to. write_warning_msg  The function displays a warning message in the standard format. It is similar to. The write_list_ family of functions  To display a list, the family of functions should be used. If is passed as the first argument to these functions, plain highlighting is used. write_list_start  Lists should always start with a header, which can be displayed using. write_numbered_list_entry  To display a numbered list, the 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). write_kv_list_entry  To display a keyword/value list, the function should be used. The first parameter is the key, the second the value. write_numbered_list  The function is a wrapper around  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. The option can be used to specify a negative report message that is output for an empty list. highlight <dd> The 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:

<dt>highlight_warning <dd> The function is like, but for warnings. It displays the text in question in red. <dt>highlight_marker <dd> To mark a list entry as active/selected, the function should be used. First argument is the list entry. The function places a highlighted star (or its second argument instead, if set) behind the entry. A typical invocation might look like:

<dt>is_output_mode <dd> The function returns true if and only if its parameter is equal to eselect’s output mode. Currently, only the default and output modes are defined, the latter corresponding to the  option. (This function appeared in eselect-1.2.6.) <dt>space <dd> The utility function takes a single integer parameter. It displays that many space characters. </dl>

Test Functions
These are implemented in.


 * has
 * The utility function is like Portage’s . It returns true if and only if the first parameter is equal to any of the remaining parameters.


 * is_function
 * The 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.


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

Path-Manipulation Functions
These are implemented in.


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


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


 * canonicalise
 * The function is a wrapper to either GNU  or.


 * relative_name
 * The function converts a path name (passed as its first argument) to be relative to a directory (second argument). This can be used to generate a relative symlink from absolute paths. (This function appeared in eselect-1.2.4.)

Manipulation Functions
These are implemented in.

<dl> <dt>svn_date_to_version <dd> If your module is kept in a CVS or subversion repository, then the 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:

Then turn on SVN keyword expansion for the module:

</dl>

Configuration Functions
These are implemented in.


 * store_config
 * The 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  is called. The function is invoked as.


 * load_config
 * The function loads a stored value from the module’s configuration file. It is invoked as  and prints the associated value.


 * append_config
 * The function adds an item to an already stored value in the module’s configuration file. It uses  /  internally and should be invoked as . Note that the item will not be appended if it occurs in the key’s value already.

Multilib Functions
These are implemented in.


 * list_libdirs
 * The function returns a set of valid libdirs for the used architecture. By default it uses  to obtain all the valid libdirs. If this fails due to a missing or broken file, this function uses  to determine the architecture.

Package-Manager Functions
These are implemented in.


 * arch
 * The function returns the correct value of the  variable for the current system. If the package manager cannot provide this information,  falls back to a lookup-table based on the  and  bash variables.


 * envvar
 * The function retrieves the contents of a configuration-environment variable for a given package. The syntax is.


 * best_version
 * The function returns the highest available version for a given package dep atom.


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


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


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

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