Library Structure

Guideline to libraries structure in UHC.

The UHC libraries structure closely follows the GHC libraries structure. However since GHC supports more extensions than UHC there might be differences.

UHC libraries modules:

UHC libraries have 3 types of modules:

• UHC specific - written from scratch for UHC
• GCH modified - copied from GHC and modified according to UHC needs, but keeping the original interface.
• GHC unmodified - plain copy of the corresponding GHC variant. Which files are copied can be seen by inspected the content of $UHC$/ehclib/files2.mk, where $UHC$ is the root directory for UHC distribution.

The reference source code for the GHC library is ghc-6.10.1.20090106.

Adding modules to a library

New modules are added to a library by following the steps:

1. If the new module (or its equivalent) already exists in GHC libraries we try to import it from there. If everything works fine, i.e. it compiles and the functions produce the expected results, then we're done. Go to testing phase. Note that if the import works directly there is no need to actually copy the module files; we only modify the $UHC$/ehclib/files2.mk? by adding the corresponding entries.
2. If the direct import doesn't work then we physically copy the module to the library structure, following the original GHC structure. Next, the module is modified so it will work in the UHC context (don't forget to document the changes).
3. If it is a completely new module which doesn't exists in GHC, we add it in the most appropriate place.
4. [Test Phase] Add tests? to verify the new module.

During modifications we may encounter a situation where we have to use a function f, already defined in another UHC specific module, say UHC.M, but which is not exported. The guideline for this is:

1. Modify UHC.M interface by exporting the function f.
2. If the above action creates a cycle dependency then abstract the function(s) we need (and only them) into a separate module and import this new module into UHC.M, as well as where we it is needed.
3. Never modify the interface of a module which was only copied-modified from GHC. If this is the case then it's a good indication that the module should be made UHC specific.

-- AtzeDijkstra - 25 Feb 2010