diff options
Diffstat (limited to 'docs/comm/the-beast/prelude.html')
| -rw-r--r-- | docs/comm/the-beast/prelude.html | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/docs/comm/the-beast/prelude.html b/docs/comm/the-beast/prelude.html new file mode 100644 index 0000000000..64b607def5 --- /dev/null +++ b/docs/comm/the-beast/prelude.html @@ -0,0 +1,207 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> + <title>The GHC Commentary - Primitives and the Prelude</title> + </head> + + <body BGCOLOR="FFFFFF"> + <h1>The GHC Commentary - Primitives and the Prelude</h1> + <p> + One of the trickiest aspects of GHC is the delicate interplay + between what knowledge is baked into the compiler, and what + knowledge it gets by reading the interface files of library + modules. In general, the less that is baked in, the better. +<p> + Most of what the compiler has to have wired in about primitives and + prelude definitions is in + <a + href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/"><code>fptools/ghc/compiler/prelude/</code></a>. + </p> + +GHC recognises these main classes of baked-in-ness: +<dl> +<dt><strong>Primitive types.</strong> +<dd>Primitive types cannot be defined in Haskell, and are utterly baked into the compiler. +They are notionally defined in the fictional module <tt>GHC.Prim</tt>. The <tt>TyCon</tt>s for these types are all defined +in module <tt>TysPrim</tt>; for example, +<pre> + intPrimTyCon :: TyCon + intPrimTyCon = .... +</pre> +Examples: +<tt>Int#, Float#, Addr#, State#</tt>. +<p> +<dt><strong>Wired-in types.</strong> +<dd>Wired-in types can be defined in Haskell, and indeed are (many are defined in </tt>GHC.Base</tt>). +However, it's very convenient for GHC to be able to use the type constructor for (say) <tt>Int</tt> +without looking it up in any environment. So module <tt>TysWiredIn</tt> contains many definitions +like this one: +<pre> + intTyCon :: TyCon + intTyCon = .... + + intDataCon :: DataCon + intDataCon = .... +</pre> +However, since a <tt>TyCon</tt> value contains the entire type definition inside it, it follows +that the complete definition of <tt>Int</tt> is thereby baked into the compiler. +<p> +Nevertheless, the library module <tt>GHC.Base</tt> still contains a definition for <tt>Int</tt> +just so that its info table etc get generated somewhere. Chaos will result if the wired-in definition +in <tt>TysWiredIn</tt> differs from that in <tt>GHC.Base</tt>. +<p> +The rule is that only very simple types should be wired in (for example, <tt>Ratio</tt> is not, +and <tt>IO</tt> is certainly not). No class is wired in: classes are just too complicated. +<p> +Examples: <tt>Int</tt>, <tt>Float</tt>, <tt>List</tt>, tuples. + +<p> +<dt><strong>Known-key things.</strong> +<dd>GHC knows of the existence of many, many other types, classes and values. <em>But all it knows is +their <tt>Name</tt>.</em> Remember, a <tt>Name</tt> includes a unique key that identifies the +thing, plus its defining module and occurrence name +(see <a href="names.html">The truth about Names</a>). Knowing a <tt>Name</tt>, therefore, GHC can +run off to the interface file for the module and find out everything else it might need. +<p> +Most of these known-key names are defined in module <tt>PrelNames</tt>; a further swathe concerning +Template Haskell are defined in <tt>DsMeta</tt>. The allocation of unique keys is done manually; +chaotic things happen if you make a mistake here, which is why they are all together. +</dl> + +All the <tt>Name</tt>s from all the above categories are used to initialise the global name cache, +which maps (module,occurrence-name) pairs to the globally-unique <tt>Name</tt> for that +thing. (See <tt>HscMain.initOrigNames</tt>.) + +<p> +The next sections elaborate these three classes a bit. + + + <h2>Primitives (module <tt>TysPrim</tt>)</h2> + <p> + Some types and functions have to be hardwired into the compiler as they + are atomic; all other code is essentially built around this primitive + functionality. This includes basic arithmetic types, such as integers, + and their elementary operations as well as pointer types. Primitive + types and functions often receive special treatment in the code + generator, which means that these entities have to be explicitly + represented in the compiler. Moreover, many of these types receive some + explicit treatment in the runtime system, and so, there is some further + information about <a href="../rts-libs/primitives.html">primitives in + the RTS section</a> of this document. + <p> + The module <a + href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysPrim.lhs"><code>TysPrim</code></a> + exports a list of all primitive type constructors as <code>primTyCons :: + [TyCon]</code>. All of these type constructors (of type + <code>TyCon</code>) are also exported as <code>intPrimTyCon</code>, + <code>stablePtrPrimTyCon</code>, and so on. In addition, for each + nullary type constructor the corresponding type (of type + <code>Type</code>) is also exported; for example, we have + <code>intPrimTy :: Type</code>. For all other type constructors, a + function is exported that constructs the type obtained by applying the + type constructors to an argument type (of type <code>Type</code>); for + example, we have <code>mkStablePtrPrimTy :: Type -> Type</code>. + <p> + As it is inconvenient to identify type that receive a special treatment + by the code generator by looking at their name, the module <a + href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrimRep.lhs"><code>PrimRep</code></a> + exports a data type <code>PrimRep</code>, which lists all + machine-manipulable implementation types. The module also exports a set + of query functions on <code>PrimRep</code> that define properties, such + as a type's byte size or whether a primitive type is a pointer type. + Moreover, the function <code>TysPrim.primRepTyCon :: PrimRep -> + TyCon</code> converts <code>PrimRep</code> values into the corresponding + type constructor. + + <h2>Wired in types (module <tt>TysWiredIn</tt>)</h2> + <p> + In addition to entities that are primitive, as the compiler has to treat + them specially in the backend, there is a set of types, functions, + etc. that the Haskell language definition flags as essential to the + language by placing them into the special module <code>Prelude</code> + that is implicitly imported into each Haskell module. For some of these + entities it suffices to define them (by standard Haskell definitions) in + a <code>Prelude</code> module and ensuring that this module is treated + specially by being always imported . + <p> + However, there is a set of entities (such as, for example, the list type + and the corresponding data constructors) that have an inbetween status: + They are not truly primitive (lists, for example, can easily be defined + by a <code>data</code> declaration), but the compiler has to have extra + knowledge about them, as they are associated with some particular + features of the language (in the case of lists, there is special syntax, + such as list comprehensions, associated with the type). Another + example, for a special kind of entity are type classes that can be used + in a <code>deriving</code> clause. All types that are not-primitive, + but about which the compiler nonetheless has to have some extra + knowledge are defined in the module <a + href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/TysWiredIn.lhs"><code>TysWiredIn</code></a>. + <p> + All wired in type constructors are contained in <code>wiredInTyCons :: + [TyCon]</code>. In addition to that list, <code>TysWiredIn</code> + exports variables bound to representations of all listed type + constructors and their data constructors. So, for example, we have + <code>listTyCon</code> together with <code>nilDataCon</cons> and + </code>consDataCon</code>. There are also convenience functions, such + as <code>mkListTy</code> and <code>mkTupleTy</code>, which construct + compound types. + <p> + + <h2>Known-key names (module <tt>PrelNames</tt>)</h2> + + All names of types, functions, etc. known to the compiler are defined in + <a + href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelNames.lhs"><code>PrelNames</code></a>. + This includes the names of types and functions exported from + <code>TysWiredIn</code>, but also others. In particular, this module + also fixes the names of all prelude modules; i.e., of the modules whose + name starts with <code>Prel</code>, which GHC's library uses to bring + some structure into the quite large number of <code>Prelude</code> + definitions. + <p> + <code>PrelNames.knownKeyNames :: [Name]</code> contains all names known + to the compiler, but the elements of the list are also exported + individually as variables, such as <code>floatTyConName</code> (having + the lexeme <code>Float</code>) and <code>floatDataConName</code> (having + the lexeme <code>F#</code>). For each of these names, + <code>PrelNames</code> derfines a unique key with a definition, such as + <p> +<blockquote><pre> +floatPrimTyConKey = mkPreludeTyConUnique 11</pre> +</blockquote> + <p> + that is, all unique keys for known prelude names are hardcoded into + <code>PrelNames</code> (and uniqueness has to be manually ensured in + that module). To simplify matching the types of important groups of + type constructors, <code>PrelNames</code> also exports lists, such as + <code>numericTyKeys</code> (keys of all numeric types), that contain the + unique keys of all names in that group. In addition, derivable type + classes and their structure is defined by + <code>derivableClassKeys</code> and related definitions. + <p> + In addition to names that have unique keys, <code>PrelNames</code> also + defines a set of names without uniqueness information. These names end + on the suffix <code>_RDR</code> and are of type <code>RdrName</code> (an + example, is <code>times_RDR</code>, which represents the lexeme + <code>*</code>). The names are used in locations where they pass + through the renamer anyway (e.g., special constructors encountered by + the parser, such as [], and code generated from deriving clauses), which + will take care of adding uniqueness information. + <p> + +<h2>Gathering it all together (module <tt>PrelInfo</tt>)</h2> + The module + <a href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/PrelInfo.lhs"><code>PrelInfo</code></a> + in some sense ties all the above together and provides a reasonably + restricted interface to these definition to the rest of the compiler. + However, from what I have seen, this doesn't quite work out and the + earlier mentioned modules are directly imported in many places. + + <p><small> +<!-- hhmts start --> +Last modified: Tue Dec 11 17:54:07 EST 2001 +<!-- hhmts end --> + </small> + </body> +</html> |