1 files changed, 114 insertions, 0 deletions
diff --git a/includes/README b/includes/README
new file mode 100644
index 0000000000..aae99bf20b
--- /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 */
+