[commit: ghc] master: comment about why this program exists (a30dbc6)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/a30dbc64e21c09008e8500f6ff41d76a52e57d46/ghc

>---------------------------------------------------------------

commit a30dbc64e21c09008e8500f6ff41d76a52e57d46
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Fri Dec 13 10:32:29 2013 +0000

    comment about why this program exists


>---------------------------------------------------------------

a30dbc64e21c09008e8500f6ff41d76a52e57d46
 utils/deriveConstants/DeriveConstants.hs | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/utils/deriveConstants/DeriveConstants.hs b/utils/deriveConstants/DeriveConstants.hs
index c793e84..ccf9028 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)