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

SCM Repository

[smlnj] Diff of /sml/trunk/src/system/README
ViewVC logotype

Diff of /sml/trunk/src/system/README

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 632, Sat Apr 29 15:50:42 2000 UTC revision 643, Fri May 12 08:29:15 2000 UTC
# Line 1  Line 1 
1  Compiler Hacker's Guide to the new CM...  Compiler Hacker's Guide to the new CM...
2  ========================================  ========================================
3    
4  Last change: 3/2000  Last change: 12/5/2000
5    
6  * Libraries  * Libraries
7  -----------  -----------
# Line 19  Line 19 
19  the compiler ("*" means that I consider the library potentially useful  the compiler ("*" means that I consider the library potentially useful
20  in its own right):  in its own right):
21    
22    * basis.cm                            SML'97 Basis Library (pre-loaded)    * $/basis.cm                          SML'97 Basis Library (pre-loaded)
23    * smlnj-lib.cm                        SML/NJ Utility Library    * $/smlnj-lib.cm                      SML/NJ Utility Library
24    * html-lib.cm                         SML/NJ HTML Library    * $/html-lib.cm                       SML/NJ HTML Library
25    * pp-lib.cm                           SML/NJ Pretty-print Library    * $/pp-lib.cm                         SML/NJ Pretty-print Library
26    
27    * ml-yacc-lib.cm                      SML/NJ ML-Yacc runtime library    * $/ml-yacc-lib.cm                    SML/NJ ML-Yacc runtime library
28    
29    * smlnj/compiler/{alpha32,hppa,ppc,sparc,x86}.cm    * $smlnj/compiler/{alpha32,hppa,ppc,sparc,x86}.cm
30                                          cross-compiler libraries, exporting                                          cross-compiler libraries, exporting
31                                          structure <Arch>Compiler                                          structure <Arch>Compiler
32    * smlnj/compiler/current.cm           structure Compiler (current arch)    * $smlnj/compiler/current.cm          structure Compiler (current arch)
33    * smlnj/compiler/all.cm               all cross-compilers and all cross-CMBs    * $smlnj/compiler/all.cm              all cross-compilers and all cross-CMBs
34    
35    * smlnj/cm/minimal.cm                 minimal CM (pre-loaded)    * $smlnj/cm/minimal.cm                minimal CM (pre-loaded)
36    * smlnj/cm/full.cm                    full structure CM (see manual)    * $smlnj/cm/full.cm                   full structure CM (see manual)
37    * smlnj/cm/tools.cm                   CM tools library    * $smlnj/cm/tools.cm                  CM tools library
38    
39    * smlnj/cmb/{alpha32,hppa,ppc,sparc,x86}-unix.cm    * $smlnj/cmb/{alpha32,hppa,ppc,sparc,x86}-unix.cm
40                                          cross-bootstrap-compilers for Unix                                          cross-bootstrap-compilers for Unix
41                                          (structure <Arch>UnixCMB)                                          (structure <Arch>UnixCMB)
42    * smlnj/cmb/ppc-macos.cm              ...for Mac (structure PPCMacosCMB)    * $smlnj/cmb/ppc-macos.cm             ...for Mac (structure PPCMacosCMB)
43    * smlnj/cmb/x86-win32.cm              ...for Windoze (structure X86Win32CMB)    * $smlnj/cmb/x86-win32.cm             ...for Windoze (structure X86Win32CMB)
44    * smlnj/cmb/current.cm                structure CMB (current arch/os)    * $smlnj/cmb/current.cm               structure CMB (current arch/os)
45    
46    * smlnj/compiler.cm                   abbrev. for smlnj/compiler/current.cm    * $smlnj/compiler.cm                  abbrev. for $smlnj/compiler/current.cm
47    * smlnj/cm.cm                         abbrev. for smlnj/cm/full.cm    * $smlnj/cm.cm                        abbrev. for $smlnj/cm/full.cm
48    * smlnj/cmb.cm                        abbrev. for smlnj/cmb/current.cm    * $smlnj/cmb.cm                       abbrev. for $smlnj/cmb/current.cm
49    
50    * comp-lib.cm                         Utility library for compiler    * $comp-lib.cm                        Utility library for compiler
51    
52    - smlnj/viscomp/core.cm               Compiler core functionality    - $smlnj/viscomp/core.cm              Compiler core functionality
53    - smlnj/viscomp/{alpha32,hppa,ppc,sparc,x86}.cm    - $smlnj/viscomp/{alpha32,hppa,ppc,sparc,x86}.cm
54                                          Machine-specific parts of compiler                                          Machine-specific parts of compiler
55    
56    - smlnj/internal/{intsys,cm-lib,cm-hook,host-compiler-0}.cm    - $smlnj/internal/{intsys,cm-lib,cm-hook,host-compiler-0}.cm
57                                          Glue that holds the interactive system                                          Glue that holds the interactive system
58                                          together                                          together
59    
60    * MLRISC/{MLRISC,Control,Lib,ALPHA,HPPA,PPC,SPARC,IA32}.cm    * $MLRISC/{MLRISC,Control,Lib,ALPHA,HPPA,PPC,SPARC,IA32}.cm
61                                          Various MLRISC bits                                          Various MLRISC bits
62                                            (Other MLRISC libraries such as
63                                             Graph, Visual, etc. do not currently
64                                             take part in the SML/NJ build.)
65    
66    * {mlyacc,mllex,mlburg}-tool.cm       CM plug-in libraries for common tools    * ${mlyacc,mllex,mlburg}-tool.cm      CM plug-in libraries for common tools
67    * {grm,lex,burg}-ext.cm               CM plug-in libraries for common file    * ${grm,lex,burg}-ext.cm              CM plug-in libraries for common file
68                                          extensions                                          extensions
69    
70    Paths of the form $/foo/... are shorthands for $foo/foo/..., paths of
71    the form $/singlearc can also be written as $singlearc (e.g.,
72    $basis.cm instead of $/basis.cm).  The usefulness of the latter
73    shorthand is controversial, so you should probably try to avoid it.
74    
75    A more complete explanation of the $-notation can be found later in
76    this document or in the CM manual.
77    
78    To learn about the definitions of the $-anchors (and, thus, where in
79    the source tree the above libraries are defined), consult the
80    "pathconfig" file here in this directory.
81    
82  * Before you can use the bootstrap compiler (CMB)...  * Before you can use the bootstrap compiler (CMB)...
83  ----------------------------------------------------  ----------------------------------------------------
84    
85  To be able to use CMB at all, you must first say  To be able to use CMB at all, you must first say
86    
87          CM.autoload "smlnj/cmb.cm";          CM.autoload "$smlnj/cmb.cm";
88    
89  after you start sml.  Alternatively -- and perhaps more conveniently --  after you start sml.  Alternatively -- and perhaps more conveniently --
90  you can provide "smlnj/cmb.cm" as a command-line argument to sml:  you can provide "$smlnj/cmb.cm" as a command-line argument to sml:
91    
92          $ sml '$smlnj/cmb.cm'
93    
94        $ sml smlnj/cmb.cm  (Be sure to protect the dollar symbol which usually has its own
95    special meaning to the shell.)
96    
97  * Compiling the compiler  * Compiling the compiler
98  ------------------------  ------------------------
# Line 94  Line 112 
112  The default for <prefix> is "sml".  It can be changed by using  The default for <prefix> is "sml".  It can be changed by using
113  CMB.make' with the new <prefix> as the optional string argument.  CMB.make' with the new <prefix> as the optional string argument.
114    
115  CMB.make uses bootfiles after it has verified that they are consistent  CMB.make reuses existing bootfiles after it has verified that they are
116  with their corresponding binfiles.  Bootfiles do not need to be  consistent with their corresponding binfiles.  Bootfiles do not need
117  deleted in order for CMB.make to work correctly.  to be deleted in order for CMB.make to work correctly.
118    
119  To bootstrap a new system (using the runtime system boot loader), the  To bootstrap a new system (using the runtime system boot loader), the
120  bootfiles _must_ be present, the binfiles need not be present (but  bootfiles _must_ be present, the binfiles need not be present (but
# Line 120  Line 138 
138  internally, there are some changes that you should be aware of:  internally, there are some changes that you should be aware of:
139    
140  1. The script will make a heap image and build a separate library directory  1. The script will make a heap image and build a separate library directory
141     that contains links to the library files in the bootfile directory.     that contains (hard) links to the library files in the bootfile directory.
142    
143  2. There is no "-full" option anymore.  This functionality should  2. There is no "-full" option anymore.  This functionality should
144     eventually be provided by a library with a sufficiently rich export     eventually be provided by a library with a sufficiently rich export
# Line 132  Line 150 
150     option to actually make the image.  The argument to "-rebuild"     option to actually make the image.  The argument to "-rebuild"
151     is the <prefix> for the new bin and boot directories (see above).     is the <prefix> for the new bin and boot directories (see above).
152    
153       [Note: When the -rebuild option is specified, then the boot procedure
154        will not read static environments from the boot directory.  Instead,
155        after the ML code has been loaded and linked, the system will invoke
156        CMB.make' with the argument that was given to -rebuild.  After
157        CMB.make' is done, the system quits.  In essence, makeml with -rebuild
158        acts as a bootstrap compiler that is not dependent on any usable
159        static libraries.]
160    
161  Makeml will not destroy the bootfile directory.  Makeml will not destroy the bootfile directory.
162    
163  * Testing a newly generated heap image  * Testing a newly generated heap image
# Line 141  Line 167 
167  will not go as you may expect because along with the new heap image  will not go as you may expect because along with the new heap image
168  should go those new stable libraries, but unless you do something  should go those new stable libraries, but unless you do something
169  about it, the newly booted system will look for its stable libraries  about it, the newly booted system will look for its stable libraries
170  in places where you stored your _old_ stable libraries.  in places where you stored your _old_ stable libraries.  (After just
171    having done "makeml", these "places" would be within the boot file
172    hierarchy under <prefix>.boot.<arch>-<os>.)
173    
174  After you have made the new heap image, the new libraries are in a  After you have made the new heap image, the new libraries are in a
175  separate directory whose name is derived from the name of the heap  separate directory whose name is derived from the name of the heap
176  image.  (Actually, only the directory hierachy is separate, the  image.  (Actually, only the directory hierachy is separate, the
177  library files themselves are hard links.)  The "testml" script that you  library files themselves are hard links.)  The "testml" script that
178  also find here will run the heap image and instruct it to look for its  you also find here will run the heap image and instruct it to look for
179  libraries in that new library directory.  its libraries in that new library directory by setting the
180    CM_PATHCONFIG environment variable to point to a different pathconfig
181    file under <prefix>.lib.
182    
183  "testml" takes the <prefix> of the heap image as its first  "testml" takes the <prefix> of the heap image as its first
184  argument. All other arguments are passed verbatim to the ML process.  argument. All other arguments are passed verbatim to the ML process.
# Line 170  Line 200 
200  argument.  <prefix> defaults to "sml" if no argument is specified.  argument.  <prefix> defaults to "sml" if no argument is specified.
201    
202  "installml" patches the ../../lib/pathconfig file to reflect any  "installml" patches the ../../lib/pathconfig file to reflect any
203  changes or additions to the path name mapping.  changes or additions to the path name mapping.  (I say "patches"
204    because entries unrelated to the SML/NJ build process are retained in
205    their original form.)  If you want to use a destination directory that
206    is different from ../../lib, then you must do this by hand (i.e.,
207    installml will not let you do this).
208    
209  Thus, after a successful CMB.make, you should say  Thus, after a successful CMB.make, you should say
210    
# Line 189  Line 223 
223  * Cross-compiling  * Cross-compiling
224  -----------------  -----------------
225    
226  All cross-compilers live in the "smlnj/compiler/all.cm" library.  You  All cross-compilers live in the "$smlnj/compiler/all.cm" library.
227  must first say  (The source tree for the "$smlnj" anchor -- see "pathconfig" -- is
228    src/system/smlnj, but this should normally not concern you.)
229    You must first say
230    
231          CM.autoload "smlnj/compiler/all.cm";          CM.autoload "$smlnj/compiler/all.cm";
232    
233  before you can access them.  (This step corresponds to the old  before you can access them.  (This step corresponds to the old
234  CMB.retarget call.)  After that, _all_ cross-compilers are available  CMB.retarget call.)  After that, _all_ cross-compilers are available
235  at the same time.  However, the ones that you are not using don't take  at the same time.  However, the ones that you are not using don't take
236  up any undue space because they only get loaded once you actually  up any undue space because they only get loaded once you actually
237  mention them at the top-level.  The names of the structures currently  mention them at the top-level.  The names of the structures currently
238  exported by target-compilers.cm are:  exported by $smlnj/compiler/all.cm are:
239    
240          structure Alpha32UnixCMB          structure Alpha32UnixCMB
241          structure HppaUnixCMB          structure HppaUnixCMB
# Line 219  Line 255 
255  implementation of the basis library for the MacOS.)  implementation of the basis library for the MacOS.)
256    
257  Alternatively, you can select just the one single structure that you  Alternatively, you can select just the one single structure that you
258  are interested in by auto-loading smlnj/compiler/<arch>.cm or  are interested in by auto-loading $smlnj/compiler/<arch>.cm or
259  smlnj/cmb/<arch>-<os>.cm.  $smlnj/cmb/<arch>-<os>.cm.
260  <arch> currently ranges over "alpha32", "hppa", "ppc", "sparc", and "x86.  <arch> currently ranges over "alpha32", "hppa", "ppc", "sparc", and "x86.
261  <os> can be either "unix" or "macos" or "win32".  <os> can be either "unix" or "macos" or "win32".
262  (Obviously, not all combinations are valid.)  (Obviously, not all combinations are valid.)
263    
264  Again, as with smlnj/cmb.cm, you can specify the .cm file as an  Again, as with $smlnj/cmb.cm, you can specify the .cm file as an
265  argument to the sml command:  argument to the sml command:
266    
267      $ sml smlnj/compiler/all.cm      $ sml '$smlnj/compiler/all.cm'
268    
269  or  or
270    
271      $ sml smlnj/cmb/alpha32-unix.cm      $ sml '$smlnj/cmb/alpha32-unix.cm'
272    
273    [Note: The command line for the "sml" command accepts configuration
274    parameters of the form "@SMLxxx...", mode switches of the form "-m"
275    and "-a", names of ML files -- which are passed to "use" -- and
276    arguments suitable for CM.make or CM.autoload.  CM.autoload is the
277    default; the "-m" and "-a" mode switches can be used to change the
278    default -- even several times within the same command line.
279    A single argument "@CMslave" is also accepted, but it should not be
280    used directly as it is intended for use by the parallel compilation
281    facility within CM.]
282    
283  * Path configuration  * Path configuration
284  --------------------  --------------------
# Line 267  Line 313 
313  be changed, but one must do so explicitly.  In effect, it does not  be changed, but one must do so explicitly.  In effect, it does not
314  depend on the contents of the file system.  Here is how it works:  depend on the contents of the file system.  Here is how it works:
315    
316  If I specify a relative pathname in one of CM's description files  If I specify a pathname that starts with a "$", then the first arc
317  where the first component (the first arc) of that pathname is known to  between "$" and the first "/" is taken as the name of a so-called
318  CM as a configuration anchor, then the corresponding directory  "anchor".  CM knows a mapping from anchor names to directory names and
319  (according to CM's mapping) is prepended to the path.  Suppose the  replaces the prefix $<anchor> with the name of the corresponding
320  path name is "a/foo.sml" and "a" is a known anchor that maps to  directory.  Therefore, an anchored path has the general form
321  "/usr/lib/smlnj", then the resulting complete pathname is  
322  "/usr/lib/smlnj/a/foo.sml".  The pathname can be a single arc (but     $<anchor>/<path>
323  does not have to be).  For example, the anchor "basis.cm" is typically  
324  mapped to the directory where the basis library is stored.  It is important that there is at least one arc in <path>.  In other
325    words, the form $<anchor> is NOT valid.  (Actually, it currently is
326  Now, the important point is that one can change the mapping of the  valid, but CM interprets it in a different way.)
327  anchor, and the path name will also change accordingly -- even very  
328  late in the game.  CM avoids "elaborating" path names until it really  Examples:
329  needs them when it is time to open files.  CM is also willing to  
330  re-elaborate the same names if there is reason to do so. Thus, the     $smlnj/compiler/all.cm
331  "basis.cm" library that was analyzed "here" but then moved "there"     $basis.cm/basis.cm
332  will also be found "there" if the anchor has been re-set accordingly.     $MLRISC/Control.cm
333    
334    The special case where <anchor> coincides with the first arc of <path>
335    can be abbreviated by ommitting <anchor>.  This leads to the shorthand
336    
337      $/<anchor>/<more>...
338    
339    for the longer
340    
341      $<anchor>/<anchor>/<more>...
342    
343    Examples:
344    
345      $/foo/bar/baz.cm      (* same as $foo/foo/bar/baz.cm *)
346      $/basis.cm            (* same as $basis.cm/basis.cm *)
347    
348    Currently, CM accepts one additional shorthand for the case where
349    <path> has precisely one arc that coincides with <anchor>.  Here, the
350    slash "/" can be ommitted, too.
351    
352    Examples:
353    
354      $basis.cm             (* same as $/basis.cm or $basis.cm/basis.cm *)
355      $nw-ext.cm            (* same as $/nw-ext.cm or $nw-ext.cm/nw-ext.cm *)
356    
357    Previously, CM used "implicit" anchors where anchored paths simply
358    have the form
359    
360       <anchor>/<more>...
361    
362    The distinction between anchored paths and relative paths was made
363    based on whether or not <anchor> had a known mapping at the time it
364    was seen by CM.  Since this is hard to read and fragile, support for
365    implicit anchors (while still there) is considered obsolete and will
366    be faded out soon.  The meaning of an implicitly anchored path <path>
367    is the same as $/<path>.
368    
369    Recognition of implicit anchors can be turned off by issuing the
370    following command:
371    
372       CM.autoload "$smlnj/cm.cm";
373       #set CM.Control.implicit_anchors false;
374    
375    + Why anchored paths?
376    
377    The important point is that one can change the mapping of the anchor,
378    and the tranlation of the (anchored) path name will also change
379    accordingly -- even very late in the game.  CM avoids "elaborating"
380    path names until it really needs them when it is time to open files.
381    CM is also willing to re-elaborate the same names if there is reason
382    to do so. Thus, the "basis.cm" library that was analyzed "here" but
383    then moved "there" will also be found "there" if the anchor has been
384    re-set accordingly.
385    
386    The anchor mapping is (re-)initialized at startup time by reading two
387    configuration files.  Normally, those are the "../../lib/pathconfig"
388    file and the ".smlnj-pathconfig" file in your home directory (if such
389    exists).  During an ongoing session, function CM.Anchor.anchor can be
390    used to query and modify the anchor mapping.
391    
392  + Different configurations at different times:  + Different configurations at different times:
393    
394  During compilation of the compiler, CMB uses a path configuration that  During compilation of the compiler, CMB uses a path configuration that
395  is read from the file "pathconfig" located here in this directory.  is read from the file "pathconfig" located here in this directory.
396    
397  At bootstrap time, the same anchors are mapped to the corresponding  At bootstrap time (while running "makeml"), the same anchors are
398  sub-directory of the "boot" directory: basis.cm is mapped to  mapped to the corresponding sub-directory of the "boot" directory:
399  sml.boot.<arch>-<os>/basis.cm -- which means that CM will look for a  basis.cm is mapped to sml.boot.<arch>-<os>/basis.cm -- which means
400  library named sml.boot.<arch>-<os>/basis.cm/basis.cm -- and so forth.  that CM will look for a library named
401    sml.boot.<arch>-<os>/basis.cm/basis.cm -- and so forth.
402    
403    [Note, there are some anchors in "pathconfig" that have no
404    corresponding sub-directory of the boot director.  Examples are
405    "root.cm", "cm", and so on.  The reason is that there are no stable
406    libraries whose description files are named using these anchors;
407    everything anchored at "$cm" is a group but not a library.]
408    
409  By the way, you will perhaps notice that there is no file  By the way, you will perhaps notice that there is no file
410          sml.boot.<arch>-<os>/basis.cm/basis.cm          sml.boot.<arch>-<os>/basis.cm/basis.cm
# Line 304  Line 415 
415  This mapping (from anchors to names in the boot directory) is the one  This mapping (from anchors to names in the boot directory) is the one
416  that will get frozen into the generated heap image at boot time.  that will get frozen into the generated heap image at boot time.
417  Thus, unless it is changed, CM will look for its libraries in the boot  Thus, unless it is changed, CM will look for its libraries in the boot
418  directory.  The aforementioned "testml" script will make sure that  directory.  The aforementioned "testml" script will make sure (by
419  the mapping is changed to the one specified in a new "pathconfig" file  setting the environment variable CM_PATHCONFIG) that the mapping be
420  which was created by makeml and placed into the test library  changed to the one specified in a new "pathconfig" file which was
421  directory.  It points all anchors to the corresponding entry in the  created by makeml and placed into the test library directory.  It
422  test library directory.  Thus, "testml" will let a new heap image run  points all anchors to the corresponding entry in the test library
423  with its corresponding new libraries.  directory.  Thus, "testml" will let a new heap image run with its
424    corresponding new libraries.
425    
426  Normally, however, CM consults other pathconfig files at startup --  Normally, however, CM consults other pathconfig files at startup --
427  files that live in standard locations.  These files are used to modify  files that live in standard locations.  These files are used to modify
# Line 326  Line 438 
438  before making the heap image.  Therefore, heap images generated by  before making the heap image.  Therefore, heap images generated by
439  makeml will look for their global pathconfig file in  makeml will look for their global pathconfig file in
440    
441          `pwd`/../../lib/pathconfig          ../../lib/pathconfig
442    
443    [Note: The "makeml" script will not re-set the CM_PATHCONFIG_DEFAULT
444    variable if it was already set before.  If it does re-set the
445    variable, it uses an absolute path name instead of the relative path
446    that I used for illustration above.]
447    
448  For example, I always keep my "good" libraries in `pwd`/../../lib --  For example, I always keep my "good" libraries in `pwd`/../../lib --
449  where both the main "install" script and the "installml" script (see  where both the main "install" script (in config/install.sh) and the
450  above) also put them -- so I don't have to do anything special about  "installml" script (see above) also put them -- so I don't have to do
451  my pathconfig file.  anything special about my pathconfig file.
452    
453  Once I have new heap image and libraries working, I replace the old  Once I have new heap image and libraries working, I replace the old
454  "good" image with the new one:  "good" image with the new one:
# Line 349  Line 466 
466  "installml" also patches the ../../lib/pathconfig file as necessary.  "installml" also patches the ../../lib/pathconfig file as necessary.
467    
468  Of course, you can organize things differently for yourself -- the  Of course, you can organize things differently for yourself -- the
469  path configuration mechanism should be sufficiently flexible.  path configuration mechanism should be sufficiently flexible.  If you
470    do so, you will have to set CM_PATHCONFIG.  This must be done before
471    you start sml.  If you want to change the pathname mapping at the time
472    sml is already running, then use the functions in CM.Anchor.
473    
474  * Libraries vs. Groups  * Libraries vs. Groups
475  ----------------------  ----------------------
# Line 369  Line 489 
489  other groups -- as long as all these other groups belong to the same  other groups -- as long as all these other groups belong to the same
490  owner library.  owner library.
491    
492  If you want to take a collection of files whose purpose fits that of a  Normally, collections of files that belong together should be made
493  library, then, please, make them into a library (i.e., not a group!).  into proper CM libraries.  CM groups (aka "library components") should
494  The purpose of groups is to deal with name-space issues _within_  be used only when there are namespace problems within a library.
 libraries.  
495    
496  Aside from the fact that I find this design quite natural, there is  Aside from the fact that I find this design quite natural, there is
497  actually a technical reason for it: when you stabilize a library  actually a technical reason for it: when you stabilize a library
# Line 394  Line 513 
513  keyword.  If the specification is missing (that's the "old" syntax),  keyword.  If the specification is missing (that's the "old" syntax),
514  then the the owner will be taken to be the interactive toplevel.  then the the owner will be taken to be the interactive toplevel.
515    
516  * Pervasive environment, core environment, the init group "init.cmi"  * Pervasive environment, core environment, the init library "init.cmi"
517  -------------------------------------------------------------------------  -------------------------------------------------------------------------
518    
519  CMB.make starts out by building and compiling the  CMB.make starts out by building and compiling the
520  "init group".  This group cannot be described in the "usual" way  "init library".  This library cannot be described in the "usual" way
521  because it uses "magic" in three ways:  because it uses "magic" in three ways:
522   - it is used to later tie in the runtime system   - it is used to later tie in the runtime system
523   - it exports the "core" environment   - it binds the "_Core" structure
524   - it exports the "pervasive" environment   - it exports the "pervasive" environment
525    
526  The pervasive environment no longer includes the entire basis library  The pervasive environment no longer includes the entire basis library
# Line 409  Line 528 
528  types).  types).
529    
530  CM cannot automatically determine dependencies (or exports) for the  CM cannot automatically determine dependencies (or exports) for the
531  init group source files, but it still does use its regular cutoff  init library source files, but it still does use its regular cutoff
532  recompilation mechanism.  Therefore, dependencies must be given  recompilation mechanism.  Therefore, dependencies must be given
533  explicitly.  This is done by a special description file which  explicitly.  This is done by a special description file which
534  currently lives in ../system/smlnj/init/init.cmi.  See the long comment  currently lives in smlnj/init/init.cmi (as an anchored path:
535  at the beginning of that file for more details.  "$smlnj/init/init.cmi").  See the long comment at the beginning of
536    that file for more details.
537  After it is built, smlnj/init/init.cmi can be used as an "ordinary" library  
538  by other libraries.  (This is done, for example, by the implementation of  After it is built, $smlnj/init/init.cmi can be used as an "ordinary"
539  the Basis library.)  Access to "smlnj/init/init.cmi" is protected by the  library by other libraries.  (This is done, for example, by the
540  privilege named "primitive".  Also, note that the .cmi-file is not  implementation of the Basis library.)  Access to
541  automatically recognized as as CM description file.  Therefore, it  "$smlnj/init/init.cmi" is protected by the privilege named
542  must be given an explicit member class:  "primitive".  Also, note that the .cmi-file is not automatically
543    recognized as as CM description file. ("cmi" should remind you of "CM
544    - Initial library".)  Therefore, it must be given an explicit member
545    class:
546    
547       smlnj/init/init.cmi : cm       $smlnj/init/init.cmi : cm
548    
549  * Autoloader  * Autoloader
550  ------------  ------------
# Line 442  Line 564 
564  properly configured.  properly configured.
565    
566  Two libraries get pre-registered at bootstap time: the basis library  Two libraries get pre-registered at bootstap time: the basis library
567  ("basis.cm") and CM itself ("minimal-cm.cm").  The latter is crucial:  ("$/basis.cm") and CM itself ("$smlnj/cm/minimal.cm").  The latter is
568  without it one wouldn't be able to register any other libraries  crucial: without it one wouldn't be able to register any other
569  via CM.autoload.  The registration of basis.cm is a mere convenience.  libraries via CM.autoload.  The registration of $/basis.cm is a mere
570    convenience.
571    
572  Here are some other useful libraries that are not pre-registered but  Here are some other useful libraries that are not pre-registered but
573  which can easily be made accessible via CM.autoload (or, non-lazily,  which can easily be made accessible via CM.autoload (or, non-lazily,
574  via CM.make):  via CM.make):
575    
576          smlnj/cm.cm             - provides the actual ("full") structure CM          $smlnj/cm.cm            - provides the actual ("full") structure CM
577                                    as described in the CM manual                                    as described in the CM manual
578          smlnj/cm/full.cm        - same as smlnj/cm.cm          $smlnj/cm/full.cm       - same as $smlnj/cm.cm
579          smlnj/compiler.cm       - provides "structure Compiler"          $smlnj/compiler.cm      - provides "structure Compiler"
580          smlnj/compiler/current.cm - same as smlnj/compiler.cm          $smlnj/compiler/current.cm - same as $smlnj/compiler.cm
581          smlnj/cmb.cm            - provides "structure CMB"          $smlnj/cmb.cm           - provides "structure CMB"
582          smlnj/cmb/current.cm    - same as smlnj/cmb.cm          $smlnj/cmb/current.cm   - same as $smlnj/cmb.cm
583          smlnj/compiler/all.cm   - provides "structure <Arch>Compiler" and          $smlnj/compiler/all.cm  - provides "structure <Arch>Compiler" and
584                                    "structure <Arch><OS>CMB" for various                                    "structure <Arch><OS>CMB" for various
585                                    values of <Arch> and <OS>                                    values of <Arch> and <OS>
586          smlnj-lib.cm            - the SML/NJ library          $smlnj-lib.cm           - the SML/NJ library
587    
588    [Note: The fact that $smlnj/compiler.cm is not among the
589    pre-registered libraries seems like an oversight and could lead to
590    some inconveniences to users who want to, for example, set compiler
591    flags.  However, pre-registration of this library significantly
592    increases the size of the heap image.  Moreover, since the library can
593    easily be loaded by giving the string as a command line argument, this
594    does not really appear to be a big burden to me.  Just create a shell
595    alias or a little wrapper script if you think you really need this.]
596    
597  * Internal sharing  * Internal sharing
598  ------------------  ------------------
# Line 562  Line 694 
694  big loss because path anchors make up for most of it.  Moreover,  big loss because path anchors make up for most of it.  Moreover,
695  stable libraries can now easily be moved to convenient locations  stable libraries can now easily be moved to convenient locations
696  without having to move large source trees at the same time. (See my  without having to move large source trees at the same time. (See my
697  new build/install.sh script for examples of that.)  new config/install.sh script for examples of that.)
698    
699  It is possible to simulate aliases (in a way that is safer than the  It is possible to simulate aliases (in a way that is safer than the
700  original alias mechanism).  For example, the root.cm file (which is the  original alias mechanism).  For example, the root.cm file (which is the
701  root of the whole system as far as CMB.make is concerned) acts as an  root of the whole system as far as CMB.make is concerned) acts as an
702  alias for smlnj/internal/intsys.cm.  In this case, root.cm is a group  alias for $smlnj/internal/intsys.cm.  In this case, root.cm is a group
703  to avoid having a (trivial) stable library file built for it.  to avoid having a (trivial) stable library file built for it.
704    
705  A library can act as an "alias" for another library if it has a  A library can act as an "alias" for another library if it has a
706  verbatim copy of the export list and mentions the other library as its  verbatim copy of the export list and mentions the other library as its
707  only member.  Examples for this are smlnj/cm.cm (for smlnj/cm/full.cm),  only member.  Examples for this are $smlnj/cm.cm (for
708  smlnj/compiler.cm (for smlnj/compiler/current.cm), etc.  $smlnj/cm/full.cm), $smlnj/compiler.cm (for $smlnj/compiler/current.cm),
709    etc.  The stable library file for such an "alias" is typically very
710    small because it basically just points to the other library.  (For
711    example, the file representing $smlnj/cm.cm is currently 234 bytes
712    long.)
713    
714  * Don't use relative or absolute pathnames to refer to libraries  * Don't use relative or absolute pathnames to refer to libraries
715  ----------------------------------------------------------------  ----------------------------------------------------------------
# Line 583  Line 719 
719  you do CMB.make().  If you use relative or absolute pathnames to  you do CMB.make().  If you use relative or absolute pathnames to
720  refer to library B from library A, you will be committed to keeping B  refer to library B from library A, you will be committed to keeping B
721  in the same relative (to A) or absolute location.  This, clearly,  in the same relative (to A) or absolute location.  This, clearly,
722  would be undesirable.  would be undesirable in many situations (although perhaps not always).

Legend:
Removed from v.632  
changed lines
  Added in v.643

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