                       SIMPLE LITTLE COMPILER
                       ======================

  Author:
    Rowan Crowe
    rowan@sensation.net.au
    Note: I'm no longer in fidonet.


UNZIPPING
=========

  If you didn't unzip with the -d switch, DELETE WHAT YOU'VE JUST
  UNZIPPED AND DO IT AGAIN. The zip file contains a directory structure
  that needs to be preserved.

  Here's an example of a command line to unzip the archive:

    pkunzip -d slc0001 c:\slc


WHAT IS SLC?
============

  SLC is a reasonably complete but very simple compiler. SLC stands for
  "Stupid Little Compiler", but I've decided to be a bit more
  constructive and rename it "Simple Little Compiler". As an experiment
  I decided to abandon the still somewhat kludgy parsing of the new
  MoonRock compiler (which hasn't been released) and instead use a stack
  method for evaluation. It is based on CALC (supplied with MoonRock and
  in a separate "compiler bits" archive), and generates code on the fly
  rather than attempting to optimise in intermediate form like CODEGEN
  does. This complete lack of optimisation is done deliberately to
  ensure the compiler is as simple as possible, yet still functional.
  The code is produces is VERY inefficient to look at and would probably
  make any competent assembly programmer burst into tears, but it works.

  The idea with this small and simple compiler is to write a set of
  library routines (this time in native SLC, not in 80x86 ASM like
  MoonRock's library), along with some necessary low level "glue" code
  in 80x86 format. Then, rewrite the compiler in native SLC. At this
  stage we have a complete compiler and set of library routines which
  are portable - only the low level glue code needs to be rewritten for
  a new processor or operating system, plus some modifications to the
  code generator. Of course, life is not as simple as that, but porting
  this compiler + library to another processor or OS will be a lot
  simple than say, trying to port MoonRock, which is written in
  QuickBASIC with an ASM library - definitely unportable material!

  At this stage the compiler generates something close to an output that
  can be assembled directly, but you may still need to edit the
  filename.asm file before it can be successfully assembled. Note that
  I'm using TASM as an assembler and did whatever I needed to in order
  to get it to work. I don't know how well it work with MASM. Remember -
  this is just a simple bootstrap to get the second version working!


ABOUT THE LANGUAGE
==================

  SLC looks a little like C with some BASICish looking keywords thrown
  in. The basic (pun unintended) elements are:

    [global] char|int [*]variablename

    [global|extern] char|int|void functionname (parameters) {
      <code here>
    }

    functiontocall([parm1, [parm2 ...]])

    variablename = expression

    if (expression) {
       <conditional code here>
    }

    if (expression) {
       <conditional code here>
    } else {
       <conditional code here>
    }

    repeat {
       <conditional code here>
    } until (expression)

    while (expression) {
       <conditional code here>
    }

    switch (expression) {
      case (expression) {
        ...
      }
      case (expression) {
        ...
      }
      case else {
        ...
      }
    }

    asm <line of asm>

    return (expression)

  "expression" is a set of numbers and/or variables with operators, such
  as <, >, ==, &, |, !, +, -, *, /

  &   bitwise AND             |   bitwise OR
  &&  logical AND             ||  logical OR
  =   assignment              ==  equal to
  <=  lower than or equal     =>  higher than or equal
  <<  shift left              >>  shift right
  !=  not equal to

  (note: don't get '=' and '==' confused! '=' assigns a value to a
  variable, '==' is used in evaluation expressions)

  That's about it. Everything else is a function that you write yourself
  (or one that is included in the standard library). See the sample
  files for an idea of how it all goes together.


LIBRARY FUNCTIONS
=================

  See LIB.DOC for documentation.


CAVEATS
=======

  Some caveats for this bootstrap:

    1. Use the above style of braces format. The compiler may not like
       deviations from this such as an opening brace on a new line.

    2. Be careful when using /* comments */ inline or even at the end of
       a line. The code generator seems to get a little confused
       sometimes and emits some strange (but still valid) code, possibly
       because it sees the leading '/' and thinks it's a division.
       Solution: put comments on a line by themselves.


HOW TO USE
==========

  This compiler has a reasonable amount of error checking but it will
  still allow some strange constructs without complaining. To use it,
  simply specify the filename on the commandline:

    C:\SLC>slc hello
    Simple Little Compiler v0.03 [DOS]; Copyright (C) 1998-2000 by Rowan Crowe.

    *** info: main() function detected, will call link at end of compile.

    processed 9 line(s) successfully, outfile is 'hello.asm'
    remaining memory is 62158 bytes.

    D:\DOS\COMMAND.COM /C tasm hello /t
    D:\DOS\COMMAND.COM /C tlink alib\startup+hello,hello,,slc/t

  The compiler will automatically call TASM and optionally, TLINK if the
  main() function is detected.

COMPILING THE LIBRARY FUNCTIONS
===============================

  Compiling the library functions is not required unless you make
  changes to the source in ALIB or LIB. To recompile the library
  functions run MAKELIB.BAT which is in the root SLC directory. To do
  this you will require the LIB util, which you probably have anyway.
  This is a simple batch file that:

    * assembles all files in alib\  (library - ASM)
    * compiles all files in lib\    (library - SLC)
    * rebuilds SLC.LIB


COMPILING THE COMPILER
======================

  Compiling SLC itself is not necessary unless you make changes to
  SLC.MOO. To recompile the source for SLC you'll need the MoonRock
  compiler, which is at http://www.rowan.sensation.net.au/moonrock.html.
  To compile use:

    mrc slc
      or
    mrc slc !DEBUG


CONCLUSION
==========

  I hope this compiler and included sample source files will be of some
  use to you. Watch out for the native coded version!

