home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sa104os2.zip / README.1ST < prev    next >
Text File  |  1995-02-17  |  13KB  |  304 lines
  1. Copyright (C) International Computer Science Institute, 1994.  COPYRIGHT  
  2. NOTICE: This code is provided "AS IS" WITHOUT ANY WARRANTY and is subject 
  3. to the terms of the SATHER LIBRARY GENERAL PUBLIC LICENSE contained in    
  4. the file "Doc/License" of the Sather distribution.  The license is also   
  5. available from ICSI, 1947 Center St., Suite 600, Berkeley CA 94704, USA.  
  6. -----> Please email comments to "sather-bugs@icsi.berkeley.edu". <-----
  7.  
  8. Comments on this port to "native" OS/2 to "Norm.Pleszkoch@theedgebbs.com"
  9.  
  10.  
  11.  
  12. Warnings:
  13.  
  14.    This package must be unzipped with directory structure -- Some BBS upload
  15.    checkers flatten out the directory structure, which gives you 300 files in
  16.    whatever directory you unzip from.  Before unzipping the inner file 
  17.    (SATHR104.ZIP), read the Installation Section below.
  18.  
  19.    The Boehm garbage collector (as previously ported to OS/2) doesn't check
  20.    DLLs for pointers to allocated memory blocks.  Play safe and do static
  21.    linking (the default) of your Sather programs.  Moreover, I have
  22.    further specialized the garbage collector for the specific EXE format
  23.    produced by the makefiles produced by this port of Sather.  If you want
  24.    to lift the standalone Boehm garbage collector for other things, you
  25.    probably want to undo the changes I made.  They are all marked -- see
  26.    below.
  27.  
  28.  
  29.  
  30. Acknowledgements:
  31.  
  32.    Firstly, to Steve Omohundro and David Stoutamire, the authors and probably
  33.    prime movers of Sather.  Stoutamire is probably the mysterious "Dave" who
  34.    signs a lot of the READMEs in the package??  Next, to Hans Boehm for his
  35.    contribution of the garbage collector.  During my hassles (which were
  36.    finally attributed to a bug in the ICC compiler -- see below), I was always
  37.    suspecting his exotic garbage collector.  Sorry about that.  Finally a 
  38.    deep bow to Ari Huttunen who made these two products work in OS/2 under an
  39.    EMX environment.  My only problems here were installing the "Hobbes, Ready
  40.    to Run" EMX environment.  Without being able to slip in the CD (oh, no
  41.    more music) and using the Huttunen port to compile my changes (you see,
  42.    the Sather compiler is written in Sather), I couldn't have made this
  43.    "native" OS/2 port.
  44.  
  45.  
  46.  
  47. What is a "native" OS/2 port of Sather?
  48.  
  49.    This is the standard Sather 1.0.4 distribution modified so that it can run
  50.    in OS/2 (HPFS or FAT), using the standard OS/2 command processor and the
  51.    IBM C Set++ suite of tools (which are required because the Sather compiler
  52.    emits C code which must be compiled) including "nmake".
  53.  
  54.    The only machine that I know this works on is my own.  It is a 486 clone,
  55.    with WARP (shrink wrap except for upgraded display driver and cdrom driver)
  56.    and 16M of RAM and a 64M pre-allocated swapper file.  I have C Set++ V2.1,
  57.    with fixes at the CTC00011 (compiler and tools), CTU00003 (utilities) and
  58.    CTM00009 (libraries) levels.  Your mileage ...
  59.  
  60.  
  61.  
  62. OK, how do I install it?
  63.  
  64.    You are reading this, so you have probably unzipped the wrapper,
  65.    "SA104OS2.zip".  Now you have this "README.1st" and "SATHR104.zip".
  66.  
  67. *  First check to make sure the directory structure has not been removed:
  68. *
  69. *      > unzip -l sathr104.zip
  70. *
  71. *   or
  72. *
  73. *      > pkunzip -vb sathr104.zip
  74.  
  75.    to list the contents of the zip file.  Each file listed should start
  76.    with  "sather/" or "^sather/" or "SATHER/" or "^SATHER/" without the quotes.
  77.    If not, then you can't use this package.  Please ask the sysop of the BBS
  78.    you downloaded from to destroy the file.
  79.  
  80.    Now decide where you want the top level Sather directory (which just
  81.    happens to be "Sather"} to be.  Suppose it is in D:\PKGS.  Then you
  82.  
  83.       > d:
  84.       > cd \pkgs
  85.  
  86.    If you have Infozip's unzip (which defaults to reconstructing
  87.    sub-directories), then
  88.  
  89.       > unzip <full path name to SATHR104.zip>
  90.  
  91. *  If using PKUNZIP, then
  92. *
  93. *     > pkunzip -d <full path name to SATHR104.zip>
  94.  
  95.    If you plan to upload this to another BBS, then delete SATHR104.zip.
  96.    Otherwise delete both the zip files.  That is, upload SA104OS2.zip.
  97.  
  98. *  From now on I will use "SATHER" to designate the top level Sather
  99. *  directory.  For the preceding example, SATHER == d:\pkgs\sather.
  100.  
  101.    Edit SATHER\makefile and modify line 27 (or thereabouts) to read:
  102.  
  103.        SHOME= SATHER
  104.  
  105.    or continuing the example:  SHOME= d:\pkgs\sather
  106.  
  107.    Now, cd to SATHER and build the Sather compiler:
  108.  
  109.        > cd SATHER
  110.        > nmake all
  111.  
  112.    This will show all the steps of the makefile.  To see much less:
  113.  
  114.        > nmake all silent=
  115.  
  116.    To see more:
  117.  
  118.        > nmake all verbose=
  119.  
  120.    I typically use:
  121.  
  122.        > nmake all verbose= > make.log
  123.  
  124.    Here's what is going to happen (if all works).
  125.     1. Build the garbage collector in SATHER\system\gc\gc.lib  (3 minutes)
  126.     2. Build Sather support in SATHER\system\base.lib          (3 minutes)
  127.     3. Compile the boot version of the Sather compiler,
  128.        SATHER\boot\cs.exe from source in SATHER\boot\cs.cod    (15 minutes)
  129.     4. Use boot compiler to compile your Sather compiler,
  130.        SATHER\compiler\cs.exe from source in SATHER\compiler   (30 minutes)
  131.     5. Use your Sather compiler to compile (then execute)
  132.        some library tests in SATHER\test                       (3 minutes)
  133.  
  134.    If you'd really like to exercise your compiler, do
  135.  
  136.        > nmake testall
  137.  
  138.     1. through 5., if not already done.
  139.     6. Build a special version of Sather compiler using your
  140.        Sather compiler.                                        (45 minutes)
  141.     7. Repeat using result of 6.                               (45 minutes)
  142.     8. Repeat using result of 7.                               (45 minutes)
  143.     9. Echo instructions for what files to compare.
  144.  
  145.    The output of steps 7. and 8. should be identical.
  146.  
  147.    If you have problems during step 1. or 2. you probably don't
  148.    have C Set ++ installed properly (things like include/library
  149.    search paths).
  150.  
  151.    If you have problems with subsequent steps, I'd like to hear from you.
  152.  
  153.  
  154.  
  155. It's installed.  Now what?
  156.  
  157.    Print and/or read the docs in SATHER\doc.
  158.  
  159.    Put the following line in your config.sys file:
  160.  
  161.       SET SATHER_COMMANDS=-home SATHER -com SATHER\library\base.prm
  162.  
  163.    where the latter two "SATHER" are full path to top level Sather directory.
  164.  
  165.    If you never intend to modify or rebuild the compiler, you can delete a
  166.    bunch of stuff.  The following is all that is really needed to use the
  167.    Sather compiler on your own sather code (which can be located anywhere).
  168.  
  169.    ESSENTIAL files:
  170.         SATHER\Library\*.*
  171.         SATHER\Compiler\cs.exe    (which can be put anywhere on your PATH)
  172.         from SATHER\System:  *.lib, *.h, config, macros, forbid, externs, iters
  173.         from SATHER\System\GC:  *.lib, *.h
  174.  
  175.  
  176.  
  177. What are all of the command line parameters for cs.exe?
  178.  
  179.    They are documented in SATHER\doc\man\cat1\cs.1
  180.  
  181.    Note that the value of the SATHER_COMMAND environment variable is added
  182.    to the set of command line parms given to cs.exe.
  183.  
  184.    Note also that the "-com file" just says treat the contents of "file" as
  185.    command line parms.
  186.  
  187.    You can set the stack size for a sather program that you compile to nnn with:
  188.           -C_flag /B/STACK:nnn
  189.  
  190.  
  191. I know a bit about Sather.  What have you changed?
  192.  
  193.    All changes to .c, .h, and .sa files have been signed with the character
  194.    string "-- NLP".  The modifications are of the form comment out (and sign)
  195.    old line then insert (and sign) new line.  Of course my editor inserts
  196.    spaces for tabs and uses CR-LF in place of LF for new lines.
  197.  
  198.    1.  Some files were added.
  199.        SATHER\readme.1st (this file);
  200.        SATHER\system\deltree.exe (freeware replacement for "rm -r"
  201.               by Mark Kimes.  Only used in the build makefiles.),
  202.        SATHER\system\buggy.c (the file submitted to IBM for ICC bug),
  203.        SATHER\system\buggyfix.c (the workaround applied to buggy.c),
  204.        SATHER\tr93-064.ps (document on the Sather type and class system),
  205.        makefile.ibm (in a number of directories).
  206.        SATHER\system\gc\junk.c (to see some critical macro values).
  207.  
  208.    2.  All files and directories were renamed (if required) to conform to the
  209.        FAT 8.3 naming conventions.  Of particular interest: *.code -> *.cod;
  210.        *.command -> *.prm (in OS/2 both .cmd and .com denote executables).
  211.  
  212.    3.  The entire SATHER\boot\cs.cod directory was rederived from the other
  213.        changes described here.
  214.  
  215.    4.  While stewing over a couple of problems I did a seek and destroy of all
  216.        "bad" returns (i.e., no return immediately prior to the final "end;") in
  217.        the files SATHER\compiler\*.sa and SATHER\Library\*.sa (a couple may
  218.        have fixed -or introduced- buglets, grep for "-- NLP ?" and "-- NLP !").
  219.        This rote activity allowed me to examine the code without looking for a
  220.        solution to my overall problems, a mind trick of mine.
  221.  
  222.    5.  Most all other changes to .sa files are confined to options.sa and be.sa
  223.        which do the following:
  224.  
  225.           Accept "\" in place of "/" as file separator.
  226.           Output "\" in place of "/" in makefile link libs only.
  227.           Change references ".o" -> ".obj"; ".a" -> ".lib"; ".code" -> ".cod".
  228.           Makefile macro references in parens instead of braces.
  229.           No default a.out -> error message instead.
  230.           Add ".exe" to -o name.
  231.           Emit a makefile suitable for nmake.
  232.           Change emitted globals.h:
  233.  
  234.             extern const TYPE (*function..  =>  extern TYPE (* const function..
  235.             (ICC says the former declares functions that return const)
  236.  
  237.             When TYPE was not present, ICC couldn't figure out to use int, so
  238.             extern const (*function... => extern int (* const function...
  239.  
  240.           Similar changes in emitted globals.c
  241.  
  242.           Changes to general emitted code:
  243.  
  244.              ICC complained about pointer conversions in constant expressions
  245.              when "boxed" variables were declared w/initializers.
  246.              Changed so that declare emitted first, followed by assignment.
  247.  
  248.              The killer bug workaround. ICC (at times) gens code that clobbers
  249.              the stack when:
  250.  
  251.                    TYPE tk; /* an automatic */
  252.                    ...
  253.                    tk = func_returning_struct().component;
  254.  
  255.                 added file level static temp vars for such returned structs of
  256.                 the form struct_typedef_name_blob (similar to ..._zero) and
  257.                 replaced affected assignments with code like:
  258.  
  259.                    tk = (..._blob = func_returning_struct()).component;
  260.  
  261.                 See SATHER\system\buggy.c and buggyfix.c for a better picture.
  262.  
  263.           Changed all abort() -> exit(16).  Thought I had problems missing
  264.           unflushed stdout.  In OS/2 exit() and abort() have same behavior
  265.           except for flushing buffers.
  266.  
  267.           OS/2 mkdir() takes one arg, so changed code in file.sa.
  268.  
  269.           Noticed that FILE::buffer_size was passing the system a GC_malloc'd
  270.           FSTR (but maybe not - see str.c next) for a buffer. Thought maybe the
  271.           system kept this pointer in a place that gc couldn't see, so changed
  272.           code so that the system allocates the requested buffer.
  273.  
  274.    6.  SATHER\system\*.c and *.h
  275.  
  276.           str.c -    changed a malloc() (?? nary a free() to be found anywhere)
  277.                      to GC_malloc().
  278.  
  279.           misc.c -   added some code to support the other changes listed here.
  280.                      added a rint() hack.
  281.                      changed GC_malloc_atomic() to GC_malloc(), just in case.
  282.  
  283.           header.h - added a few includes for system prototypes.
  284.  
  285.    7.  SATHER\system\gc\*.c
  286.  
  287.           mark.c -    fixed a preprocessor warning on #endif
  288.  
  289.           os_dep.c -  added a missing fclose().
  290.                       modified GC_register_data_segments() to take advantage
  291.                       of the fact that Sather's generated .exe's
  292.                       have one writable segment with stack allocation at
  293.                       high end and static/extern storage at low end.
  294.  
  295.                       The more general approach gave the whole segment,
  296.                       the change just gives the static/extern part.
  297.  
  298.           makefiles - All build and generated makefiles override the default
  299.                       linker alignment (16 bits) to (32 bits).
  300.  
  301. Now I'm going to sit down and play with Sather.
  302.  
  303. Norm Pleszkoch
  304.