Reorganisation of the source tree

[ghc-hetmet.git] / compat / README

diff --git a/compat/README b/compat/README
new file mode 100644 (file)
index 0000000..8d0697b
--- /dev/null
+++ b/compat/README
@@ -0,0 +1,32 @@
+GHC compatibiliy library: libghccompat.a
+----------------------------------------
+
+This library contains interfaces that are available in recent versions
+of GHC, but may or may not be available in older versions.  The idea
+is to provide an abstraction layer and reduce the amount of #ifdefery
+and code duplication in GHC and its tools.  Furthermore, we can add
+modules to the main library and start using them right away in GHC, by
+adding a stub to this compat library.
+
+There are two types of modules in here:
+
+(a) a module with the same name as a module in the main library
+    (eg. Distribution.Package).  If the module is available in
+    the main library, then we don't include it in  libghccompat.
+    Otherwise, we have a stub module here that just #includes
+    the source from the real location under libraries/.  Go look
+    at Distribution/Package.hs for example.
+
+(b) a module that doesn't exist in another library.  For example,
+    Compat.RawSystem.  These modules are used to provide functions
+    that are available in newer versions of the main libraries.
+
+BIG NOTE: when building stage 2 of GHC, libghccompat is not used,
+because we would have to build another version of it.  Instead, we
+just use the appropriate libraries directly.  For (a)-type modules,
+just import the module directly.  For (b)-type modules, a single
+#ifdef will be required to choose between the Compat version and
+the real version.
+
+In stage 1 of GHC, and tools (eg. ghc-pkg, runghc), libghccompat.a
+is linked in, so all its libraries will be accessible.