summaryrefslogtreecommitdiff
path: root/docs/comm/rts-libs/primitives.html
blob: 28abc794261be1a50ca0b4469b2d3a5e188d1b2f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
<!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</title>
  </head>

  <body BGCOLOR="FFFFFF">
    <h1>The GHC Commentary - Primitives</h1>
    <p>
      Most user-level Haskell types and functions provided by GHC (in
      particular those from the Prelude and GHC's Prelude extensions) are
      internally constructed from even more elementary types and functions.
      Most notably, GHC understands a notion of <em>unboxed types,</em> which
      are the Haskell representation of primitive bit-level integer, float,
      etc. types (as opposed to their boxed, heap allocated counterparts) -
      cf. <a
	href="http://research.microsoft.com/Users/simonpj/Papers/unboxed-values.ps.Z">"Unboxed
	Values as First Class Citizens."</a>

    <h4>The Ultimate Source of Primitives</h4>
    <p>
      The hardwired types of GHC are brought into scope by the module
      <code>PrelGHC</code>.  This modules only exists in the form of a
      handwritten interface file <a
      href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/lib/std/PrelGHC.hi-boot"><code>PrelGHC.hi-boot</code>,</a>
      which lists the type and function names, as well as instance
      declarations.  The actually types of these names as well as their
      implementation is hardwired into GHC.  Note that the names in this file
      are z-encoded, and in particular, identifiers ending on <code>zh</code>
      denote user-level identifiers ending in a hash mark (<code>#</code>),
      which is used to flag unboxed values or functions operating on unboxed
      values.  For example, we have <code>Char#</code>, <code>ord#</code>, and
      so on. 

    <h4>The New Primitive Definition Scheme</h4>
    <p>
      As of (about) the development version 4.11, the types and various
      properties of primitive operations are defined in the file <a
	href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/compiler/prelude/primops.txt.pp"><code>primops.txt.pp</code></a>.
      (Personally, I don't think that the <code>.txt</code> suffix is really
      appropriate, as the file is used for automatic code generation; the
      recent addition of <code>.pp</code> means that the file is now mangled
      by cpp.)
    <p>
      The utility <a
	href="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/ghc/utils/genprimopcode/"><code>genprimopcode</code></a> 
      generates a series of Haskell files from <code>primops.txt</code>, which
      encode the types and various properties of the primitive operations as
      compiler internal data structures.  These Haskell files are not complete
      modules, but program fragments, which are included into compiler modules
      during the GHC build process.  The generated include files can be found
      in the directory <code>fptools/ghc/compiler/</code> and carry names
      matching the pattern <code>primop-*.hs-incl</code>.  They are generate
      during the execution of the <code>boot</code> target in the
      <code>fptools/ghc/</code> directory.  This scheme significantly
      simplifies the maintenance of primitive operations.
    <p> 
      As of development version 5.02, the <code>primops.txt</code> file also allows the
      recording of documentation about intended semantics of the primitives.  This can
      be extracted into a latex document (or rather, into latex document fragments)
      via an appropriate switch to <code>genprimopcode</code>. In particular, see <code>primops.txt</code>
      for full details of how GHC is configured to cope with different machine word sizes.
    <p><small>
<!-- hhmts start -->
Last modified: Mon Nov 26 18:03:16 EST 2001
<!-- hhmts end -->
    </small>
  </body>
</html>