The class loading algorithm
How must the source files be named?
The algorithm used by Liberty to look for an Eiffel source file is the following:
- Lower case filenames - Liberty looks all along the loading path (see below) using the class name in lower case as prefix. If needed, the Eiffel suffix (".e") is added automatically. Liberty only looks for suffixed files on the disk. Only the first file encountered according to the order of the path is taken in account. An Eiffel file is always supposed to have the same name as the inside class definition.
- Upper case filenames - When the previous step did not find the required Eiffel class file, Liberty looks along the loading path (see below) for a file bearing the class name upper in upper case letters. If needed, the Eiffel suffix ".e" is added automatically. One must note that the overhead to find an upper case file name is not negligible at all and that a lower case file name may hide some upper case name.
How is the loading path built?
As described above, Liberty looks for classes in
.e files. But where should those files be situated? The answer is, in the loading path. The thing is, how is the loading path built, what are the default values, and how can it be changed?
Liberty builds a "universe" where it looks for all the classes. This "universe" is a tree of clusters. The root of the tree is the universe. This universe is either made of clusters and
loadpath.se files provided by:
- either the ACE file
- or a combination of the following:
- the command line (
- the current directory (a
loadpath.sefile in the current directory if it exists, the cluster represented by the current directory otherwise)
- the configuration file
- the command line (
loadpath.se file is a node of the tree. It contains other nodes (referenced
loadpath.se files), and clusters (directories). Note that all the clusters in a
loadpath.se file are direct children of the node. It means that, even if directories are arborescent this is not reflected in Liberty's universe.
To look for a supplier class, Liberty starts from its client. It tries to look for the "closest" class with the good name. It allows one to have many classes with the same name in the system. The algorithm is the following:
- try to look for a class with the good name in a sub-cluster of the client. The less deep, the better.
- try again starting from the parent cluster of the client.
- and so on, until the universe (the tree root) is reached.
If there is no client (e.g. a class given on the command line) the universe is searched and the class nearest to the root is selected.
If more than one class have the smallest distance, the compiler will bail because it cannot decide which to use. In the future, an extension to ACE files will allow someone to provide custom distances (a "distance" is the amount of depth to add from a cluster to a child; it defaults to 1)
loadpath.se file represents a node with two children: the cluster in the directory of the
loadpath.se file, and the cluster in the directory named "internal" in the former directory. Both have a distance equal to one, meaning that if there are two classes named
FOO in both
internal/ then the compiler will emit an error.
The tree will be the following:
+ <Universe> + "/my/loadpath.se" | + /my/ | + /my/internal/ + . . . |
Those files contain directories (clusters: the leaves of the "universe" tree) and references to other
loadpath.se files (nodes of the "universe" tree).
Those path names may be written using - either a POSIX notation - or your local system notation
Note that for a library to be portable, you should prefer the POSIX notation.
Here are the gory details on how the "universe" tree is managed:
The tree itself is a bunch of classes situated in the
smarteiffel/tools/ace cluster. It is a Composite which abstract class is
CLASSES; most of the parent-children handling is done by concrete features in the
* .--- CLASSES <--. | ^ | children parent | | | `--> CLUSTERS ---' 0-1 ^ | +----------+-------------+ | | | ACE --> UNIVERSE LOADPATH CLASSES_TREE --> CLUSTER (singleton)
LOADPATHis a node of the tree. It references a
UNIVERSEis a singleton object held by
CLASSES_TREEis a leaf of the tree. It is a facade to the old
CLASSES_TREE_FACTORYis used to create a node or a leaf depending on whether the given path is a directory or a plain file. It creates
CLUSTERholds references to the known and loaded classes in that cluster
ACEstays the Universe facade for the remaining of the Liberty system and dispatches request to the
CLASSEStree (via the