Configuration of Epeios-related software components

This are general configuration instructions common to all Epeios software. Configuration instructions specific to each software may be available in the Configuration section of each software's main page.
Some parts of this page will only apply to software with command-line interface (CLI). Also some other parts will only apply to frontend related components.

Language

The default language is English. You can switch to French by changing the <Language>…<Language> entry in the Parameters section of the configuration file (<component name>.xcfg) from en to fr. This two are currently the only available languages, but, by completing the locale file (<component name>.xlcl), and modifying the configuration file accordingly, you can switch to whatever language you want.

It's also possible to change punctually the language, without having to modify the configuration file, as described below.

Frontends

Parameters

This section concerns XDHTML frontends, that is, components with a name ending with xdh (before the extension).
<Parameters>
 <Preset Type="PRESET_TYPE" Handling="HANDLING">PRESET_VALUE</Preset>
 <Backend Type="BACKEND_TYPE">PARAMETERS</Backend>
</Parameters>
  • PRESET_TYPE : one of :
    • None : no preset; PRESET_VALUE is not used,
    • Setup : use the setup which id is given by PRESET_VALUE,
    • Project : use the project which file name is given by PRESET_VALUE,
  • HANDLING : one of :
    • Display or missing: the prolog page is displayed, with the given project selected,
    • Load : load the given project (prolog page is skipped),
    • Run : run the given project (both prolog and login pages are skipped),
    • Login : load the given preset (prolog page is skipped), and displays only the login form on the login page.
  • BACKEND_TYPE : one of :
    • None : for no backend ; PARAMETERS is ignored,
    • Predefined : for a predefined backend, as defined in the Definitions/Backends section ; PARAMETERS is the id of the chosen backend,
    • the plugins defined in the FrontendPlugins section, to which PARAMETERS is given as parameters.
The Preset entry applies only to the frontends with desktop GUI, but the Backend entry is also used for the Web (multi-user) and CLI frontends.

Setups

<Setups>
 <SetupHandling="HANDLING"></Setup>
</Setups>

HANDLING: one of: In progress…

The Setups/Setup entries are for all type of software, but the Setup's Handling attribute is dedicated to the frontends used with desktop GUIs.

Command-line arguments

All command-line components from the Epeios project can have their command-line arguments be configured.

All this components read their parameters from an internal registry. This registry is filled with the content of the configuration file (and potential project file ; see below), but also with values depending from the command-line arguments. To set a value for a parameter, you can use this special option :

--#<path>=<value>

where <path>, which is automatically prefixed with Parameters/, is the path of the entry in the registry, and <value> its value.

For example, there is a Parameters/Language entry in the registry for the language to use, and which value is generally set in the configuration file. To switch temporarily to another language without having to modify the configuration file, simply add --#Language=<language> option, where <Language> is the language you want to switch to (given that the translations for this language exist in the locale file ; see above), when calling the component.

In the configuration file, you will find an Arguments section. Each Argument entry specifies a shortcut for either the command argument, an option, a flag or an argument which is neither of previous type of argument. The Layouts section contains a Layout entry for each command to make the link between an argument and the parameter it represents following its position.

The Locale section contains the translations of the label and descriptions of the arguments, and is used for the generation of the help page of the component.

Project files

Some command-line components handle project files; in such a case, this is indicated in the help page (displayed with the --help command) of the component. Such a project file has, by convention, a .xprj extension, and following structure :

<?xml version="1.0" encoding="utf-8"?>
<Projects>
 <Project target="<component name>">
  ...
 </Project>
</Projects>

In fact, all Epeios-related software components can handle project files, even when not mentioned in the help page. You only have to add a --#Project=<project file name> option when launching the component, or set the Parameters/Project entry in the configuration file to the project filename.

You can also define some projects in the Definitions section of the configuration file, and then use one of them by adding a --#Project[Type=“Predefined”]=<project id> option when launching the component, or set the Parameters/Project[Type=“Predefined”] entry in the configuration file to the project id.

You can put in a project file the same entries as in the configuration file (although some entries don't make sense, for example the Parameters/Project entry mentioned above). A project file can be seen as a remote configuration file. For example, there is mentioned above that you can change the language of a component by changing the Parameters/Language entry in the configuration file. But you can also put this entry in a project file, without modifying the configuration file, so that the language of the component only changes when launched with this project file.

Entries in a project file supersede same entries in configuration file.

Setups

Setups (with final s) is a section containing one or more Setup (without final s) sections, each with its own id attribute value. Each Setup contains a set of parameters, which, when owned by the selected setup, are entries that are considered as child of the Parameters section of the configuration file.

To specify which setup to use, put its id as the value of the Setup attribute of the Parameters tag. This can be done directly in the configuration file, or through an option to type as command-line argument if defined in the Arguments section (this should be indicated in the help page – command --help – of the tool), or, as explained above, with the --#@Setup=<id> option as a command-line argument, where <id> is the setup's id.

Alternatively, you can add a Default attribute to the Setups tag with the value of the id of the default setup. This value is superseded by the value of the above described Setup attribute of the Parameters tag.

A project file can contain its own Setups section.

Entries of a selected setup supersede same entries in a project file and in the configuration file.

'Debug' section

This is a section defined under the Parameters section which deals with various debug features

'DumpRegistries' entry

This entry is usually given as a command-line argument (--#Debug/DumpRegistries=<value>).

If <value> is empty, the content of all the registries is displayed.

You can also specify which registry content to display by giving as <value> one or several of the following characters:

  • m for the main registry; filled with the content of the configuration file,
  • l for the lasting registry; filled with application data, and set by application,
  • p for the project registry; filled by project file,
  • s for the setup registry; filled with setup content, when one is specified,
  • a for the arguments registry; filled with the content of the command-line arguments,
  • r for the runtime registry; set by the application, but lost once the application is terminated.

For example --#Debug/DumpRegistries=am displays the content of the argument registry and the main registry.

'DumpLocales' entry

This entry is usually given as a command-line argument (--#Debug/DumpLocales=<value>).

If <value> is empty, the content of all the locales is displayed.

You can also specify which locale content to display by giving as <value> one or several of the following characters :

  • m for the main locale.
  • c for the configuration locale,
  • p for the project locale,

For example --#Debug/DumpLocales=mp displays the content of the main locale and the project locale.

The XML preprocessor

Configuration/locale/project files go through the Epeios XML preprocessor, which is described on the XPPq dedicated page, before handled by the component. So, all the Epeios XML preprocessor directives can be used in this files. This allows in particular to split each of them in several sub-files.