compat/README

   1 GHC compatibiliy library: libghccompat.a
   2 ----------------------------------------
   3
   4 This library contains interfaces that are available in recent versions
   5 of GHC, but may or may not be available in older versions.  The idea
   6 is to provide an abstraction layer and reduce the amount of #ifdefery
   7 and code duplication in GHC and its tools.  Furthermore, we can add
   8 modules to the main library and start using them right away in GHC, by
   9 adding a stub to this compat library.
  10
  11 There are two types of modules in here:
  12
  13 (a) a module with the same name as a module in the main library
  14     (eg. Distribution.Package).  If the module is available in
  15     the main library, then we don't include it in  libghccompat.
  16     Otherwise, we have a stub module here that just #includes
  17     the source from the real location under libraries/.  Go look
  18     at Distribution/Package.hs for example.
  19
  20 (b) a module that doesn't exist in another library.  For example,
  21     Compat.RawSystem.  These modules are used to provide functions
  22     that are available in newer versions of the main libraries.
  23
  24 BIG NOTE: when building stage 2 of GHC, libghccompat is not used,
  25 because we would have to build another version of it.  Instead, we
  26 just use the appropriate libraries directly.  For (a)-type modules,
  27 just import the module directly.  For (b)-type modules, a single
  28 #ifdef will be required to choose between the Compat version and
  29 the real version.
  30
  31 In stage 1 of GHC, and tools (eg. ghc-pkg, runghc), libghccompat.a
  32 is linked in, so all its libraries will be accessible.