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       One of the trickiest aspects of GHC is the delicate interplay
  12       between what knowledge is baked into the compiler, and what
  13       knowledge it gets by reading the interface files of library
  14       modules.  In general, the less that is baked in, the better.
  15 <p>
  16       Most of what the compiler has to have wired in about primitives and
  17       prelude definitions is in
  18       <a
  19       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/"><code>fptools/ghc/compiler/prelude/</code></a>.
  20     </p>
  21
  22 GHC recognises these main classes of baked-in-ness:
  23 <dl>
  24 <dt><strong>Primitive types.</strong>
  25 <dd>Primitive types cannot be defined in Haskell, and are utterly baked into the compiler.
  26 They are notionally defined in the fictional module <tt>GHC.Prim</tt>.   The <tt>TyCon</tt>s for these types are all defined
  27 in module <tt>TysPrim</tt>; for example,
  28 <pre>
  29   intPrimTyCon :: TyCon
  30   intPrimTyCon = ....
  31 </pre>
  32 Examples:
  33 <tt>Int#, Float#, Addr#, State#</tt>.
  34 <p>
  35 <dt><strong>Wired-in types.</strong>
  36 <dd>Wired-in types can be defined in Haskell, and indeed are (many are defined in </tt>GHC.Base</tt>).
  37 However, it's very convenient for GHC to be able to use the type constructor for (say) <tt>Int</tt>
  38 without looking it up in any environment.  So module <tt>TysWiredIn</tt> contains many definitions
  39 like this one:
  40 <pre>
  41   intTyCon :: TyCon
  42   intTyCon = ....
  43
  44   intDataCon :: DataCon
  45   intDataCon = ....
  46 </pre>
  47 However, since a <tt>TyCon</tt> value contains the entire type definition inside it, it follows
  48 that the complete definition of <tt>Int</tt> is thereby baked into the compiler.
  49 <p>
  50 Nevertheless, the library module <tt>GHC.Base</tt> still contains a definition for <tt>Int</tt>
  51 just so that its info table etc get generated somewhere.  Chaos will result if the wired-in definition
  52 in <tt>TysWiredIn</tt> differs from that in <tt>GHC.Base</tt>.
  53 <p>
  54 The rule is that only very simple types should be wired in (for example, <tt>Ratio</tt> is not,
  55 and <tt>IO</tt> is certainly not).  No class is wired in: classes are just too complicated.
  56 <p>
  57 Examples: <tt>Int</tt>, <tt>Float</tt>, <tt>List</tt>, tuples.
  58
  59 <p>
  60 <dt><strong>Known-key things.</strong>
  61 <dd>GHC knows of the existence of many, many other types, classes and values.  <em>But all it knows is
  62 their <tt>Name</tt>.</em>  Remember, a <tt>Name</tt> includes a unique key that identifies the
  63 thing, plus its defining module and occurrence name
  64 (see <a href="names.html">The truth about Names</a>).  Knowing a <tt>Name</tt>, therefore, GHC can
  65 run off to the interface file for the module and find out everything else it might need.
  66 <p>
  67 Most of these known-key names are defined in module <tt>PrelNames</tt>; a further swathe concerning
  68 Template Haskell are defined in <tt>DsMeta</tt>.  The allocation of unique keys is done manually;
  69 chaotic things happen if you make a mistake here, which is why they are all together.
  70 </dl>
  71
  72 All the <tt>Name</tt>s from all the above categories are used to initialise the global name cache,
  73 which maps (module,occurrence-name) pairs to the globally-unique <tt>Name</tt> for that
  74 thing.  (See <tt>HscMain.initOrigNames</tt>.)
  75
  76 <p>
  77 The next sections elaborate these three classes a bit.
  78
  79
  80     <h2>Primitives (module <tt>TysPrim</tt>)</h2>
  81     <p>
  82       Some types and functions have to be hardwired into the compiler as they
  83       are atomic; all other code is essentially built around this primitive
  84       functionality.  This includes basic arithmetic types, such as integers,
  85       and their elementary operations as well as pointer types.  Primitive
  86       types and functions often receive special treatment in the code
  87       generator, which means that these entities have to be explicitly
  88       represented in the compiler.  Moreover, many of these types receive some
  89       explicit treatment in the runtime system, and so, there is some further
  90       information about <a href="../rts-libs/primitives.html">primitives in
  91       the RTS section</a> of this document.
  92     <p>
  93       The module <a
  94       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysPrim.lhs"><code>TysPrim</code></a>
  95       exports a list of all primitive type constructors as <code>primTyCons ::
  96       [TyCon]</code>.  All of these type constructors (of type
  97       <code>TyCon</code>) are also exported as <code>intPrimTyCon</code>,
  98       <code>stablePtrPrimTyCon</code>, and so on.  In addition, for each
  99       nullary type constructor the corresponding type (of type
 100       <code>Type</code>) is also exported; for example, we have
 101       <code>intPrimTy :: Type</code>.  For all other type constructors, a
 102       function is exported that constructs the type obtained by applying the
 103       type constructors to an argument type (of type <code>Type</code>); for
 104       example, we have <code>mkStablePtrPrimTy :: Type -> Type</code>.
 105     <p>
 106       As it is inconvenient to identify type that receive a special treatment
 107       by the code generator by looking at their name, the module <a
 108       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrimRep.lhs"><code>PrimRep</code></a>
 109       exports a data type <code>PrimRep</code>, which lists all
 110       machine-manipulable implementation types.  The module also exports a set
 111       of query functions on <code>PrimRep</code> that define properties, such
 112       as a type's byte size or whether a primitive type is a pointer type.
 113       Moreover, the function <code>TysPrim.primRepTyCon :: PrimRep ->
 114       TyCon</code> converts <code>PrimRep</code> values into the corresponding
 115       type constructor.
 116
 117     <h2>Wired in types (module <tt>TysWiredIn</tt>)</h2>
 118     <p>
 119       In addition to entities that are primitive, as the compiler has to treat
 120       them specially in the backend, there is a set of types, functions,
 121       etc. that the Haskell language definition flags as essential to the
 122       language by placing them into the special module <code>Prelude</code>
 123       that is implicitly imported into each Haskell module.  For some of these
 124       entities it suffices to define them (by standard Haskell definitions) in
 125       a <code>Prelude</code> module and ensuring that this module is treated
 126       specially by being always imported .
 127     <p>
 128       However, there is a set of entities (such as, for example, the list type
 129       and the corresponding data constructors) that have an inbetween status:
 130       They are not truly primitive (lists, for example, can easily be defined
 131       by a <code>data</code> declaration), but the compiler has to have extra
 132       knowledge about them, as they are associated with some particular
 133       features of the language (in the case of lists, there is special syntax,
 134       such as list comprehensions, associated with the type).  Another
 135       example, for a special kind of entity are type classes that can be used
 136       in a <code>deriving</code> clause.  All types that are not-primitive,
 137       but about which the compiler nonetheless has to have some extra
 138       knowledge are defined in the module <a
 139       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysWiredIn.lhs"><code>TysWiredIn</code></a>.
 140     <p>
 141       All wired in type constructors are contained in <code>wiredInTyCons ::
 142       [TyCon]</code>.  In addition to that list, <code>TysWiredIn</code>
 143       exports variables bound to representations of all listed type
 144       constructors and their data constructors.  So, for example, we have
 145       <code>listTyCon</code> together with <code>nilDataCon</cons> and
 146       </code>consDataCon</code>.  There are also convenience functions, such
 147       as <code>mkListTy</code> and <code>mkTupleTy</code>, which construct
 148       compound types.
 149     <p>
 150
 151     <h2>Known-key names (module <tt>PrelNames</tt>)</h2>
 152
 153       All names of types, functions, etc. known to the compiler are defined in
 154       <a
 155       href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelNames.lhs"><code>PrelNames</code></a>.
 156       This includes the names of types and functions exported from
 157       <code>TysWiredIn</code>, but also others.  In particular, this module
 158       also fixes the names of all prelude modules; i.e., of the modules whose
 159       name starts with <code>Prel</code>, which GHC's library uses to bring
 160       some structure into the quite large number of <code>Prelude</code>
 161       definitions.
 162     <p>
 163       <code>PrelNames.knownKeyNames :: [Name]</code> contains all names known
 164       to the compiler, but the elements of the list are also exported
 165       individually as variables, such as <code>floatTyConName</code> (having
 166       the lexeme <code>Float</code>) and <code>floatDataConName</code> (having
 167       the lexeme <code>F#</code>).  For each of these names,
 168       <code>PrelNames</code> derfines a unique key with a definition, such as
 169     <p>
 170 <blockquote><pre>
 171 floatPrimTyConKey = mkPreludeTyConUnique 11</pre>
 172 </blockquote>
 173     <p>
 174       that is, all unique keys for known prelude names are hardcoded into
 175       <code>PrelNames</code> (and uniqueness has to be manually ensured in
 176       that module).  To simplify matching the types of important groups of
 177       type constructors, <code>PrelNames</code> also exports lists, such as
 178       <code>numericTyKeys</code> (keys of all numeric types), that contain the
 179       unique keys of all names in that group.  In addition, derivable type
 180       classes and their structure is defined by
 181       <code>derivableClassKeys</code> and related definitions.
 182     <p>
 183       In addition to names that have unique keys, <code>PrelNames</code> also
 184       defines a set of names without uniqueness information.  These names end
 185       on the suffix <code>_RDR</code> and are of type <code>RdrName</code> (an
 186       example, is <code>times_RDR</code>, which represents the lexeme
 187       <code>*</code>).  The names are used in locations where they pass
 188       through the renamer anyway (e.g., special constructors encountered by
 189       the parser, such as [], and code generated from deriving clauses), which
 190       will take care of adding uniqueness information.
 191     <p>
 192
 193 <h2>Gathering it all together (module <tt>PrelInfo</tt>)</h2>
 194       The module
 195       <a href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelInfo.lhs"><code>PrelInfo</code></a>
 196       in some sense ties all the above together and provides a reasonably
 197       restricted interface to these definition to the rest of the compiler.
 198       However, from what I have seen, this doesn't quite work out and the
 199       earlier mentioned modules are directly imported in many places.
 200
 201     <p><small>
 202 <!-- hhmts start -->
 203 Last modified: Tue Dec 11 17:54:07 EST 2001
 204 <!-- hhmts end -->
 205     </small>
 206   </body>
 207 </html>