



                     Using  Bash  1.12


                  on  the  Atari  ST/TT


                            family  of


                  Personal  Computers



                       Scott J. Kolodzieski

                (scott@sparc1.stevens-tech.edu)



                           April 11, 1992



1     Prerequisites



This brief document is intended as an introduction to using Bash on an

Atari ST/TT computer. It is written for the user who are familiar with

concepts such as Unix, Command Line Interpreters, Shells, En-

vironment Variables  and the like. If you are not familiar with these

concepts then I am afraid that these few paragraphs may be of little use

to you. Perhaps in the future I will expand this document to the point of

a general overview of command line interpreters available on the ST/TT

and more fully explain their usage.
____________________________
 I am greatly in debt to a number of people who have made Bash a real winner the

 ST/TT, they are Jwahar Bammi, Edgar Roeder and many other people in the ST
 (internet) community who have given me a great deal of technical assistance, b*
 *ug
 reports, and general suggestions.


                                   1




2     Technical  Considerations



For those readers who are familiar with the Unixmode extension to

the ST/TT file system as implemented in the Gcc run time library this

section may be skipped.



Because the native TOS operating system on the Atari ST/TT limits

the naming of files to a maximum of 11 characters, (an 8 character

file name, followed by a `.', then an optional 3 character extension), a

software extension to this file system has been implemented in the Gnu

C run time support library (hereby referred to as the RTL). What this

amounts to is the following, when a program that has been compiled

with the RTL is executed, the \C" startup code checks the system for the

presence of an environment variable named Unixmode. If found, it then

modifies the standard \C" file/directory functions based on the contents

of the Unixmode environment variable. The Unixmode environment

variable may contain a series of characters, each character (or sequence

of characters) indicates how the standard \C" file/directory functions

are modified. A complete specification of the Unixmode environment

variable looks as follows :  UNIXMODE=``/.<x>r<y>LAHdb'' where <x>

and <y> represent single characters. The meanings of these options are

described briefly in the following table.

_______________________________________________________________________________
| | character sequence | meaning                                             | |
|_|____________________|_____________________________________________________|_|
| |           /          a|llow / or \ to separate subdirectories.      | |
|_|_______________________|_____________________________________________|_|____
| |          .<x>        us|e <x> as replacement for `.'   in filenames | |
| |                        |                                            | |
| |                      wi|th more than one `.'   in their name.        | |
|_|________________________|_____________________________________________|_|___
| |          r<y>        us|e <y> as the root drive.                       | |
|_|________________________|_______________________________________________|_|_
| |           L          a|llow symbolic links.                             | |
|_|_______________________|_________________________________________________|_|_
| |           A          a|llow auto creation of links.                   | |
|_|_______________________|_______________________________________________|_|__
| |           H          h|ide the special `.dir' file.                   | |
|_|_______________________|_______________________________________________|_|__
| |           d          a|llow /dev/<x> in addition to <x>:             | |
|_|_______________________|______________________________________________|_|___
| |           b          o|pen files in binary mode                        | |
|_|_______________________|________________________________________________|_|_




A few points should be made before continuing with our discussion of

the Unixmode extension.  First, all of these options need not always

be set. One usually just picks the extensions that are required, puts the

relevant characters into the Unixmode variable and then executes the

desired program. Of course there is no harm in setting Unixmode once,

with all possible options.  In fact one can set up Unixmode for max-

imum Unix compatibility and forget about it.  The second point that

should be made is that the entire Unixmode standard is implemented

in software, It is only an extension to the high level i/o subsys-

tem of the \C" runtime library. The TOS level bios/gemdos calls

do not know about the Unixmode extensions! This is not a problem as

the main support tools for Bash, i.e. the Gnu file/text utilities,

Gnu Emacs,and Gcc are all aware of Unixmode and behave very nicely

with the Unixmode extensions.



The above options are best described by an example, suppose Unix-

mode is set to the string \/.,rCLAHdb", before one starts some pro-

gram compiled with the RTL. That program may now use extended file

names, even those with multiple occurrences of the `.'  character, the

RTL will do the necessary file name conversions to keep TOS happy.

Because of the presence of the \/" character one may refer to files as

\c:\path\foo" as \c:/path/foo", also because of the \C" following

the \r", \C:" was selected as the root drive, thus the above path could

even be abbreviated as \/path/foo". The presence of the \d" character

in the Unixmode variable allows one to access drive <X> as /dev/<x>/

instead of the more conventional X:\ this feature is frequently used in

Bash.



For the other options that are not described in the above example I refer

you to the documentation that comes with the RTL source code. This

source is freely available from atari.archive.umich.edu




3     Necessary  Files



To get Bash up and running on your Atari you should ideally have at

least the following set of files. The first four come with the binary distri-

bution of Bash V1.12 and the last is available from atari.archive.umich.edu.



    fflbash.ttp -  The binary executable of the Bash shell
    ffltermcap -  A set of terminal descriptions, usually placed in /etc/


    fflinput.rc -  A set of key bindings for Bash, this I find convenient

      to place in the same directory as bash.ttp
    fflbash.rc -  This file contains a set of Bash commands that are

      to be executed upon each invocation of bash.ttp, a good spot to

      put this file is the users home directory.
    fflsetenv.prg -  This is the only file is not included with the bi-

      nary distribution of Bash.  It is used to set certain environment

      variables at boot time.



4     Setting  up  Bash



4.1     Setting the Environment



The program setenv.prg should go in the \auto" folder of your boot

partition so as to set the following environment variables before at-

tempting to execute bash.ttp.  You should read the documentation

that comes with setenv.prg for a complete description of how to use

it. The following list gives the variables and their values that they should

be set to.



    fflTERMCAP = <full path to termcap file>
    fflTERM = vt52
    fflINPUTRC = <full path to input.rc file>
    fflUNIXMODE = .,/LAHdb
    fflHOME = <full path to users home directory>




Since Unixmode will be set prior to bash.ttp being executed, the paths

in the TERMCAP and INPUTRC variables may use the \/dev/<x>/path/filename"

format if you wish. On my system I use the following setup without any

problems:



       TERMCAP=/dev/C/etc/termcap

       TERM=vt52

       INPUTRC=/dev/F/usr/sjk/input.rc

       UNIXMODE=/.,rCLAHdb

       HOME=/dev/F/usr/sjk



4.2     Editing the \bash.rc" File



Using your favorite editor (it should be Gnu Emacs) you should edit the

supplied \bash.rc" file.  You should note that as distributed the file is

line terminated with the <lf> character.  After you finish editing the

file be sure to save it so that each line is in your new \bash.rc" file is

also <lf> terminated.



The only necessary change in the \bash.rc" file actually needed to make

Bash usable is a change of the line defining the Path environment

variable.  Path should be set to a \:"  separated list of paths used to

search for executable files.  Since \:"  is the separator, paths MUST

be defined using the Unixmode /dev/<x>/path method.  In the next

section a small sample \bash.rc" is included for reference.



4.3     A sample \bash.rc" file



           # This is the "bash.rc file" that i use on my system.
           #
           # first we set up the path, i.e. were we look for executebles.




                 export path=/bin/bin:/bin/gnu
           #
           # define some useful aliases
                 alias  cls='echo -en "\33e\33e"'
                 alias    on='echo -en "\33e"'
           #
           # set up the required places for running gnu emacs
                 alias           emacs='/dev/c/bin/emacs/lisp/xemacs -q -l /dev*
 */c/.emacsc'
                 export emacsloadpath=/dev/c/bin/emacs/lisp
                 export       emacslib=/dev/c/bin/emacs/lisp
                 export       emacsdoc=/dev/c/bin/emacs/etc
           #
           # set up required names for running gnu-cc
                 export  gnuinc=/dev/c/lib/gnu/include
                 export  gnulib=/dev/c/lib/gnu/c-lib
                 export gccexec=/dev/c/bin/gnu/gcc-
           #
           # tex/latex/amstex defines...
                 alias  showdvi='/bin/tex/bin/l-show'
                 alias printdvi='/bin/tex/bin/dviprint -v 0.5in -d 4 -z 240'
                 alias     latex='/bin/tex/bin/virtex "&lplain"'
                      texinputs='.;c:/bin/tex/styles'
                     TEXFORMATS='.;C:/bin/tex/formats'
                       TEXFONTS='.;C:/bin/tex/tfm'
                         TEXPOOL='.;C:/bin/tex/bin'
                 export TEXINPUTS TEXFORMATS TEXFONTS TEXPOOL DBICONFIG
           #
           # some general program alias
                alias     stats='echo -en "\33E"; pushd /; c-stat; popd; echo -*
 *en "\33E"'



4.4     The \input.rc" file



The \input.rc" file is a convenience and not a necessity. It simply gives

the user a way to either map \hard-keys" (Function/Keypad and theirs

shifts) to either internal editor commands, or more generally to arbitrary




strings of text.  The only hitch is you must know the byte sequence

returned by each key. The is easy to find out in Bash, just after starting

Bash type <ctrl>q<hard-key>.  The byte sequence that <hard-key>

returns will be displayed on the terminal. See the sample \input.rc" file

for a sample of how his remapping is done.



4.5     A sample \input.rc" file



           #
           # Bind <up-arrow>                     (up-arrow     returns <esc>*H)
           #
           "\e*H": previous-history
           #
           # bind <down-arrow>                   (down-arrow  returns <esc>*P)
           #
           "\e*P": next-history
           #
           # bind <left-arrow>                   (left-arrow  returns <esc>*K)
           #
           "\e*K": backward-char
           #
           # bind <right-arrow>                  (right-arrow returns <esc>*M)
           #
           "\e*M": forward-char
           #
           # bind <delete> and <back-space>     (delete       returns <ctrl>?)
           #                                       (backspace    returns <ctrl>*
 *H)
           "^?":    backward-delete-char
           "^H":    backward-delete-char




5     Running  Bash



Be sure to follow all the guidelines in the previous section \Setting up

BASH" before attempting to run bash.ttp, the Bash executable.



You may now double click on the file bash.ttp, and enter \-login

-rcfile ~/bash.rc",  when prompted for parameters.   This should

launch Bash and you should be ready to go. This only works on TOS

1.4 and later, since in prior versions of TOS, the passed arguments are

forced to upper case.  A workaround for this is to write a small \C"

program that launches Bash with its arguments via a \system()" call.

For information on internal Bash commands you could enter \help" at

the bash prompt.  In depth information concerning the syntax of bash

commands may be found in the rather substantial manual page \bash.1"

distributed with Bash. Also see the list of references at the end of this

document.



Bash is designed to work with TOS programs, however GEM programs

can be run from Bash provided one writes a small wrapper program

that shuts off the text cursor, turns on the mouse, and draws the solid

backgound. This would provide functionality similar to the \gem" com-

mand available in \Gulam".



6     Differences  from  UNIX  Bash



Because of the fact that TOS lacks the multitasking capabilities of the

Unix operating system, Unix style job control is not available under

Bash. If you are running MiNT, a free multitasking extension to TOS,

limited job control like features may be mimmicked with the \bg.ttp"

program distributed with the MiNT system.  Other than job control

and some other small multitasking related features, the ST/TT version




of Bash is a complete implementation of GNU Bash.



7     Suggestions  and  Comments



Any shell is relatively useless without a complete complement of file

utilities.  Bash is no exception.  There are several ports of the Gnu

file/text/shell utilities available on atari.archive.umich.edu that

work very well with Bash on an ST/TT. Also I highly recommend

the Gnu C compiler package that was put together by Jwahar Bammi.

This \C" compiler along with the previously mentioned utilities and

Gnu Emacs make an excellent Unix like \C" development system on

the Atari family of computers.



If you read Usenet or get the Info-Atari16 mailing list, you are aware

of the constants outcry of people for a small-\lean" shell that occupies

~20k of memory and does everything, including compiling Gnu Emacs.

I find this humorous.  One can make a small and fast shell that has

limited features that may be of general use, but when it comes to doing

constant program development one really begins to depend on many of

the features present in a full featured shell such as Bash.  To set the

record strait, my port of Bash has an executable file size of 200k, it

uses approximately another 100k for memory management and internal

data structures.  This leaves 700k available on a 1 meg machine.  For

serious development this is not enough. But with the price of memory

these days it is not bad to assume a 2 megabyte lower bound on an ST

system. This gives a rather comfortable amount of free ram (with Bash

running) and you have about as full featured a shell as you could want.




8     Bug  Reports



If there are any problems with this document or Bash, please let me

know.  I will try to fix all reported bugs, and make updates to this

manual; but since work on Bash is done in my spare time, no promises.

The source for this entire distribution of Bash is available so you are

encourage to track down any existing bugs and mail me patches. That

is the most likely way for fixes to be incorporated into a future release.



9     References



The folowing references may prove helpful.



    fflbash.texinfo -  Some preliminary documentation by the author

      of Bash. This may be found in the original FSF source distribu-

      tion of Bash. This document is still rather incomplete.

    fflreadline.texinfo -  Complete TeX documentation for the Gnu

      Readline library.  This describes key bindings and all available

      readline commands; also available with the origian FSF source

      distribution of Bash.

    fflbash.1 -  A manual page (31 pages) that, at least for the mo-

      ment, is the diffinative Bash reference.  This is included in both

      the binary and source distributions of Bash for the Atari ST/TT.

    fflChangelog -  There are two Changelog files. They describe the

      modifications to the source code required for the Atari specific

      verions of Bash.  These are only useful if you are interested in

      modifying the source.  There is a Changelog in the source and

      readline directories of the Atari source distribution of Bash.
