AWE(1)                         ALGOL W compiler                         AWE(1)

NAME
       awe - compiler for the ALGOL W language

SYNOPSIS
       awe source.alw... [flags] [-o executable | -c object.c | -p object.c]

DESCRIPTION
       Awe  implements the language described in the ALGOL W Language Descrip‐
       tion, June 1972 very closely.  awe.txt documents Awe's dialect of ALGOL
       W,  the  run-time behaviour of Awe-compiled programs, and how to inter‐
       face ALGOL with C.

       The awe command line may consist of a list of ALGOL W source file names
       and  an  optional  output file flag.  The source files will be concate‐
       nated into a single source program.

       By default awe compiles an executable. The default  name  of  the  exe‐
       cutable  is the name of the last ALGOL W source file with its extension
       removed, on Windows systems an ".exe" suffix will be appended.

       If an ALGOL W program contains procedures with external references (cf.
       section 5.3.2.4 of the Language Description) then awe will write C pro‐
       totypes for them to stdout. You will need to provide  C  functions  for
       those, and link them into your program.

       The most convenient way to maintain moderately complex ALGOL W programs
       is to write a Makefile that uses the ready-make targets in awe.mk.  See
       awe.mk(7).

OPTIONS
       -o executable  specifies a name for the executable.

       -c  object.c  compiles  the  ALGOL W program into a C intermediate-code
       file. Use this if you need to link your ALGOL W program with external C
       functions.

       -p object.c compiles a single ALGOL W procedure into a C function.

       The following flags are meant for debugging purposes only:

       -i  adds  code  that initializes all numbers to zero and all strings to
       spaces.

       -t adds tracing hooks to all procedure calls. (Experimental.)

EXAMPLES
       awe program.alw

       awe zap.alw -c zap.c > externals.h
       gcc zap.c externals.c -lm -lgc -lawe -o zap

       awe procedure.alw -c procedure.c

       Programs compiled by Awe should be able to produce ALGOL W specific er‐
       ror  messages for most runtime errors. Assertion errors always indicate
       bugs in Awe. Segmentation faults should only occur in the case  of  un‐
       bounded recursion. (However, if you link to C code you are back on your
       own.)

       "Call by Name" should used with great caution or  great  abandon.   awe
       notes the locations where Name formal parameters are defined, and where
       expressions are used as Name actual parameters.

Awe and GCC
       Awe uses Gnu C, with its extensions, as an intermediate  language.  Awe
       is  responsible  for  all parsing, type checking and compile-time error
       messages, it uses gcc to generate object code  only.  gcc  should  stay
       completely invisible when you run awe, any messages from gcc whatsoever
       should be considered to be bugs in Awe.  The C files awe generates  are
       temporary  and  will not contain human readable code: do not store them
       in a version control system or distribute them; delete  them  when  you
       delete object files.

Windows
       On Windows systems, Awe programs should not be linked to Boehm GC.  The
       Awe run-library will use the C library's malloc  function  to  allocate
       records,  and they will not garbage collected. But ALGOL W programs can
       be provided with a procedure for explicity  deallocating  records,  see
       the Freeing Records section of awe.txt.

PREREQUISITES
       The Gnu C compiler, the Boehm GC library.

FILES
       /usr/local/bin/awe
              The Awe compiler.

       /usr/local/share/doc/awe/awe.txt
              The Awe ALGOL W documentation file.

       /usr/local/include/awe.mk
              The Awe general-purpose Makefile.

       /usr/local/include/awe.h
              The  Awe  runtime  library  header file. Include this in C files
              that define external procedures for ALGOL W programs.

       /usr/local/lib/libawe.a
              The runtime library for Awe-compiled programs.

       /usr/local/include/aweio.h
              The Awe Standard I/O System header file. (Experimental.)

SEE ALSO
       awe.mk(7)
       gcc(1)
       gc(3)
       ALGOL W Language Description, June 1972

VERSION
       2020 Version

AUTHOR
       Copyright 2017 by Glyn Webster.

       Awe is free software: you can redistribute it and/or  modify  it  under
       the terms of the GNU General Public License and Lesser GNU General Pub‐
       lic License as published by the Free Software Foundation,  either  ver‐
       sion 3 of the License, or (at your option) any later version.

awe                               2020-08-08                            AWE(1)