<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>
- <h2>Primitives</h2>
+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
TyCon</code> converts <code>PrimRep</code> values into the corresponding
type constructor.
- <h2>The Prelude</h2>
+ <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,
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>.
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