File:    g77intro.txt
Date:    1997 August 15
Version: 0.4
Author:  Clive Page, cgp@star.le.ac.uk
g77 vn:  0.5.19  [check this]

This file contains a brief introduction to g77, the GNU Fortran compiler,
here packaged for use on PCs with MS-DOS using the EMX DOS-extender.


1. What is g77?

G77 is a Fortran compiler from the Free Software Foundation (GNU). The g77
compiler is designed to be portable, and there are implementations  on a
wide variety of systems including Linux, other Unixes, OS/2, and MS-DOS.  
The g77 compiler supports the whole of the (now obsolete) Fortran77
Standard plus many commonly-used extensions.  This package, g77dos,
packages the g77 compiler with the EMX DOS-extender of Eberhard Matthes
and a few other useful utilities, so it can be used under MS-DOS.  It
requires a PC (386/486/Pentium) with around 4 MB of disc space.

Typographical note: in this introduction Fortran keywords and code are
shown in UPPER CASE merely make them stand out; g77 is equally happy
with Fortran in lower-case.


2. How to download.

The package is available by anonymous FTP from ftp.star.le.ac.uk in
directory pub/fortran (and maybe other sites in due course).
There are two zip files:

 g77dos.zip    [insert size here]  The main executables
 g77doc.zip    [insert size here]  Documentation and other stuff.

Remember to FTP these in binary mode.

This port is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.  You should have received a copy of the GNU General Public
License along with emx; see the file COPYING. If not, write to the Free
Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  The GNU
Public Licence requires the corresponding source code to be available. 
This can be obtained from a number of FTP sites including:  [insert
addresses here]


3. How to install.

You will need at least 3 MB [check this] of free space on your hard disc.
If you start from your root directory the files will unzip into
subdirectories \EMX \EMX\BIN \EMX\LIB and \EMX\DOC as necessary.  You are
free to put them somewhere else but if so you will need to update the file
SETUPG77.BAT to reflect the changes.  The simplest commands are:

  CD \
  UNZIP G77DOS.ZIP
  UNZIP G77DOC.ZIP

To use the system you need to execute the very short batch file SETUPG77
which adds the \EMX\BIN directory to your path and defines an
environment variable.


4. How to use the compiler.

The command G77 will compile and link your program and produce an
executable bound with the EMX DOS-extender (which is needed to get 32-bit
memory access).  There are various command options (see below) which need
to be specified before the name of the program file(s).  A simple
demonstration program called MYTEST.F is included in the package.  To
compile this just use:
  G77 MYTEST.F
This generates a file MYTEST.EXE, which can be executed simply using
  MYTEST

It is good practice to get the compiler to warn you of unused and
undeclared variables, to get the maximum amount of safety checking, try:
  G77 -W -Wall -O MYTEST.F

Note that the switches are case-sensitive: -Wall not -WALL 

The g77 compiler has a large number of other command switches - a few of
the most useful are shown here:

-c               Compile-only: produces .OBJ files.
-ffree-form      Use free-format source code
-fpedantic       Warns of non-portable/non-standard code.
-fno-automatic   Static storage for all variables, like universal SAVE
-fno-backslash   Interprets "\" as a normal character in strings
-fvxt            Use VAX Fortran interpretation of certain syntax
-g               Produces debugging information.
-Idirectory      Specifies directory to search for INCLUDE files
-O               Optimise code generation
-Wimplicit       Warns of any names with no explicit data type
-Wuninitialised  Warns of some cases of unset variables (if -O also set).
-Wall            Warns of both of above cases.

Any number of source-code files can be used on the command-line, and
wild-cards (*) are supported in file-names.  The command-line can also
contain compiled object modules (.OBJ) and library files (called "archives"
in Unix-speak) which have .A as the extension.  File-names are, of course,
not case-sensitive in MS-DOS.

Under Windows95 (and maybe other systems) you may find that the EMX
DOS-extender is insufficient; in this case using RSX may solve the problem.
One way to do this is use the RSX command with your executable as its
first argument, for example:

  RSX MYPROG.EXE


