Difference between revisions of "Configuration file"

From Liberty Eiffel Wiki
Jump to navigation Jump to search
m
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
  +
Most Liberty Eiffel tools need some kind of configuration which is stored in a unique file to prevent the user from having to use overly long command lines. This is named '''liberty.cfg''' on windows systems and '''liberty.se''' on unix-like systems.
[[Category:Smarteiffel]]
 
   
  +
In particular it contains
The configuration is used by most SmartEiffel tools. It groups in a unique file all the data which allow the user not too have over-long command lines ;-)
 
  +
* general settings like system type, number of processes to start during compilation
 
Can be found in this file, in particular:
 
 
* paths to find tools, environment variables, [[short]] templates...
 
* paths to find tools, environment variables, [[short]] templates...
 
* paths of the clusters that define all the classes available by default (the universe).
 
* paths of the clusters that define all the classes available by default (the universe).
  +
* '''se''' shortcuts for the available tools
  +
* C-compiler options for each c_mode
   
This tool is generated by [[install|the installation tool]] of SmartEiffel.
+
An initial version of this configuration is generated by [[install|the installation tool]] of Liberty Eiffel.
 
== Where is this file ==
 
 
Depending on the operating system, there are default values. In all cases, this default value can be overwritten using the <tt>SmartEiffel</tt> environment variable. <tt>SmartEiffel</tt> must contain the path of the configuration file. ''Elders'' who know SmallEiffel certainly still use <TT>$HOME/SmartEiffel/sys/system.se</TT>
 
 
Default values:
 
   
  +
== Where is this configuration file stored? ==
  +
It is possible to have several configuration files, which are treated by priority and more specific files can override the settings from the general ones. The lowest priority is attributed to system-wide files, while user-specific (e.g. <tt>~/.serc</tt>) and session-specific (the <tt>Liberty</tt> environment variable) get higher priority. In case a configuration location is a directory, all the entries of the directory are merged (or to be accurate: all entries are handled with priority defined via alphabetical sort of the names). All that because of some distributions like to add/remove files instead of grep'ing and sed'ing huge configuration file.
  +
Default configuration file locations:
 
{|
 
{|
 
|-
 
|-
 
| Windows and DOS:
 
| Windows and DOS:
| <TT>%USERPROFILE%\SE.CFG</TT> if the variable is defined, <TT>C:\SE.CFG</TT> otherwise
+
| '''<TT>%ALLUSERSPROFILE%\Liberty-Eiffel</TT>''', <TT>%USERPROFILE%\SE.CFG</TT>, <TT>%USERPROFILE%\LIBERTY.CFG</TT>, '''<TT>%USERPROFILE%\Liberty-Eiffel</TT>''' (lookup in this order)
 
|-
 
|-
 
| Unix and Cygwin:
 
| Unix and Cygwin:
  +
| <TT>/etc/serc</TT>, <TT>/etc/xdg/liberty-eiffel</TT>, '''<TT>/etc/liberty-eiffel</TT>''', <TT>/usr/local/etc/liberty-eiffel</TT>, '''<TT>~/.config/liberty-eiffel</TT>''', <TT>~/.serc</TT> <TT>~/.liberty-eiffel</TT> (look-up in this order, XDG_CONFIG_HOME is taken into account to adjust the paths)
| <TT>~/.serc</TT> or <TT>/etc/serc</TT> (look-up in this order)
 
|-
 
| Elate&nbsp;:
 
| <TT>/lang/eiffel/serc</TT>
 
 
|}
 
|}
  +
The suggested directories are '''bold'''.
   
