Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Annotation of /sml/trunk/src/system/smlnj/init/init.cmi
ViewVC logotype

Annotation of /sml/trunk/src/system/smlnj/init/init.cmi

Parent Directory Parent Directory | Revision Log Revision Log


Revision 715 - (view) (download)

1 : blume 573 #
2 : blume 643 # init.cmi
3 : blume 573 #
4 : blume 592 # (C) 2000 Lucent Technologies, Bell Laboratories
5 : blume 573 #
6 :     # Author: Matthias Blume (blume@kurims.kyoto-u.ac.jp)
7 :     #
8 : blume 643 # This is the specification for how to build the "init library".
9 :     # The main purpose of the init library is to tie in the runtime system
10 : blume 592 # and to build the pervasive environment. The pervasive enviroment
11 :     # must contain a binding of the "special" structure named "_Core".
12 : blume 643 # Because of its special nature, the init library cannot be described as
13 : blume 573 # an ordinary CM library. Instead, it is built from the DAG description
14 : blume 643 # in this file. The bootstrap compiler turns the init library into an
15 :     # ordinary stable library. The boot process fetches the pervasive
16 : blume 573 # environment from that stable library.
17 :     #
18 : blume 643 # In addition to the pervasive environments, the init library can (and does)
19 : blume 573 # also export additional definitions. These can be accessed by client code
20 :     # (such as the implementation of the Basis library) by simply listing
21 :     # "init.cmi : cm" in their respective library description files. (Since CM
22 :     # does not automatically recognize the member class of ".cmi" files, the
23 :     # class "cm" must be given explicitly.) Clients who want to access "init.cmi"
24 :     # must be in possession of the privilege named "primitive".
25 :     #
26 :     # The specification is basically a DAG: "bind" statements define
27 :     # named environments which are the results of compiling the files on the
28 :     # right-hand side of "=" wrt. a combination of the environments given
29 :     # in parentheses.
30 :     #
31 :     # Format of this file:
32 :     # - The file is processed on a line-by-line basis.
33 :     # - Empty lines and lines beginning with "#" are ignored.
34 :     # - Actual whitespace, "=", ",", "(", and ")" are all counted as whitespace.
35 :     # (this means that the syntactic sugar you see below is really just
36 :     # sugar for the human eye; the program that processes this file can
37 :     # do without it)
38 :     # - A line that says "nosplit" disables cross-module inlining (aka
39 :     # "lambda-splitting") until the next line that says "split".
40 :     # - The (single) "rts-placeholder" line acts mostly like a "bind" line.
41 :     # Its purpose is to specify the module that plays the role of a
42 :     # placeholder for the runtime system.
43 : blume 592 # - A "bind-core" line acts like a "bind" line, but it has an additional
44 :     # first argument which must be the name of a structure bound at top-level
45 :     # by the named .sml file. CM replaces these bindings by corresponding
46 :     # bindings of the internal structure symbol "_Core".
47 :     # - "bind" lines (as well as "bind-core" lines and the "rts-placeholder"
48 :     # line) must be in topological order (i.e., they cannot access environment
49 :     # names that are being defined later).
50 : blume 573 # - The last line that gets processed is the "return" line.
51 : blume 592 # It must specify at least one environment name, namely the one that is
52 :     # used as the system-wide "pervasive" environment.
53 : blume 573 # For any additional name n the exports of the module that was bound
54 : blume 643 # (by "bind") to n are added to the exports of the init library.
55 : blume 573 # These exports can be accessed by clients that explicitly list init.cmi
56 :     # in their own description files.
57 :     # Note: Since some clients need direct access to the core environment,
58 : blume 592 # the name "core" is also listed. This "core" (as opposed to "xcore"
59 :     # has a binding for structure "Core" which can be accessed directly
60 :     # from SML source code.)
61 : blume 573 # - There is one pre-defined name ("primitive") that refers to the
62 :     # Environment.primEnv. It must not be "exported" by the "return" line.
63 : blume 715 # - A line of the form "ifdef SYMBOL rest ..." is equivalent to "rest ..."
64 :     # if the CM symbol "SYMBOL" is defined (i.e., if "#if defined(SYMBOL)"
65 :     # would be true in ordinary description files). If SYMBOL is not
66 :     # defined, then the "ifdef" line will be ignored.
67 :     # - Similarly, a line of the form "ifndef SYMBOL rest ..." is equivalent
68 :     # to "rest ..." if SYMBOL is not defined; otherwise the line will
69 :     # be ignored.
70 : blume 573 #
71 : blume 592 # Note that a binding for structure _Core is necessary ALMOST EVERYWHERE.
72 :     # Therefore, it is necessary that the pervasive environment has such a
73 : blume 643 # binding. For files of this initial library (which do not yet have the
74 : blume 592 # benefit of being able to access the pervasive environment), a trivial
75 :     # member "xcore" is used to supply _Core.
76 : blume 715 #
77 :     # Conditional compilation:
78 :     #
79 :     # Guarded lines of the "ifdef" and "ifndef" variety (see above) are used to
80 :     # achive a limited form of conditional compilation within the init library.
81 :     # Since "ifdef" and "ifndef" guards can be applied even to lines that
82 :     # are already guarded, one can easily get the effect of a logical "and".
83 :     # A logical "or" can be obtained by duplicating lines that have different
84 :     # guards. (Be careful with this, though. The guards of such duplicated
85 :     # lines must be mutually exclusive! Otherwise the same ML source might get
86 :     # included more than once.)
87 :     # Thus, any logical combinaton of conditions can be expressed (albeit perhaps
88 :     # clumsily). For simple case (such as, for example, having different source
89 :     # files for different architectures), this facility should be easy to use.
90 :     #
91 :     # Example:
92 :     # ...
93 :     # ifdef ARCH_ALPHA32 bind foo = foo-alpha32.sml (bar, baz)
94 :     # ifdef ARCH_X86 bind foo = foo-x86.sml (bar, baz)
95 :     # ifndef ARCH_ALPHA32 ifndef ARCH_X86 bind foo = foo-default.sml (bar, baz)
96 :     # ...
97 :     #
98 : blume 573
99 :     #### END OF EXPLANATION, SPEC STARTS HERE...
100 :    
101 :     # Turn off splitting. It would confuse the compiler because the following
102 :     # files are not actually loaded at boot time.
103 :     nosplit
104 :    
105 : blume 592 # The "signature" of the runtime system. (No _Core yet.)
106 : blume 573 bind asig = assembly.sig (primitive)
107 :    
108 : blume 592 # The placeholder for the runtime system. (No _Core yet.)
109 : blume 573 rts-placeholder rts = dummy.sml (asig, primitive)
110 :    
111 :     # We can now turn the cross-module optimizer on (when available)...
112 :     split
113 :    
114 :     # This defines the core environment to be used everywhere else...
115 : blume 592 # (This binds the structure symbol "Core", which is not yet the one that
116 :     # is used implicitly by the compiler. Of course, "core.sml" itself cannot
117 :     # yet have access to _Core.)
118 : blume 573 bind core = core.sml (rts, asig, primitive)
119 :    
120 : blume 592 # Now we make the binding for structure _Core for use by the remaining
121 : blume 643 # members of the init library. (Everybody else in the world gets access to
122 : blume 592 # _Core via the pervasive env.)
123 :     # The "bind-core" line says that its first argument ("xCore") should be
124 :     # re-written as "_Core" before compilation. This rewriting is done
125 :     # internally after the parser has already completed. Normally, there is
126 :     # no way of referring explicitly to a structure named _Core.
127 :     bind-core (xCore) xcore = xcore.sml (core)
128 :    
129 : blume 573 # The rest of the DAG...
130 : blume 592 # (Everybody implicitly depends on xcore to have access to _Core.)
131 :     bind built-in = built-in.sml (core, primitive, xcore)
132 :     bind pp = pre-perv.sml (built-in, xcore)
133 :     bind ps = pre-string.sml (core, built-in, pp, xcore)
134 :     bind ss-sig = substring.sig (pp, built-in, xcore)
135 :     bind ss = substring.sml (ss-sig, pp, ps, core, built-in, xcore)
136 :     bind print-hook = print-hook.sml (built-in, xcore)
137 :     bind use-hook = use-hook.sml (built-in, xcore)
138 :     bind exn-info-hook = exn-info-hook.sml (built-in, xcore)
139 :     bind init-utils = init-utils.sml (ps ss-sig ss, xcore)
140 : blume 573
141 :     # Building the "pervasive" environment. This file should be
142 :     # kept as small as possible and only bind non-modular things
143 :     # (i.e., top-level types and values).
144 : blume 592 # Make sure everybody else in the world gets access to structure _Core...
145 :     bind-core (xCore) pervasive = pervasive.sml (core, ps, ss, pp, print-hook, use-hook, exn-info-hook, built-in, xcore)
146 : blume 573
147 :     # Report the results to the world...
148 : blume 592 return (pervasive) built-in print-hook use-hook exn-info-hook core init-utils

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0