The .EXE file produced by the compiler can only be run if a suitable
DOS-extender (EMX.EXE  or RSX.EXE) to be available on the search path.  If
you want to distribute your programs to other machines you may prefer to
generate a stand-alone executable, although this will be larger.  You can
do this with the EMXBIND program by first extracting a version of the
executable in "a.out" format, and then binding this with EMX.   Assuming
you have created a file MYPROG.EXE, the commands would be:

  EMXBIND -x MYPROG.EXE A.OUT
  EMXBIND -b -s EMX A.OUT MYPROG.EXE
  DEL A.OUT


5. Extensions to g77 compatible with Fortran90:

The g77 compiler conforms fully only to the Fortran77 Standard.  Although
this is technically obsolete, the vast majority of Fortran programs in the
world were written (more or less) to this Standard.  The new standard,
Fortran90, has many more advanced features.  The g77 compiler already
supports some features of Fortran90, the most notable of these being:

IMPLICIT NONE (to flag non-explicit data types in a program unit).
INCLUDE 'filename' 
Automatic arrays (a form of dynamic storage within subprograms).
Free-format input, e.g. & at end of line to be continued
  (if the switch -ffree-form is used) 
Multiple statements on a line (with ";" as the separator).
Symbolic names can be up to 31-characters long, can contain lower-case
  letters (equivalent to upper-case) and underscores.
End-of-line comments may be used starting with ! (but ! must not be
  in column 6 with fixed-format source-code).
Relational operators > >= < <= == /= can be used instead of .GT. etc.
Character constants can use "double" or 'single' quotes.
Program unit names permitted on END, e.g. END SUBROUTINE MYSUB.
DO without labels and END DO are permitted, also indefinite DO (but a
  conditional EXIT or STOP is obviously needed in such loops).
DO WHILE(logical expression) with END DO is permitted.
EXIT and CYCLE are allowed in DO loops.
SELECT CASE structure is supported but only with integer/logical selectors.
Construct names are allowed with IF/DO/CYCLE/EXIT/SELECT CASE.
Zero-length strings are valid.
Substrings of character constants are permitted.
Character intrinsic functions ACHAR, IACHAR, and LEN_TRIM are provided.
Bit-wise integer functions BTEST, IAND, IBCLR, IBITS, IBSET, IEOR, IOR,
  ISHFT, ISHFT, MVBITS, NOT (the MIL-STD 1753 intrinsics) are provided.
OPEN with STATUS='REPLACE' is supported.
NAMELIST input/output is also supported.
Type declarations may use KIND values (but this is of limited use because
  kind-selection functions are not yet provided).


6. Other g77 extensions (NOT compatible with Fortran90)

Many extensions to the official Fortran77 Standard were introduced by
companies which produced Fortran compilers for sale, but not all of these 
were incorporated into Fortran90.  You may find that existing "Fortran77"
code makes use of some of these non-standard features.  Fortunately g77
supports some of the more common extensions, especially those of VAX
Fortran.  The most important ones are listed below.  They make it possible
to use "legacy" code with a minimum of alteration, but are NOT recommended
if you are writing new code.

Data types BYTE, INTEGER*1, INTEGER*2, INTEGER*4 (default), INTEGER*8,
 REAL*4 (default), REAL*8, DOUBLE COMPLEX, COMPLEX*8 (default), COMPLEX*16,
 LOGICAL*1, LOGICAL*2, LOGICAL*4 (default) are supported.
DATA statements may be intermixed with specifications statements.
Arguments of procedure calls may use %VAL, %REF, %LOC, %DESCR functions.
Additional intrinsic functions: LOC, AND, OR, LSHIFT, RSHIFT, XOR,
 CDABS, CDCOS, CDEXP, CDLOG, CDSIN, CDSQRT, DCMPLX, DCONJG, DFLOAT,
 DIMAG, DREAL, IMAG, ZABS, ZCOS, ZEXP, ZLOG, ZSIN, and ZSQRT supported.
Any number of continuations lines may be used.
Symbolic names may include "$" if -fdollar-ok switch is specified..
Integer constants may be specified in other number bases: e.g. B'01', 
 O'01234567', X'01EF', Z'FFFF' etc.; in addition "typeless" constants  may
 be given in a similar form but with the letter following the string of 
 digits.
