Installing `gawk' on the Atari ST
=================================

   This section assumes that you are running TOS.  It applies to other
Atari models (STe, TT) as well.

   In order to use `gawk', you need to have a shell, either text or
graphics, that does not map all the characters of a command line to
upper case.  Maintaining case distinction in option flags is very
important (see Invoking `awk': Command Line.).  Popular shells like
`gulam' or `gemini' will work, as will newer versions of `desktop'.
Support for I/O redirection is necessary to make it easy to import
`awk' programs from other environments.  Pipes are nice to have, but
not vital.

   If you have received an executable version of `gawk', place it, as
usual, anywhere in your `PATH' where your shell will find it.

   While executing, `gawk' creates a number of temporary files.  `gawk'
looks for either of the environment variables `TEMP' or `TMPDIR', in
that order.  If either one is found, its value is assumed to be a
directory for temporary files.  This directory must exist, and if you
can spare the memory, it is a good idea to put it on a RAM drive.  If
neither `TEMP' nor `TMPDIR' are found, then `gawk' uses the current
directory for its temporary files.

   The ST version of `gawk' searches for its program files as described
in See The `AWKPATH' Environment Variable: AWKPATH Variable.  On the
ST, the default value for the `AWKPATH' variable is
`".,c:\lib\awk,c:\gnu\lib\awk"'.  The search path can be modified by
explicitly setting `AWKPATH' to whatever you wish.  Note that colons
cannot be used on the ST to separate elements in the `AWKPATH'
variable, since they have another, reserved, meaning.  Instead, you
must use a comma to separate elements in the path.  If you are
recompiling `gawk' on the ST, then you can choose a new default search
path, by setting the value of `DEFPATH' in the file `...\config\atari'.
You may choose a different separator character by setting the value of
`ENVSEP' in the same file.  The new values will be used when creating
the header file `config.h'.

   Although `awk' allows great flexibility in doing I/O redirections
from within a program, this facility should be used with care on the ST.
In some circumstances the OS routines for file handle pool processing
lose track of certain events, causing the computer to crash, and
requiring a reboot.  Often a warm reboot is sufficient.  Fortunately,
this happens infrequently, and in rather esoteric situations.  In
particular, avoid having one part of an `awk' program using `print'
statements explicitly redirected to `"/dev/stdout"', while other
`print' statements use the default standard output, and a calling shell
has redirected standard output to a file.

   When `gawk' is compiled with the ST version of `gcc' and its usual
libraries, it will accept both `/' and `\' as path separators.  While
this is convenient, it should be remembered that this removes one,
technically legal, character (`/') from your file names, and that it
may create problems for external programs, called via the `system()'
function, which may not support this convention.  Whenever it is
possible that a file created by `gawk' will be used by some other
program, use only backslashes.  Also remember that in `awk',
backslashes in strings have to be doubled in order to get literal
backslashes.

   The initial port of `gawk' to the ST was done with `gcc'.  If you
wish to recompile `gawk' from scratch, you will need to use a compiler
that accepts ANSI standard C (such as `gcc', Turbo C, or Prospero C).
If `sizeof(int) != sizeof(int *)', the correctness of the generated
code depends heavily on the fact that all function calls have function
prototypes in the current scope.  If your compiler does not accept
function prototypes, you will probably have to add a number of casts to
the code.

   If you are using `gcc', make sure that you have up-to-date libraries.
Older versions have problems with some library functions (`atan2()',
`strftime()', the `%g' conversion in `sprintf()') which may affect the
operation of `gawk'.

   In the `atari' subdirectory of the `gawk' distribution is a version
of the `system()' function that has been tested with `gulam' and `msh';
it should work with other shells as well.  With `gulam', it passes the
string to be executed without spawning an extra copy of a shell.  It is
possible to replace this version of `system()' with a similar function
from a library or from some other source if that version would be a
better choice for the shell you prefer.

   The files needed to recompile `gawk' on the ST can be found in the
`atari' directory.  The provided files and instructions below assume
that you have the GNU C compiler (`gcc'), the `gulam' shell, and an ST
version of `sed'. The `Makefile' is set up to use `byacc' as a `yacc'
replacement.  With a different set of tools some adjustments and/or
editing will be needed.

   `cd' to the `atari' directory.  Copy `Makefile.st' to `makefile' in
the source (parent) directory.  Possibly adjust `../config/atari' to
suit your system.  Execute the script `mkconf.g' which will create the
header file `../config.h'.  Go back to the source directory.  If you
are not using `gcc', check the file `missing.c'.  It may be necessary
to change forward slashes in the references to files from the `atari'
subdirectory into backslashes.  Type `make' and enjoy.

   Compilation with `gcc' of some of the bigger modules, like
`awk_tab.c', may require a full four megabytes of memory.  On smaller
machines you would need to cut down on optimizations, or you would have
to switch to another, less memory hungry, compiler.