comment about why this program exists

1 files changed, 16 insertions, 1 deletions

diff --git a/utils/deriveConstants/DeriveConstants.hs b/utils/deriveConstants/DeriveConstants.hs
index c793e84e85..ccf9028904 100644
--- a/utils/deriveConstants/DeriveConstants.hs
+++ b/utils/deriveConstants/DeriveConstants.hs
@@ -1,4 +1,3 @@
-
 {- ------------------------------------------------------------------------
 
 (c) The GHC Team, 1992-2012
@@ -8,6 +7,22 @@ declarations in the header files (primarily struct field offsets)
 and generates various files, such as a header file that can be #included
 into non-C source containing this information.
 
+We want to get information about code generated by the C compiler,
+such as the sizes of types, and offsets of struct fields.  We need
+this because the layout of certain runtime objects is defined in C
+headers (e.g. includes/rts/storage/Closures.h), but we need access to
+the layout of these structures from a Haskell program (GHC).
+
+One way to do this is to compile and run a C program that includes the
+header files and prints out the sizes and offsets. However, when we
+are cross-compiling, we can't run a C program compiled for the target
+platform.
+
+So, this program works as follows: we generate a C program that when
+compiled to an object file, has the information we need encoded as
+symbol sizes.  This means that we can extract the information without
+needing to run the program, by inspecting the object file using 'nm'.
+
 ------------------------------------------------------------------------ -}
 
 import Control.Monad (when, unless)