FORMAT specifications may include $ to suppress the final carriage-return.
Debug lines starting "D" or "d" are treated as comments.


7. Notes on Input/Output 

I/O unit numbers must be in the range 0 to 99, with 0 and 6 pre-connected to
  the screen, 5 to the keyboard (but best to use UNIT=* for both).
Unformatted direct-access files have bytes as units of record length.
Output to the screen does not count as "printing" in Fortran terms, so
  the first character of each record is never removed for carriage-control.
Output to unit N is sent to file "FORT.N" if no file was opened for it.


8. The Fortran Library 

G77 supports, even on MS-DOS, most of the routines commonly used to access
system services on Unix.  These include: ABORT, GETARG, IARGC, EXIT,
CTIME, DATE, DTIME, ETIME, FDATE, GMTIME, LTIME, IDATE, ITIME, MCLOCK,
SECNDS, SECOND, SYSTEM, TIME,  ERF, DERF, ERFC, DERFC, IRAND, RAND,
SRAND, ACCESS, CHDIR, CHMOD, GETCWD, FSTAT, SSTAT, LSTAT, RENAME, UMASK,
UNLINK, GERROR, IERRNO, PERROR, GETENV, FGETC, GFET, FPUTC, FPUT, FLUSH,
FNUM, FSEEK, FTELL, ISATTY, TTYNAM, SLEEP.

Note that I have not checked all of these.  HOSTNM and GETLOG are  not
supported, and SYSTEM (which executes an operating system command line)
seems to work in a DOS-box under Windows3.1 and Windows95, but not under
genuine MS-DOS. 

For details of the calling sequences see the g77 documentation in the set
of g77_*.txt files.   The same documentation is also available on the WWW in
HTML format, see http://www-rocq.inria.fr/~kern/G77/g77_toc.html


9. How to use object libraries

A version of the standard Unix library manager, unhelpfully called AR, is
provided.  It manages what it calles "archives" which are more usually
called object modules.  These files have ".A" as their extension.
To create a library you need to compile with the -c switch to produce one
or more object files (.OBJ).  These can be put in a library like this:

  AR -r  MYLIB.A  MYPROG.OBJ\

To list the contents of an archive use
  AR -t MYLIB.A

Then if you specify MYLIB.A on the G77 command-line, it will be searched
during the loading phase  and load only those modules which are called
directly or indirectly. 


10. Debugging

[to be written]


11. Graphics

I recommend the PGPLOT package written by Tim Pearson of CalTech, which is
available from http://astro.caltech.edu/~tjp/pgplot/
So far I have not had time to provide a PGPLOT driver for g77/EMX, but with
the available graphics libraries this should not be difficult.


12. Source Code and Further Information

All of this software has been released by the various authors under the
terms of the GNU Public Licence.  This is provided in file COPYING.DOC 
which you should read.  The licence requires source code to be provided or
easily available.  These sources, which occupy the space of several more
floppy discs, are widely available on the Internet.

The g77 compiler from James Craig Burley ported to OS/2 and
DOS can be found at several places, including:
ftp://ftp.uni-stuttgart.de/pub/systems/os2/leo/gnu/emx+gcc/contrib/g77src.zip

The GNU Fortran library from Dave Love can be found at:
ftp://ftp.dl.ac.uk/pub/fx/libU77

The EMX DOS-extender and software development system from Eberhard Mattes
is available from many places including:
ftp://src.doc.ic.ac.uk/packages/os2/unix/emx09c
ftp://ftp.rrzn.uni-hannover.de/pub/mirror/os2/dev/emx/v0.9c/ 
The following files are needed for a full g77/gcc development system:
emxrt.zip,  emxdev1.zip, emxdev2.zip, gnudev1.zip, gnudev2.zip

Further information on EMX is available on the WWW at: 
http://warp.eecs.berkeley.edu/os2/software/shareware/emx.html

The RSX DOS-extender comes from Rainer Schnitker:
ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc

The original g77 documentation has been converted from .texi to HTML and
version can be found on: http://www-rocq.inria.fr/~kern/g77_toc.html  I
have further converted these to plain ascii files, and provided them on
the G77DOC.ZIP disc: they are called G77_*.TXT (with a chapter index in
CONTENTS.TXT). 
