)rv comment
set version = '!version!'
call name(FCSYS,'FC implementation guide')
!head('introduction')
This document is designed to aid implementation of the UBC Fortran 77
compiler. 
this is the fourth distribution that has been made 
of the compiler and is included in the first UBC distribution tape.
this  is version !version! of the compiler.
!head('distribution conditions')
it is assumed, as a condition of distribution:
!pt we assume no liability for this program.
!pt no further distribution is allowed.
any other users must either obtain their own release or wait for the
formal release of the compiler.
!pt any two installations having obtained copies of the compiler from UBC may exchange distributions freely.
!pt the purpose of the distribution is to aid in debugging and developement
of the compiler and to allow other installations access to the compiler.
while it is generally as bug free as possible; it is expected that bugs
may exist and that these (as well as any improvements) will be reported.
!pt for bug reports to be useful the minimal program to exhibit the
bug should be produced. it is of little use having a 1000 line program
that "doesn't work", requiring numerous input files and producing 
volumes of output.
!head('address')
other installations interested in the compiler should contact:
)l2 @w. @e. webb
)l @institute of @animal @resource @ecology
)l 2204 Main Mall
)l @university of @british @columbia
)l @vancouver, @b. @c. 
)l @canada @v6@t 1@w5
)l
!p the phone number is 604-228-6527.
!head('Restoring the files from the tape')
if there is enough disk space available, just restore the entire distribution:
)l2 tar x0f /dev/rmt0 
!p if there is insufficient space (the above requires about 12,325 blocks),
then just the files sufficient to implement Fortran 77 many be restored
by first restoring the file "f77.restore" and using it to restore the files
required.
!head('Simple minded installation of F77')
!p to install the compiler over top of Bell's fc use:
)l2 install.fc 
!p to install it by itself, (as f77), use: )l2 install.f77
!p note that the install files take two arguments, the first of which may be either "", 
"34" or "fpt". "" causes the standard I/D separated version to be used, "34" causes a non I/D space compiler to be installed, "fpt"
causes the floating point simulator to be installed.
!p the second argument controls whether the standard V6 "ar" format, 
or whether the PWB (or UNIX library) version of "ar" is used.
the second argument should be specfied only if the OLD V6 format is to
be used.
!p you will probably want to inspect the install files as they move files into
the directories "/lib", "/usr/fort", and "/bin".
!head('PWB dependencies')
the only part of the compiler that is dependent upon PWB (other than for the
format of AR-I libraries) is the FDB (Fortran DeBugger) routine. there are
three possible ways around this dependency:
!pt use the  -P switch on the FDB command. (-U is the opposite for UNIX V6).
!pt change the value of the variable "sysfudge" using CDB  to 768 for PWB
(default is 512 for UNIX), or re-compile after changing the source in "fdb/run.c".
!pt create the file "/etc/pwb" which FDB will check to see if its on a PWB 
system. this is by far the easiest, but requires access to the /etc directory.
!head('Relevent files')
the following files are required (under some name or other) for the
proper operation of the compiler:
!i(bin/fc) is the Fortran Compiler command if it is to be invoked as "fc". It invokes the compiler and
(if required) the linkeditor.
this name should only be used if Bell's "Fortran" compiler is not being 
used.
!i(bin/f77) is the Fortran Compiler if it is to be invoked as "f77". it
invokes the actual compiler and (if required) the linkeditor.
!i(usr/fort/fc) is the actual compiler. 
!i(usr/fort/ferr) is the routine used by the run time to print out an
interpretation of a runtime error.
!i(usr/fort/errmsgs) is the file referenced by FERR to get the error 
message texts.
it contains both runtime diagnostics and fuller explanations for compiler
diagnostics. it may be freely edited as FERR scans the file to find the
proper diagnostic.
!i('usr/fort/fc.msgs-!version!') contains the actual compiler error messages.
it may be freely edited as long as no new lines are added or any old lines
deleted as the compiler finds the error message by looking for the n'th 
line for error message "n".
the suffix "!version!" is the compiler internal version number. it is present so 
that messages may be added and deleted between versions. 
!i(bin/asa) is the ASA output filter. it converts ASA carriage control
(1 == page skip, 0=double space etc.) into standard ASCII controls (FF, NL,
CR, etc.)
!i(lib/libf.a is the runtime library if the compiler is installed as "fc". it contains the routines that must
be linked to the object module produced by the compiler if the compiler is installed as "fc".
!i(lib/frt0.o) is the Fortran runtime header file if the compiler is installed as "fc". it invokes the main
program if the compiler is installed as "fc".
!i(lib/mfrt0.o) is the profile runtime header file if the compiler is installed
as "fc".
!i(lib/libf77.a) is the runtime library if the compiler is installed as
"f77".
!i(lib/frt77.o) is the runtime header file if the compiler is installed 
as "f77".
!i(lib/mfrt77.o) is the profile runtime header file if the compiler is 
installed as "f77".
!head('generating the compiler')
while the object files on the tape should be sufficient, all files
needed to generate the compiler should be on the tape (@i hope).
see the file "fc/READ!47ME" for details on generating the compiler.
!head('C Compiler')
the FC compiler uses a large number of "#define"'s and has a large symbol table.
it will probably be necessary to change the C preprocessor to allow for more
defined symbols.
!p in addition, the large number of symbols will probably mean that the C compiler
itself will have to have its hash table size increased. 
!head('LD - the linkeditor')
because the of the large number of global symbols it will probably be necessary to
increase the size of the linkeditor's symbol table. 
!p I have included a version of LD that has the following features:
!pt the symbol table is large enough to handle the compiler itself.
!pt it will accept either the original UNIX version 6 AR format, or the 
PWB (or UNIX library) version.
!pt it accepts the "-z" option that includes the entire contents of a library.
this is useful when a large program is stored in a file and contains many 
subroutines, as the object generated will be an archieve.
!head('non PDP 11/45 and 11/70')
the compiler is generated with separated I and D spaces. this only works on some
PDP 11's that run UNIX. if shared I and D spaces are not available then much less
space is available for the symbol table.
such systems should specify "34" on the "install" command so that the correct
version is installed.
!head('floating point')
the compiler makes use of floating point arithmetic and will require the 
floating point simulator for PDP 11's that don't have the floating point 
instruction set. this could cause problems due to the extra memory space required
for the simulator.
such systems should specify "fpt" on the "install" command so that the correct
version is installed.
!p it should be essentially trivial to modify the runtime to allow use of the 
floating point simulator.
!p note: for these reasons somebody should modify the system to incorporate the 
simulator into the kernal so that programs don't have to be modified as much when
moved from system to system. 
!head('sticky compiler')
because the compiler is quite large, and since it is at least shareable
it is often important to make the "/usr/fort/fc" file sticky. this will
substantially reduce the start-up time after the first "fc" command.
the only thing is to be very careful in removing the compiler if it
has been made sticky as this is a good way of losing i-nodes.
!p note that if very large programs are to be compiled on non I/D space 
machines a little more memory may be obtained by )u not )u making the compiler
sharable. this allows the full 32K address space to be used and can gain
several K words.
on systems with fast disks it is not as essential to make the compiler sticky.
on a system with RK05 disks you can change the response time to the "fc"
command from 13 to 3 seconds by making it sticky.
!head('files referenced by the compiler')
the compiler references a couple of files:
!i('usr/fort/fcmsgs-!version!') contains the compiler's error diagnostics. the compiler
will run without this file but it is very hard to determine the causes of errors
without it.
!i(etc/pagesize) contains the default printer page size in lines (logical length in the
first word, physical in the second). if this file does not exist 
the compiler will use 60 lines/page as the page length for listings.
!head('files referenced by the runtime')
!i(usr/fort/ferr)
the runtime references the this file which it uses to print
out the text explanation for a runtime error. if this file is missing then
the error explanation will not be printed.
!i(usr/fort/errmsgs) is referenced by "ferr" when it is requested by the
runtime error routine to print out the reason for the error.
!head('files passed to LD by FC')
!i(lib/frt0.o) contains the runtime header file.
!i(lib/mfrt0.o) contains the profile runtime header file.
!i(lib/libf.a) is the fortran library.
!i(lib/libc.a) for the C library in case any C routines are called.
!i(lib/liba.a) for the basic library (sqrt etc.).
!head('files passed to LD by F77')
!i(lib/mfrt77.o) contains the profile runtime header file.
!i(lib/mfrt77.o) contains the profile runtime header file.
!i(lib/libf.a) is the fortran library.
!i(lib/libc.a) for the C library in case any C routines are called.
!i(lib/liba.a) for the basic library (sqrt etc.).
!head('code generation')
the compiler generates !u standard a.out files, except when it generates
libraries of a.out files. the linkedit may, if desired, produce shareable
load modules. note that the object files produced by the compiler
use the full a.out format: text, data, and bss sections are produced
from fortran programs. note that since threaded code is used that while
it is possible to make shareable load modules it is not possible to
generate separable load modules without changing the compiler.
!head('Time Zone Dependencies')
the compiler prints out what it thinks are the time and date for listings.
this will obviously be incorrect for installations not on the west coast.
the easiest fix is to use "db" (or "cdb" if you have an improved one) 
to patch the "timezone" variable in "ctime" to your time zone value.
!head('tape format')
the Fortran 77 subset of the distribution consists of the following directores:
!i(fc) contains source and object for the compiler itself.
!i(run) contains run-time routines (mostly arithmetic).
!i(io) contains the io routines (modifications of unix fc routines).
!i(fns) contains some of the standard functions (sin, sqrt etc).
!i(usr/fort) contains the compiler itself, the error messages for
runtime and the error message printing routine (ferr).
!i(bin) contains some objects.
!i(libs) contains fortran callable versions of unix system routines.
!i(lib) contains some fortran libraries and the fortran header file.
(it also contains most of the libraries on our system in case something
was inadvertently left out).
!i(fcdoc) contains documention source for Fortran. it is in @f@m@t format.
to get a copy of this document one could use: "fmt uhead fcsys".
the user's guide is: in "fc?".
!i(doc) contains documentation for other parts of the distribution.
!head('things to look out for')
while some parts of the compiler and runtime have been used quite
a bit there are others not so completely checked out:
!pt the --t (two word integer) mode has not been used much.
!pt the complex and double precision routines haven't been used 
much.
!pt the basic functions haven't been checked out fully, but the
common ones (sin, cos, exp, sqrt etc. seem ok). 
!head('FDB routine')
I have included on this distribution a copy of the FDB (Fortran DeBug)
program. 
the documentation is with the other documentation.
!head(documentation)
the directories "fcdoc" and "doc" contain the documentation files. all the source is in
FMT format, so to print out a copy FMT must be used. I have put copies
that can be copied to a printer in the directory "prt". in general, to
produce a new copy of the document use:
)l2a
 fmt uhead name
or
 fmt uhead name?
) depending upon the individual document. to print out a copy of all of the
documents the shell-file "fc.fmt" may be used. 
the shell-file "prt.gen" generates the files in the directory "prt".
!p the files "fcint?" contain such documentation as exists about the
internal workings of the compiler and the runtime. 
!head('known bugs and problems')
!pt the compiler does not conform to the Fortran 77 standard in the way
that it passes character expressions, as only the address is passed, and
not the address and length. this means that you cannot declare a parameter
as "character *(*) x" and then use "length(x)" to get the length.
this is done to be compatible with existing compilers that allow quoted
strings in parameter lists.
!pt similarly hollerith constants are treated exactly the same as quoted
constants. I will probably intoduce a compiler option that will allow the
compiler to follow the standard exactly.
!pt the runtime routines do not support the OPEN statement, and
the INQUIRE statement, though the compiler will generate
the proper code for them.
