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 537, Fri Feb 18 17:20:16 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: 2/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      - The SML'97 basis library    * $/basis.cm                          SML'97 Basis Library (pre-loaded)
23          - cm-hook.cm    - an internal library for organizational purposes    * $/smlnj-lib.cm                      SML/NJ Utility Library
24          - cm-lib.cm     - the library that implements CM's functionality    * $/html-lib.cm                       SML/NJ HTML Library
25          * comp-lib.cm   - a helper library for the compiler, MLRISC, and CM    * $/pp-lib.cm                         SML/NJ Pretty-print Library
26          * full-cm.cm    - the library that exports the public interface to  
27                            the compilation manager (i.e., structure CM)    * $/ml-yacc-lib.cm                    SML/NJ ML-Yacc runtime library
28          * minimal-cm.cm - exports a reduced version of structure CM;  
29                            this one is pre-registered at the top level    * $smlnj/compiler/{alpha32,hppa,ppc,sparc,x86}.cm
30          * host-cmb.cm   - the library that exports the public interface to                                          cross-compiler libraries, exporting
31                            the bootstrap compiler (i.e., structure CMB)                                          structure <Arch>Compiler
32          - host-compiler-0.cm    * $smlnj/compiler/current.cm          structure Compiler (current arch)
33                          - an internal library for organizational purposes    * $smlnj/compiler/all.cm              all cross-compilers and all cross-CMBs
34          * host-compiler.cm  
35                          - the library that exports the public interface to    * $smlnj/cm/minimal.cm                minimal CM (pre-loaded)
36                            the visible compiler (i.e., structure Compiler)    * $smlnj/cm/full.cm                   full structure CM (see manual)
37          - intsys.cm     - an internal library for organizational purposes    * $smlnj/cm/tools.cm                  CM tools library
38                            (In fact, its the "root" of the main hierarchy.)  
39          * ml-yacc-lib.cm - needs no further comment    * $smlnj/cmb/{alpha32,hppa,ppc,sparc,x86}-unix.cm
40          * smlnj-lib.cm  - needs no further comment                                          cross-bootstrap-compilers for Unix
41          * <arch>-compiler.cm - exports the Compiler structure for the                                          (structure <Arch>UnixCMB)
42                             given architecture (<Arch>Compiler).    * $smlnj/cmb/ppc-macos.cm             ...for Mac (structure PPCMacosCMB)
43          * <arch>-<os>.cm - exports <Arch><OS>CMB for the given architecture-    * $smlnj/cmb/x86-win32.cm             ...for Windoze (structure X86Win32CMB)
44                             OS combination.    * $smlnj/cmb/current.cm               structure CMB (current arch/os)
45          * target-compilers.cm  
46                          - library exporting target-specific versions of    * $smlnj/compiler.cm                  abbrev. for $smlnj/compiler/current.cm
47                            structure Compiler and of structure CMB.    * $smlnj/cm.cm                        abbrev. for $smlnj/cm/full.cm
48                            This is a summary of all the <arch>-compiler.cm    * $smlnj/cmb.cm                       abbrev. for $smlnj/cmb/current.cm
49                            and <arch>-<os>.cm libraries above.  
50                            (The existence of these libraries is the moral    * $comp-lib.cm                        Utility library for compiler
51                             equivalent of "CMB.retarget" in the old CM.)  
52          * viscomp-core.cm - library that implements the machine-independent    - $smlnj/viscomp/core.cm              Compiler core functionality
53                            core of the compiler.    - $smlnj/viscomp/{alpha32,hppa,ppc,sparc,x86}.cm
54          * viscomp-<arch>.cm - library that implements the visible compiler                                          Machine-specific parts of compiler
55                             for a given architecture.  
56      - $smlnj/internal/{intsys,cm-lib,cm-hook,host-compiler-0}.cm
57                                            Glue that holds the interactive system
58                                            together
59    
60      * $MLRISC/{MLRISC,Control,Lib,ALPHA,HPPA,PPC,SPARC,IA32}.cm
61                                            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
67      * ${grm,lex,burg}-ext.cm              CM plug-in libraries for common file
68                                            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 "host-cmb.cm";          CM.autoload "$smlnj/cmb.cm";
88    
89  after you start sml.  after you start sml.  Alternatively -- and perhaps more conveniently --
90    you can provide "$smlnj/cmb.cm" as a command-line argument to sml:
91    
92  * Compiling the compiler -- a two-step procedure        $ sml '$smlnj/cmb.cm'
 ------------------------------------------------  
93    
94  Until now (with the old CM), once we managed to run CMB.make() to  (Be sure to protect the dollar symbol which usually has its own
95  completion we had a directory full of binfiles that were ready to be  special meaning to the shell.)
 used by the boot procedure.  This is no longer the case.  
   
 The boot procedure now wants to use stable libraries (except for the  
 part that makes up the pervasive environment).  Having stable  
 libraries around during development of these very libraries would be a  
 bit annoying because if CM sees a stable library it will no longer  
 bother to check the corresponding source files -- even if they have  
 changed.  Therefore, libraries are not stabilized until you think you  
 are ready for that.  Thus, you should run:  
   
         CMB.make ();  
   
 until you no longer get compile errors.  CMB.make will return true in  
 this case.  Then you say:  
   
         CMB.deliver ();  
   
 This command creates a second directory parallel to the "bin"  
 directory -- the "boot" directory.  It will hold everything necessary  
 to bootstrap a new heap image.  You will probably find that  
 CMB.deliver() compiles a number of additional files even though  
 CMB.make completed successfully.  This is because CMB.make compiles  
 just those modules that will actually go into the heap image, but  
 CMB.deliver must also build the remaining files -- files that are part  
 of libraries to be stabilized but which are not used by the compiler.  