The other operating systems don't have a default value, the <tt>SmartEiffel</tt> environment variable must be used. If you have such an operating system and you think there is a reasonnable default value, '''thanks to tell us'''.
+
The other operating systems don't have a default value, the <tt>Liberty</tt> environment variable must be used. If you have such an operating system and you think there is a reasonable default value, '''thanks for telling us'''.
 
'''Note:''' The configuration handling changes slightly in the upcoming version '''2.3'''. Instead of having only one file, one may have more than one, which are treated by priority. The lowest priority is attributed to system-wide files, while user-specific (e.g. <tt>~/.serc</tt>) and session-specific (the <tt>SmartEiffel</tt> environment variable) get higher priority. It goes even further since each "file" can now be a ''directory''. In that case all the entries of the directory are merged. All that because of some distributions like to add/remove files instead of grep'ing and sed'ing huge configuration files.
 
   
 
== File syntax ==
 
== File syntax ==
   
The file is written using a simple text format. It is split in sections that begin by a word between square brackets on a line. Each section is comprised of key-value pairs separated by a colon.
+
The file is written using a simple text format. It is split up into sections that each begin with a word between square brackets on a single line. Each section is comprised of key-value pairs separated by a colon.
   
 
Example:
 
Example:
   
 
[General]
 
[General]
bin: /home/cyril/SmartEiffel/bin/
+
bin: /home/cyril/Liberty/bin/
sys: /home/cyril/SmartEiffel/sys/
+
sys: /home/cyril/Liberty/sys/
short: /home/cyril/SmartEiffel/short/
+
short: /home/cyril/Liberty/short/
 
os: UNIX
 
os: UNIX
 
flavor: Linux
 
flavor: Linux
Line 48: Line 42:
 
=== The General section ===
 
=== The General section ===
   
This section is named <TT>[General]</TT>. There must be the following keys:
+
This section is named <TT>[General]</TT>. It must provide the following keys:
   
 
{|
 
{|
 
|-
 
|-
 
| width="10%" valign="top" | <TT>bin</TT>
 
| width="10%" valign="top" | <TT>bin</TT>
| the path to the SmartEiffel executables. This path is used in particular by the [[se]] tool (see below the Tools section) and [[compile]].
+
| the path to the compiler executables. This path is used in particular by the [[se]] tool (see below the Tools section) and [[compile]].
 
|-
 
|-
 
| valign="top" | <TT>sys</TT>
 
| valign="top" | <TT>sys</TT>
| the path to the SmartEiffel system files. This path is used by [[compile_to_c]] and [[compile_to_jvm]]. It contains all the basic files included by those compilers. They define the "basic bricks" of the generated Eiffel system.
+
| the path to the Liberty Eiffel system files. This path is used by [[compile_to_c]]. It contains all the basic files included by those compilers. They define the "basic bricks" of the generated Eiffel system.
 
|-
 
|-
 
| valign="top" | <TT>short</TT>
 
| valign="top" | <TT>short</TT>
Line 62: Line 56:
 
|-
 
|-
 
| valign="top" | <TT>os</TT>
 
| valign="top" | <TT>os</TT>
| the type of the operating system SmartEiffel is installed on. The recognized types are: UNIX, Windows, Cygwin, BeOS, Macintosh, Amiga, DOS, OS2, OpenVMS, Elate.
+
| the type of the operating system Liberty Eiffel is installed on. The recognized types are: UNIX, Windows, Cygwin, BeOS, Macintosh, Amiga, DOS, OS2, OpenVMS, Elate.
 
|-
 
|-
 
| valign="top" | <TT>flavor</TT>
 
| valign="top" | <TT>flavor</TT>
| allows a more accurate specification of the operating system type, useful for some plugins. For instance, if the <TT>os</TT> is UNIX, the <TT>flavor</TT> can be Solaris. There is no predefined list of values; plugins must tell which are the supported <TT>flavor</TT>s.
+
| allows a more accurate specification of the operating system type, useful for some plugins. For instance, if the <TT>os</TT> is UNIX, the <TT>flavor</TT> can be Linux. There is no predefined list of values; plugins must tell which are the supported <TT>flavor</TT>s.
 
|-
 
|-
 
| valign="top" | <TT>tag</TT>
 
| valign="top" | <TT>tag</TT>
| normally only used by the [[install|installation tool]] to define the version of the configuration file. There should be ascending compatibility between versions but '''currently, if the tag is not the one of the installation tool, no data is kept'''. This behavior is changed in the upcoming 2.3, to keep as much data as possible.
+
| normally only used by the [[install|installation tool]] to define the version of the configuration file. There should be ascending compatibility between versions but '''currently, if the tag is not the one of the installation tool, no data is kept'''. This behavior was changed in SmartEiffel 2.3, to keep as much data as possible.
   
The tag value is '''3''' for the 2.2 version of SmartEiffel and should be the same for the upcoming 2.3.
+
The tag value was '''3''' for SmartEiffel 2.2 and 2.3.
 
|-
 
|-
 
| valign="top" | <TT>jobs</TT>
 
| valign="top" | <TT>jobs</TT>
| if a tool has some tasks which may be done in parallel (e. g. calling the C compiler for generated C files) it creates at most the configured amount of processes
+
| if a tool has some tasks which may be done in parallel (e. g. calling the C compiler for generated C files) it creates at most the configured amount of processes. Performance-wise, it's likely best not to use hyperthreading, especially when compiling big systems. An example: if your system reports a quadcore processor, it might actually be equipped with a dualcore with hyperthreading activated. In that case it's likely best to set <TT>jobs</TT> to 2 and not to 4.
 
|}
 
|}
   
=== Environment ===
+
=== The Environment section ===
   
The environment allows to define ''environment variables'' specific to SmartEiffel. In particular those variables are available in the remaining of the configuration file, in the <tt>loadpath.se</tt> files, ACE files and some command line arguments.
+
The environment section allows you to define ''environment variables'' specific to Liberty Eiffel. In particular these variables are available in the remaining of the configuration file, in the <tt>loadpath.se</tt> files, ACE files and some command line arguments.
   
 
The [[install|installation tool]] installs the following default variables:
 
The [[install|installation tool]] installs the following default variables:
   
 
[Environment]
 
[Environment]
path_tutorial: /home/cyril/SmartEiffel/tutorial/
+
path_liberty: /home/cyril/Liberty/
path_tools: /home/cyril/SmartEiffel/tools/
+
path_liberty_core: /home/cyril/Liberty/src/lib/
path_lib: /home/cyril/SmartEiffel/lib/
+
path_liberty_extra: /home/cyril/Liberty/src/wrappers/
  +
path_smarteiffel: /home/cyril/Liberty/src/smarteiffel/
  +
path_tools: /home/cyril/Liberty/src/tools/
  +
path_tutorial: /home/cyril/Liberty/tutorial/
   
 
Note that anyone can add their own variables.
 
Note that anyone can add their own variables.
Line 91: Line 88:
 
=== The universe ===
 
=== The universe ===
   
The universe is the set of all the known clusters. It is defined in the <TT>[Loadpath]</TT> section.
+
The universe is the set of all known clusters. It is defined in the <TT>[Loadpath]</TT> section.
   
 
The [[install|installation tool]] installs the following default universe:
 
The [[install|installation tool]] installs the following default universe:
   
 
[Loadpath]
 
[Loadpath]
lib: ${path_lib}loadpath.se
+
liberty_core: ${path_liberty_core}loadpath.se
  +
liberty_extra: ${path_liberty_extra}loadpath.se
  +
test: ${path_liberty}test/loadpath.se
  +
smarteiffel: ${path_smarteiffel}loadpath.se
 
tools: ${path_tools}loadpath.se
 
tools: ${path_tools}loadpath.se
 
tutorial: ${path_tutorial}loadpath.se
 
tutorial: ${path_tutorial}loadpath.se
   
Note that anyone can add their own tools to the libraries they most use.
+
Note that anyone can add their own tools to the libraries they use most.
   
'''Caveat''': the universe is ''not'' used by the tools if an ACE file is given. In this case, this latter file must describe the whole universe. On the other hand it is very simple to do so since just adding a single line or two to your ACE file will produce the desired effect:
+
'''Caveat''': the universe is ''not'' used by the tools if an ACE file is given. In this case, the ACE file must describe the whole universe. On the other hand it is very simple to do so since just adding a single line or two to your ACE file will produce the desired effect:
   
 
cluster
 
cluster
standard: "${path_lib}loadpath.se"
+
standard: "${path_liberty_core}loadpath.se"
   
 
=== Tools ===
 
=== Tools ===
   
All the tools used by the [[se]] command are set here. Those tools must be in the directory pointed by the <tt>bin</tt> key of the <tt>[General]</tt> section. The key is used as first argument of [[se]].
+
All tools used by the [[se]] command are set here. These tools must be in the directory pointed to by the <tt>bin</tt> key of the <tt>[General]</tt> section. The key is used as first argument of [[se]].
   
 
The [[install|installation tool]] installs the following default commands:
 
The [[install|installation tool]] installs the following default commands:
   
 
[Tools]
 
[Tools]
  +
ace_check: ace_check
c: compile
 
 
c2c: compile_to_c
 
c2c: compile_to_c
  +
c: compile
  +
class_check: class_check
 
clean: clean
 
clean: clean
  +
doc: eiffeldoc
java: compile_to_jvm
 
  +
find: finder
  +
make: se_make.sh
  +
mock: mocker
 
pretty: pretty
 
pretty: pretty
 
short: short
 
short: short
  +
test: eiffeltest
find: finder
 
  +
test_ng: eiffeltest_ng
ace_check: ace_check
 
  +
test_server: eiffeltest_server
class_check: class_check
 
  +
wrap: wrappers_generator
javap: print_jvm_class
 
doc: eiffeldoc
 
 
x_int: extract_internals
 
x_int: extract_internals
test: eiffeltest
 
   
Note that anyone can add their own tools, as long as the executable is in the directory pointed by the <tt>bin</tt> key of the <tt>[General]</tt> section and an entry is added to the <tt>[Tools]</tt> section.
+
Note that anyone can add their own tools, as long as the executable is in the directory pointed to by the <tt>bin</tt> key of the <tt>[General]</tt> section and an entry is added to the <tt>[Tools]</tt> section.
   
 
=== C modes ===
 
=== C modes ===
   
Those modes are used by the C back-end: used C compiler, options...
+
These modes are used by the C back-end: used C compiler, options... E. g.
  +
[boost]
  +
c_compiler_type: gcc
  +
c_compiler_path: gcc
  +
c_compiler_options: -pipe -O2 -fno-gcse
  +
c_linker_path: gcc
  +
c_linker_options: -Xlinker -no-as-needed
  +
cpp_compiler_type: g++
  +
cpp_compiler_path: g++
  +
cpp_compiler_options: -pipe -O2 -fno-gcse
  +
cpp_linker_path: gcc
  +
cpp_linker_options: -Xlinker -no-as-needed
  +
   
There are by default some C modes that are automatically associated to the Eiffel compilation levels (<TT>-boost</TT>, <TT>-require_check</TT>, etc.) The C mode can also be explicitely set in the command line of [[compile_to_c|compile_to_c]] or [[compile|compile]] thanks to the <TT>-c_mode</TT> option.
+
By default some C modes are automatically associated to the Eiffel compilation levels (<TT>-boost</TT>, <TT>-require_check</TT>, etc.). The C mode can also be explicitely set in the command line of [[compile_to_c|compile_to_c]] or [[compile|compile]] thanks to the <TT>-c_mode</TT> option.
   
The [[install|installation tool]] installs the following default C modes: <TT>boost</TT>, <TT>no_check</TT>, <TT>require_check</TT>, <TT>ensure_check</TT>, <TT>invariant_check</TT>, <TT>loop_check</TT>, <TT>all_check</TT>, <TT>debug_check</TT> and <TT>release</TT>. Only the last one must be explicitely set; it is usually used to finalize a program (<TT>se c -boost -c_mode release ...</TT>)
+
The following C modes are default for a standard installation: <TT>boost</TT>, <TT>no_check</TT>, <TT>require_check</TT>, <TT>ensure_check</TT>, <TT>invariant_check</TT>, <TT>loop_check</TT>, <TT>all_check</TT>, <TT>debug_check</TT> and <TT>release</TT>. Only the last one must be explicitely set; it is usually used to finalize a program (<TT>se c -boost -c_mode release ...</TT>)
   
Usually the default C modes depend on the chosen C compiler. All those modes can be modified during the installation, but the default values come from a template file. There is one such file per supported C compiler (in the directory <TT>SmartEiffel/install</TT>, the <TT>*.rc</TT> files).
+
Usually the default C modes depend on the chosen C compiler and needs adaption if GCC is not used.

Revision as of 08:31, 25 September 2018

Most Liberty Eiffel tools need some kind of configuration which is stored in a unique file to prevent the user from having to use overly long command lines. This is named liberty.cfg on windows systems and liberty.se on unix-like systems.

In particular it contains

  • general settings like system type, number of processes to start during compilation
  • paths to find tools, environment variables, short templates...
  • paths of the clusters that define all the classes available by default (the universe).
  • se shortcuts for the available tools
  • C-compiler options for each c_mode

An initial version of this configuration is generated by the installation tool of Liberty Eiffel.

Where is this configuration file stored?

It is possible to have several configuration files, which are treated by priority and more specific files can override the settings from the general ones. The lowest priority is attributed to system-wide files, while user-specific (e.g. ~/.serc) and session-specific (the Liberty environment variable) get higher priority. In case a configuration location is a directory, all the entries of the directory are merged (or to be accurate: all entries are handled with priority defined via alphabetical sort of the names). All that because of some distributions like to add/remove files instead of grep'ing and sed'ing huge configuration file. Default configuration file locations:

Windows and DOS: %ALLUSERSPROFILE%\Liberty-Eiffel, %USERPROFILE%\SE.CFG, %USERPROFILE%\LIBERTY.CFG, %USERPROFILE%\Liberty-Eiffel (lookup in this order)
Unix and Cygwin: /etc/serc, /etc/xdg/liberty-eiffel, /etc/liberty-eiffel, /usr/local/etc/liberty-eiffel, ~/.config/liberty-eiffel, ~/.serc ~/.liberty-eiffel (look-up in this order, XDG_CONFIG_HOME is taken into account to adjust the paths)

The suggested directories are bold.

The other operating systems don't have a default value, the Liberty environment variable must be used. If you have such an operating system and you think there is a reasonable default value, thanks for telling us.

File syntax

The file is written using a simple text format. It is split up into sections that each begin with a word between square brackets on a single line. Each section is comprised of key-value pairs separated by a colon.

Example:

[General]
bin: /home/cyril/Liberty/bin/
sys: /home/cyril/Liberty/sys/
short: /home/cyril/Liberty/short/
os: UNIX
flavor: Linux
tag: 3
jobs: 4

The General section

This section is named [General]. It must provide the following keys:

bin the path to the compiler executables. This path is used in particular by the se tool (see below the Tools section) and compile.
sys the path to the Liberty Eiffel system files. This path is used by compile_to_c. It contains all the basic files included by those compilers. They define the "basic bricks" of the generated Eiffel system.
short the path to the short templates (modes -html, -tex, etc.)
os the type of the operating system Liberty Eiffel is installed on. The recognized types are: UNIX, Windows, Cygwin, BeOS, Macintosh, Amiga, DOS, OS2, OpenVMS, Elate.
flavor allows a more accurate specification of the operating system type, useful for some plugins. For instance, if the os is UNIX, the flavor can be Linux. There is no predefined list of values; plugins must tell which are the supported flavors.
tag normally only used by the installation tool to define the version of the configuration file. There should be ascending compatibility between versions but currently, if the tag is not the one of the installation tool, no data is kept. This behavior was changed in SmartEiffel 2.3, to keep as much data as possible.

The tag value was 3 for SmartEiffel 2.2 and 2.3.

jobs if a tool has some tasks which may be done in parallel (e. g. calling the C compiler for generated C files) it creates at most the configured amount of processes. Performance-wise, it's likely best not to use hyperthreading, especially when compiling big systems. An example: if your system reports a quadcore processor, it might actually be equipped with a dualcore with hyperthreading activated. In that case it's likely best to set jobs to 2 and not to 4.

The Environment section

The environment section allows you to define environment variables specific to Liberty Eiffel. In particular these variables are available in the remaining of the configuration file, in the loadpath.se files, ACE files and some command line arguments.

The installation tool installs the following default variables:

[Environment]
path_liberty: /home/cyril/Liberty/
path_liberty_core: /home/cyril/Liberty/src/lib/
path_liberty_extra: /home/cyril/Liberty/src/wrappers/
path_smarteiffel: /home/cyril/Liberty/src/smarteiffel/
path_tools: /home/cyril/Liberty/src/tools/
path_tutorial: /home/cyril/Liberty/tutorial/

Note that anyone can add their own variables.

The universe

The universe is the set of all known clusters. It is defined in the [Loadpath] section.

The installation tool installs the following default universe:

[Loadpath]
liberty_core: ${path_liberty_core}loadpath.se
liberty_extra: ${path_liberty_extra}loadpath.se
test: ${path_liberty}test/loadpath.se
smarteiffel: ${path_smarteiffel}loadpath.se
tools: ${path_tools}loadpath.se
tutorial: ${path_tutorial}loadpath.se

Note that anyone can add their own tools to the libraries they use most.

Caveat: the universe is not used by the tools if an ACE file is given. In this case, the ACE file must describe the whole universe. On the other hand it is very simple to do so since just adding a single line or two to your ACE file will produce the desired effect:

cluster
   standard: "${path_liberty_core}loadpath.se"

Tools

All tools used by the se command are set here. These tools must be in the directory pointed to by the bin key of the [General] section. The key is used as first argument of se.

The installation tool installs the following default commands:

[Tools]
ace_check: ace_check
c2c: compile_to_c
c: compile
class_check: class_check
clean: clean
doc: eiffeldoc
find: finder
make: se_make.sh
mock: mocker
pretty: pretty
short: short
test: eiffeltest
test_ng: eiffeltest_ng
test_server: eiffeltest_server
wrap: wrappers_generator
x_int: extract_internals

Note that anyone can add their own tools, as long as the executable is in the directory pointed to by the bin key of the [General] section and an entry is added to the [Tools] section.

C modes

These modes are used by the C back-end: used C compiler, options... E. g.

[boost]
c_compiler_type: gcc
c_compiler_path: gcc
c_compiler_options: -pipe -O2 -fno-gcse
c_linker_path: gcc
c_linker_options: -Xlinker -no-as-needed
cpp_compiler_type: g++
cpp_compiler_path: g++
cpp_compiler_options: -pipe -O2 -fno-gcse
cpp_linker_path: gcc
cpp_linker_options: -Xlinker -no-as-needed


By default some C modes are automatically associated to the Eiffel compilation levels (-boost, -require_check, etc.). The C mode can also be explicitely set in the command line of compile_to_c or compile thanks to the -c_mode option.

The following C modes are default for a standard installation: boost, no_check, require_check, ensure_check, invariant_check, loop_check, all_check, debug_check and release. Only the last one must be explicitely set; it is usually used to finalize a program (se c -boost -c_mode release ...)

Usually the default C modes depend on the chosen C compiler and needs adaption if GCC is not used.