*z80 #H z80
*type #H z80
*type1 #H z80
*type3 #H z80
*stack
*makestack
*a68makestack
*a68stack
*a68stack32
NEW.A68MAKESTACK Command
Form:            NEW.A68MAKETSTACK "size,to/a/k"
Purpose:         To create a segment for an ALGOL68C program's stack
Author:          RDE
Specification:

If the stack requirements of an Algol68C program are known in advance then
the command NEW.A68MAKESTACK can be used to create a stack to include with
an Algol68C program when linking.  If the stack has not been so included its
size may be varied before execution using the :RDE.A68STACK32 command.
Note that the Algol68C stack is NOT the same as the BCPL stack.
Note also that the A68C command needs a BCPL stack of 1000 (use the STACK
command).

SIZE is the size of the stack needed and TO names the file into which the
stack segment will be written.  This file is used when linking an ALGOL68C
program to provide the stack.  See HELP A68C EXAMPLE
*link #H lked
*lib
*library
The Algol68C libraries are in different places depending upon the object
machine:
        Machine                         Library

        68000 (16-bits)                 SYS:a68c.68000.lib.mod16
        68000 (32-bits)                 SYS:a68c.68000.lib.mod32
        LSI4                            SYS:a68c.LSI4.lib.mod

The TRIPOS linkage editor LKED is used to link a program with a library -
see HELP A68C EXAMPLE (note that LKED must be run on the object machine).
*example
*demo
*demonstration
The following details the compilation, linking and running of a simple
Algol68C program: starting from a 68000 TRIPOS.

        1> INPUT prog1
        # the first part of the program .. #

        INT x = 42;

        ENVIRON EXAMPLE
        /*
        1> INPUT prog2
        USING EXAMPLE FROM "envprog"

        # the last part of the program .. #

        print (x)
        /*
        1> LIBRARY :RDE.LOADER32
        1> STACK 1000
        1> A68C prog1 ENVOUT envprog OBJ objprog
        ALGOL68C Release 1.303
        Unused space 10487

        Z68000 Version 1.8
        Program=20 Data=12
        1> A68MAKESTACK 500 TO prog-stack
        1> A68C prog2 TO progbin OBJIN objprog,prog-stack
        ALGOL68C Release 1.303
        Unused space 10522

        Z68000 Version 1.8
        Program=20 Data=12
        TRIPOS 32 Bit Linkage Editor Version 1.0
        Linking complete - maximum code size = 8047 words
        1> progbin
        42
        1>

Code for the LSI4 can be generated by using MC=LSI4 with each A68C command.
*68000 #N ..
*m68k #N ..
*command #N ..
** ..
ALGOL68C compilers

The Algol68C system on LSI4 TRIPOS is documented in the documentation folder
under "Algol68C on the LSI4 computer". An example of how to use it is available
using HELP ALGOL68C EXAMPLE. It is currently impossible to compile Algol 68C
programs on LSI4 TRIPOS:  68000 TRIPOS, CAP or the IBM 370 must be used.
For information about Algol68C on Z80s use HELP Z80 A68C.
For an example of how to run Algol68C programs compiled on CAP on an LSI4
use HELP A68C EXAMPLE.

*68000
*m68k
*command
**
NEW.A68C Command

This command is available only on 68000 TRIPOS.
The current system uses 32 bit INTegers (and BITS) and 32-bit addresses,
although it can produce code for 16 bit integers.  REALs are NOT implemented
yet.

To use the compiler on a 68000 type:

  LIBRARY :rde.loader32
  STACK   1000
  :RDE.A68STACK32 2500

(The 2500 is the amount of stack, in BCPL words, that will be available to
Algol68C programs when they run.  It should increased for programs which
use large arrays, etc.  This stack size does not affect the compiler, which
has its stack bound in).

Form:           NEW.A68C   [FROM] source [VER ver] [ZCODE zcode] [OPT opt]
                           [ENVOUT envout] [HEAP integer] [XREF xref]
                           [INIT init] [MC machine] [Z translator]
                           [ZOPT opt] [OBJ object] [OBJIN objs]
                           [LIBRARY libraries] [MAP map] [TO loadmodule]
Purpose:        To compile an Algol68C program for vaious machines.
Author:         RDE + compiler authors
Specification:

The parameters have the following meanings:

FROM            Algol68C source.

VER             File for compiler, translator and linkage editor verification
                output (eg. compiler error messages).

ZCODE           ZCODE output file.

HEAP            Amount of HEAP to be used by the compiler.  Increasing this
                value may allow larger programs to be compiled, although there
                is insufficient free store on a 256 Kb machine to increase it
                by much.  The default is currently 7000.

OPT             Compiler options (heading items, such as USING).

ENVOUT          Environment output file.

XREF            Compiler cross reference output file.

INIT            Initialisation file.  This parameter is intended for testing
                new files, and will not be needed for normal use.

MC              Machine name (see below).

Z               Translator load module file.  As with INIT, this parameter is
                not required for normal use.

ZOPT            Translator options.

OBJ             Object module output file.

OBJIN           Additional object modules to be linked into the final load
                module.

LIBRARY         Additional library files to be scanned before the standard
                Algol68C library.

MAP             Linkage editor MAP file.

TO              Load module output file.


Notes:

1. The parameters given with OBJIN and LIBRARY may a list of files separated
   by space, comma or '+'.

2. If the ZCODE heading item is used to specify the ZCODE file, the translator
   will not be run, since the location of the ZCODE cannot be known.  Similarly,
   if the object file is specified in the NAME string of the program, the
   linkage editor will not be run.

3. Translator options are:

     -N or -n    do not generate procedure names in the code
     -B or -b    do not generate break checks in the code

The machine names currently available are:

  68000
  68000-16
  68000-32
  LSI4

68000-16 and 68000-32 force the use of 16 and 32 bit integers respectively.
68000 is the same as 68000-16 in the current version, although it may be
changed to 68000-32 in the future.

The default machine name is 68000.

IMPORTANT NOTE: The version of the compiler currently available on 68000s uses
16 bit integers internally, and so cannot cope with any constants (or constant
expressions) whose value is outside 16 bit range, even if MC 68000-32 is used.



Examples:

  new.a68c a to b

This compiles a single segment program to a load module, which may be run
simply by typing its name.  Command line decoding and file access is as on
the LSI4 implementation, which has been documented by MJA.

A program may be compiled to run on an LSI4 by using:

  NEW.A68C a TO b MC lsi4

To compile a multi-segment program, use:

  NEW.A68C a OBJ obj.a ENVOUT env1

The second parameter is the object module file.  The environment file may
be quoted in USING directives of descendent segments.  Program heading items
may be given in the command's 'opt' parameter:

  NEW.A68C a OBJ b OPT "USING A FROM *"env1*""

(Take care with the TRIPOS BCPL string escapes!).

When compiling the last segment, others may be included by means of the
'objin' parameter:

  NEW.A68C a68c.final TO program OBJIN obj.a,obj.b

Alternatively, the linkage editor (in 'new.lked') may be used directly.  This
is necessary if an overlaid program is to be produced.  LKED documentation is
available on TRIPOS.  If compiling for LSI4s, the linkage editor must be run on
an LSI4.

If the linkage editor is to be used directly, the Algol68C library files must
be quoted in the LIBRARY parameter.  These files are:

               68000-16        sys:a68c.68000.lib.mod16
               68000-32        sys:a68c.68000.lib.mod32
               LSI4            sys:a68c.lsi4.lib.mod

The 'zopt' parameter of the 'a68c' command is used to give translator options.
The most important of these is '-b', which disables automatic break checking.
By default, the translator inserts a check of the TRIPOS 'break' flag in each
loop that is compiled, so that a looping program may be terminated by CTRL/B.
If you are confident that the program works, you may quote -b to remove these
checks, so reducing the size of the code:

  NEW.A68C a TO b ZOPT -b

Break checking is currently enabled in the Algol68C segments of the standard
library.


ADDITIONAL LIBRARY ROUTINES


PROC sys int clock = INT:  # run time in tenths of seconds #

PROC sys hmax      = INT:  # heap left in current block in INT-sized units #

These routines are intended to replace 'clock' and 'heap available', which are
not yet available.

Note that the result of 'sys hmax' is the amount of space left in the current
heap block.  When this block is exhausted, another will be allocated from TRIPOS
store, and so the result of the routine gives no indication as to the total
amount of heap available.