96    
97  You can reduce the number of extra files compiled and stabilized  * Compiling the compiler
98  during CMB.deliver at the expense of not building any cross-compilers.  ------------------------
 For that, say  
         #set (CMB.symval "LIGHT") (SOME 1);  
 before running CMB.deliver.  
99    
100  After you have made the boot directory, if you want to continue  We are now back to the old scheme where a call to CMB.make() suffices to
101  developing the compiler (i.e., make changes to some sources,  build a bootable set of files (libraries in our case).  CMB.make maintains
102  recompile, etc.), you must first get rid of that boot directory.  two parallel hierarchies of derived files:
 Running the "makeml" script (see below) will automatically remove the  
 boot directory.  
103    
104  The names of "bin" and "boot" directories are    1. the binfile hierarchy ("binfiles"), containing compiled objects for
105         each individual ML source file; this hierarchy is rooted at
106          <prefix>.bin.<arch>-<opsys>
107      2. the stable library hierarchy ("boot files"), containing library files
108         for each library that participates in building SML/NJ; this hierarchy
109         is rooted at
110          <prefix>.boot.<arch>-<opsys>
111    
112          <prefix>.bin.<arch>-<os>  The default for <prefix> is "sml".  It can be changed by using
113    CMB.make' with the new <prefix> as the optional string argument.
114    
115  and  CMB.make reuses existing bootfiles after it has verified that they are
116    consistent with their corresponding binfiles.  Bootfiles do not need
117    to be deleted in order for CMB.make to work correctly.
118    
119          <prefix>.boot.<arch>-<os>  To bootstrap a new system (using the runtime system boot loader), the
120    bootfiles _must_ be present, the binfiles need not be present (but
121    their presence does not hurt either).
122    
123  respectively, with "sml" being the default for <prefix>.  To change  You can reduce the number of extra files compiled and stabilized
124  the prefix, use CMB.make' and CMB.deliver' with the new prefix  during CMB.make at the expense of not building any cross-compilers.
125  provided as the optional string argument to these functions.  For that, say
126            #set (CMB.symval "LIGHT") (SOME 1);
127    before running CMB.make.
128    
129  * Making the heap image  * Making the heap image
130  -----------------------  -----------------------
# Line 129  Line 137 
137  The "feel" of using makeml should be mostly as it used to.  However,  The "feel" of using makeml should be mostly as it used to.  However,
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 also move its associated  1. The script will make a heap image and build a separate library directory
141     libraries into a separate 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 142  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  4. Unless you use "-rebuild", makeml will delete the boot directory     [Note: When the -rebuild option is specified, then the boot procedure
154     (thus readying you for further "CMB.make();" runs).      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.
162    
163  * Testing a newly generated heap image  * Testing a newly generated heap image
164  --------------------------------------  --------------------------------------
# Line 151  Line 166 
166  If you use a new heap image by saying "sml @SMLload=..." then things  If you use a new heap image by saying "sml @SMLload=..." then things
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 new CM will look for its stable libraries in places  about it, the newly booted system will look for its stable libraries
170  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.  The "testml" script that you also find here will run the heap  image.  (Actually, only the directory hierachy is separate, the
177  image and instruct it to look for its libraries in that new library  library files themselves are hard links.)  The "testml" script that
178  directory.  you also find here will run the heap image and instruct it to look for
179    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 180  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.deliver, you should say  Thus, after a successful CMB.make, you should say
210    
211          ./makeml          ./makeml
212    
# Line 199  Line 223 
223  * Cross-compiling  * Cross-compiling
224  -----------------  -----------------
225    
226  All cross-compilers live in the "target-compilers.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 "target-compilers.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 229  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 <arch>-compiler.cm or <arch>-<os>.cm.  are interested in by auto-loading $smlnj/compiler/<arch>.cm or
259    $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
265    argument to the sml command:
266    
267        $ sml '$smlnj/compiler/all.cm'
268    
269    or
270    
271        $ 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  --------------------  --------------------
285    
# 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:
455    
456    mv <image>.<arch>-<osvariant> ../../bin/.heap/sml.<arch>-<osvariant>    mv <image>.<arch>-<osvariant> ../../bin/.heap/sml.<arch>-<osvariant>
457    
458  and then:  After this you must also move all libraries from <image>.libs/* to their
459    corresponding position in ../../lib.
   rm -r ../../lib/*.cm  
   mv <image>.libs/*.cm ../../lib  
460    
461  For convenience, there is a script called "installml" that automates  Since this is cumbersome to do by hand, there is a script called
462  this task.  Using the script has the added advantage that it will not  "installml" that automates this task.  Using the script has the added
463  clobber libraries that belong to other than the current architecture.  advantage that it will not clobber libraries that belong to other than
464  (The rather heavy-handed "rm/mv" approach above will delete all stable  the current architecture.  (A rather heavy-handed "rm/mv" approach
465  libraries for all architectures.)  "installml" also patches the  will delete all stable libraries for all architectures.)
466  ../../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 371  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 384  Line 501 
501  library, n for n sub-groups), there will be just one file representing  library, n for n sub-groups), there will be just one file representing
502  the one stable archive (per architecture/os) for the whole thing.  For  the one stable archive (per architecture/os) for the whole thing.  For
503  example, I structured the standard basis into one library with two  example, I structured the standard basis into one library with two
504  sub-groups, but once you compile it (CMB.deliver) there is only one  sub-groups, but once you compile it (CMB.make) there is only one
505  stable file that represents the whole basis library.  If groups were  stable file that represents the whole basis library.  If groups were
506  allowed to appear in more than one library, then stabilization would  allowed to appear in more than one library, then stabilization would
507  duplicate the group (its code, its environment data structures, and  duplicate the group (its code, its environment data structures, and
# Line 396  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 (or CMB.deliver) 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 builds the "core" environment   - it binds the "_Core" structure
524   - it builds 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
527  but only non-modular bindings (top-level bindings of variables and  but only non-modular bindings (top-level bindings of variables and
528  types).  types).
529    
530  CM cannot automatically determine dependencies for the init group  CM cannot automatically determine dependencies (or exports) for the
531  source files, but it still does use its regular cutoff recompilation  init library source files, but it still does use its regular cutoff
532  mechanism.  Therefore, dependencies must be given explicitly.  This is  recompilation mechanism.  Therefore, dependencies must be given
533  done by a special description file which currently lives in  explicitly.  This is done by a special description file which
534  Init/init.cmi.  See the long comment at the beginning of that file for  currently lives in smlnj/init/init.cmi (as an anchored path:
535  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, init.cmi can be used as an "ordinary" library by  
538  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 "init.cmi" is protected by the  library by other libraries.  (This is done, for example, by the
540  privilege named "primitive".  implementation of the Basis library.)  Access to
541    "$smlnj/init/init.cmi" is protected by the privilege named
542    "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
548    
549  * Autoloader  * Autoloader
550  ------------  ------------
551    
552  The new system heavily relies on the autoloader.  As a result, almost  The new system heavily relies on the autoloader.  As a result, almost
553  no static environments need to get unpickled at bootstap time.  The  no static environments need to get unpickled at bootstrap time.  The
554  construction of such environments is deferred until they become  construction of such environments is deferred until they become
555  necessary.  Because of this, I was able to reduce the size of the heap  necessary.  Thanks to this, it was possible to reduce the size of the
556  image by more than one megabyte (depending on the architecture).  The  heap image by more than one megabyte (depending on the architecture).
557  downside (although not really terribly bad) is that there is a short  The downside (although not really terribly bad) is that there is a
558  wait when you first touch an identifier that hasn't been touched  short wait when you first touch an identifier that hasn't been touched
559  before.  (I acknowledge that the notion of "short" may depend on your  before.  (I acknowledge that the notion of "short" may depend on your
560  sense of urgency. :-)  sense of urgency. :-)
561    
# Line 440  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          full-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          host-compiler.cm        - provides "structure Compiler"          $smlnj/cm/full.cm       - same as $smlnj/cm.cm
579          host-cmb.cm             - provides "structure CMB"          $smlnj/compiler.cm      - provides "structure Compiler"
580          target-compilers.cm     - provides "structure <Arch>Compiler" and          $smlnj/compiler/current.cm - same as $smlnj/compiler.cm
581            $smlnj/cmb.cm           - provides "structure CMB"
582            $smlnj/cmb/current.cm   - same as $smlnj/cmb.cm
583            $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 497  Line 634 
634          defined(<namespace> <name>)          defined(<namespace> <name>)
635      is true if any of the included members preceeding this clause exports      is true if any of the included members preceeding this clause exports
636      a symbol "<namespace> <name>".      a symbol "<namespace> <name>".
637    - Within the "exports" section of the description (i.e., before "is):    - Within the "exports" section of the description (i.e., before "is"):
638      The same expression is true if _any_ of the members exports the      The same expression is true if _any_ of the members exports the
639      named symbol.      named symbol.
640      (It would be more logical if the exports section would follow the      (It would be more logical if the exports section would follow the
# Line 557  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
700    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
702    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.
704    
705    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
707    only member.  Examples for this are $smlnj/cm.cm (for
708    $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  ----------------------------------------------------------------  ----------------------------------------------------------------
716    
717  Don't use relative or absolute pathnames to refer to libraries.  If  Don't use relative or absolute pathnames to refer to libraries.  If
718  you do it anyway, you'll get an appropriate warning at the time when  you do it anyway, you'll get an appropriate warning at the time when
719  you do CMB.deliver().  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.537  
changed lines
  Added in v.643

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