ghc/docs/comm/the-beast/prelude.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
   5     <title>The GHC Commentary - Primitives and the Prelude</title>
   6   </head>
   7
   8   <body BGCOLOR="FFFFFF">
   9     <h1>The GHC Commentary - Primitives and the Prelude</h1>
  10     <p>
  11       Most of what the compiler has to have wired in about primitives and
  12       prelude definitions is in
  13       <a
  14       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/"><code>fptools/ghc/compiler/prelude/</code></a>.
  15     </p>
  16
  17     <h2>Primitives</h2>
  18     <p>
  19       Some types and functions have to be hardwired into the compiler as they
  20       are atomic; all other code is essentially built around this primitive
  21       functionality.  This includes basic arithmetic types, such as integers,
  22       and their elementary operations as well as pointer types.  Primitive
  23       types and functions often receive special treatment in the code
  24       generator, which means that these entities have to be explicitly
  25       represented in the compiler.  Moreover, many of these types receive some
  26       explicit treatment in the runtime system, and so, there is some further
  27       information about <a href="../rts-libs/primitives.html">primitives in
  28       the RTS section</a> of this document.
  29     <p>
  30       The module <a
  31       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysPrim.lhs"><code>TysPrim</code></a>
  32       exports a list of all primitive type constructors as <code>primTyCons ::
  33       [TyCon]</code>.  All of these type constructors (of type
  34       <code>TyCon</code>) are also exported as <code>intPrimTyCon</code>,
  35       <code>stablePtrPrimTyCon</code>, and so on.  In addition, for each
  36       nullary type constructor the corresponding type (of type
  37       <code>Type</code>) is also exported; for example, we have
  38       <code>intPrimTy :: Type</code>.  For all other type constructors, a
  39       function is exported that constructs the type obtained by applying the
  40       type constructors to an argument type (of type <code>Type</code>); for
  41       example, we have <code>mkStablePtrPrimTy :: Type -> Type</code>.
  42     <p>
  43       As it is inconvenient to identify type that receive a special treatment
  44       by the code generator by looking at their name, the module <a
  45       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrimRep.lhs"><code>PrimRep</code></a>
  46       exports a data type <code>PrimRep</code>, which lists all
  47       machine-manipulable implementation types.  The module also exports a set
  48       of query functions on <code>PrimRep</code> that define properties, such
  49       as a type's byte size or whether a primitive type is a pointer type.
  50       Moreover, the function <code>TysPrim.primRepTyCon :: PrimRep ->
  51       TyCon</code> converts <code>PrimRep</code> values into the corresponding
  52       type constructor.
  53
  54     <h2>The Prelude</h2>
  55     <p>
  56       In addition to entities that are primitive, as the compiler has to treat
  57       them specially in the backend, there is a set of types, functions,
  58       etc. that the Haskell language definition flags as essential to the
  59       language by placing them into the special module <code>Prelude</code>
  60       that is implicitly imported into each Haskell module.  For some of these
  61       entities it suffices to define them (by standard Haskell definitions) in
  62       a <code>Prelude</code> module and ensuring that this module is treated
  63       specially by being always imported .
  64     <p>
  65       However, there is a set of entities (such as, for example, the list type
  66       and the corresponding data constructors) that have an inbetween status:
  67       They are not truly primitive (lists, for example, can easily be defined
  68       by a <code>data</code> declaration), but the compiler has to have extra
  69       knowledge about them, as they are associated with some particular
  70       features of the language (in the case of lists, there is special syntax,
  71       such as list comprehensions, associated with the type).  Another
  72       example, for a special kind of entity are type classes that can be used
  73       in a <code>deriving</code> clause.  All types that are not-primitive,
  74       but about which the compiler nonetheless has to have some extra
  75       knowledge are defined in the module <a
  76       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysWiredIn.lhs"><code>TysWiredIn</code></a>.
  77     <p>
  78       All wired in type constructors are contained in <code>wiredInTyCons ::
  79       [TyCon]</code>.  In addition to that list, <code>TysWiredIn</code>
  80       exports variables bound to representations of all listed type
  81       constructors and their data constructors.  So, for example, we have
  82       <code>listTyCon</code> together with <code>nilDataCon</cons> and
  83       </code>consDataCon</code>.  There are also convenience functions, such
  84       as <code>mkListTy</code> and <code>mkTupleTy</code>, which construct
  85       compound types.
  86     <p>
  87       All names of types, functions, etc. known to the compiler are defined in
  88       <a
  89       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelNames.lhs"><code>PrelNames</code></a>.
  90       This includes the names of types and functions exported from
  91       <code>TysWiredIn</code>, but also others.  In particular, this module
  92       also fixes the names of all prelude modules; i.e., of the modules whose
  93       name starts with <code>Prel</code>, which GHC's library uses to bring
  94       some structure into the quite large number of <code>Prelude</code>
  95       definitions.
  96     <p>
  97       <code>PrelNames.knownKeyNames :: [Name]</code> contains all names known
  98       to the compiler, but the elements of the list are also exported
  99       individually as variables, such as <code>floatTyConName</code> (having
 100       the lexeme <code>Float</code>) and <code>floatDataConName</code> (having
 101       the lexeme <code>F#</code>).  For each of these names,
 102       <code>PrelNames</code> derfines a unique key with a definition, such as
 103     <p>
 104 <blockquote><pre>
 105 floatPrimTyConKey = mkPreludeTyConUnique 11</pre>
 106 </blockquote>
 107     <p>
 108       that is, all unique keys for known prelude names are hardcoded into
 109       <code>PrelNames</code> (and uniqueness has to be manually ensured in
 110       that module).  To simplify matching the types of important groups of
 111       type constructors, <code>PrelNames</code> also exports lists, such as
 112       <code>numericTyKeys</code> (keys of all numeric types), that contain the
 113       unique keys of all names in that group.  In addition, derivable type
 114       classes and their structure is defined by
 115       <code>derivableClassKeys</code> and related definitions.
 116     <p>
 117       In addition to names that have unique keys, <code>PrelNames</code> also
 118       defines a set of names without uniqueness information.  These names end
 119       on the suffix <code>_RDR</code> and are of type <code>RdrName</code> (an
 120       example, is <code>times_RDR</code>, which represents the lexeme
 121       <code>*</code>).  The names are used in locations where they pass
 122       through the renamer anyway (e.g., code generated from deriving clauses),
 123       which will take care of adding uniqueness information.
 124     <p>
 125       The module
 126       <a href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelInfo.lhs"><code>PrelInfo</code></a>
 127       in some sense ties all the above together and provides a reasonably
 128       restricted interface to these definition to the rest of the compiler.
 129       However, from what I have seen, this doesn't quite work out and the
 130       earlier mentioned modules are directly imported in many places.
 131
 132     <p><small>
 133 <!-- hhmts start -->
 134 Last modified: Mon Nov 26 19:29:33 EST 2001
 135 <!-- hhmts end -->
 136     </small>
 137   </body>
 138 </html>