Reorganisation of the source tree

[ghc-hetmet.git] / includes / README

diff --git a/includes/README b/includes/README
new file mode 100644 (file)
index 0000000..aae99bf
--- /dev/null
+++ b/includes/README
@@ -0,0 +1,114 @@
+-----------------------------------------------------------------------------
+The External API to the GHC Runtime System.
+-----------------------------------------------------------------------------
+
+The header files in this directory form the external API for the
+runtime.  The header files are used in the following scenarios:
+
+  1. Included into the RTS source code itself.
+       In this case we include "Rts.h", which includes everything
+       else in the appropriate order.
+
+       Pretty much everything falls into this category.
+
+  2. Included into a .hc file generated by the compiler.
+       In this case we include Stg.h, which includes a
+       subset of the headers, in the appropriate order and
+       with the appropriate settings (e.g. global register variables
+       turned on).
+
+       Includes everything below Stg.h in the hierarchy (see below).
+
+  3. Included into external C source code.
+       The following headers are designed to be included into
+        external C  code (i.e. C code compiled using a GHC installation,
+        not part of GHC itself or the RTS):
+
+               HsFFI.h
+               RtsAPI.h
+               SchedAPI.h
+               RtsFlags.h
+               Linker.h
+
+       These interfaces are intended to be relatively stable.
+
+       Also Rts.h can be included to get hold of everything else, including
+       definitions of heap objects, info tables, the storage manager interface
+       and so on.  But be warned: none of this is guaranteed to remain stable
+       from one GHC release to the next.
+
+  4. Included into non-C source code, including Haskell (GHC itself)
+     and C-- code in the RTS.
+
+       The following headers are #included into non-C source, so
+       cannot contain any C code or declarations:
+               config.h
+               RtsConfig.h
+               Constants.h
+               DerivedConstants.h
+               ClosureTypes.h
+               StgFun.h
+               MachRegs.h
+               Liveness.h
+               StgLdvProf.h
+
+Here is a rough hierarchy of the header files by dependency.
+
+Rts.h
+  Stg.h
+    ghcconfig.h                /* configuration info derived by the configure script. */
+    RtsConfig.h                /* settings for Rts things (eg. eager vs. lazy BH) */
+    MachDeps.h         /* sizes of various basic types */
+    StgTypes.h         /* basic types specific to the virtual machine */
+    TailCalls.h                /* tail calls in .hc code */
+    StgDLL.h           /* stuff related to Windows DLLs */
+    MachRegs.h         /* global register assignments for this arch */
+    Regs.h             /* "registers" in the virtual machine */
+    StgProf.h          /* profiling gubbins */
+    StgMiscClosures.h  /* decls for closures & info tables in the RTS */
+    RtsExternal.h      /* decls for RTS things required by .hc code */
+      (RtsAPI.h)
+      (HsFFI.h)
+
+  RtsTypes.h           /* types used in the RTS */
+
+  Constants.h          /* build-time constants */
+  StgLdvProf.h
+  StgFun.h
+  Closures.h
+  Liveness.h           /* macros for constructing RET_DYN liveness masks */
+  ClosureMacros.h
+  ClosureTypes.h
+  InfoTables.h
+  TSO.h
+  Updates.h            /* macros for performing updates */
+  GranSim.h
+  Parallel.h
+  SMP.h
+  Block.h
+  StgTicky.h
+  Stable.h
+  Hooks.h
+  Signals.h
+  DNInvoke.h
+    Dotnet.h
+
+Cmm.h                  /* included into .cmm source only */
+  DerivedConstants.h   /* generated by mkDerivedConstants.c from other */
+                       /* .h files. */
+  (Constants.h)
+  (ClosureTypes.h)
+  (StgFun.h)
+  (MachRegs.h)
+  (Liveness.h)  
+  (Block.h)
+
+Bytecodes.h    /* Bytecode definitions for the interpreter */
+Linker.h       /* External API to the linker */
+RtsFlags.h     /* External API to the RTS runtime flags */
+SchedAPI.h     /* External API to the RTS scheduler */
+ieee-flpt.h    /* ToDo: needed? */
+
+RtsAPI.h       /* The top-level interface to the RTS (rts_evalIO(), etc.) */
+HsFFI.h                /* The external FFI api */
+