Test Trac #9036
[ghc.git] / 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>