[project @ 2004-11-11 16:03:51 by simonmar]

Add a more prominent description of what this library is all about.

diff --git a/ghc/lib/compat/Makefile b/ghc/lib/compat/Makefile
index fa35db7..62d1726 100644 (file)
--- a/ghc/lib/compat/Makefile
+++ b/ghc/lib/compat/Makefile
@@ -1,15 +1,3 @@
-# 
-# This library contains modules only available in versions of GHC
-# newer than the current one.  They are implemented as stubs that
-# #include the actual code from fptools/libraries.
-#
-# The idea is to ease the task of writing portable code in GHC and its
-# tools: the client can link with libghccompat.a and assume that all
-# the modules are available.  In this way we can add modules to the library
-# and start using them right away in GHC, as long as the new library modules
-# can be compiled using older versions of GHC.
-#
-
 TOP=../..
 include $(TOP)/mk/boilerplate.mk
 

diff --git a/ghc/lib/compat/README b/ghc/lib/compat/README
new file mode 100644 (file)
index 0000000..8d0697b
--- /dev/null
+++ b/ghc/lib/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.