This is Info file f/g77.info, produced by Makeinfo version 1.68 from the input file ../../../src/gcc-2.95.3/gcc/f/g77.texi. INFO-DIR-SECTION Programming START-INFO-DIR-ENTRY * g77: (g77). The GNU Fortran compiler. END-INFO-DIR-ENTRY This file documents the use and the internals of the GNU Fortran (`g77') compiler. It corresponds to the GCC-2.95 version of `g77'. Published by the Free Software Foundation 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1995-1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "GNU General Public License," "Funding for Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled "GNU General Public License," "Funding for Free Software," and "Protect Your Freedom--Fight `Look And Feel'", and this permission notice, may be included in translations approved by the Free Software Foundation instead of in the original English. Contributed by James Craig Burley (). Inspired by a first pass at translating `g77-0.5.16/f/DOC' that was contributed to Craig by David Ronis ().  File: g77.info, Node: Time Intrinsic (VXT), Next: UMask Intrinsic (function), Prev: TanD Intrinsic, Up: Other Intrinsics Time Intrinsic (VXT) .................... CALL Time(TIME) TIME: `CHARACTER*8'; scalar; INTENT(OUT). Intrinsic groups: `vxt'. Description: Returns in TIME a character representation of the current time as obtained from `ctime(3)'. Programs making use of this intrinsic might not be Year 10000 (Y10K) compliant. For example, the date might appear, to such programs, to wrap around (change from a larger value to a smaller one) as of the Year 10000. *Note FDate Intrinsic (subroutine)::, for an equivalent routine. For information on other intrinsics with the same name: *Note Time Intrinsic (UNIX)::.  File: g77.info, Node: UMask Intrinsic (function), Next: Unlink Intrinsic (function), Prev: Time Intrinsic (VXT), Up: Other Intrinsics UMask Intrinsic (function) .......................... UMask(MASK) UMask: `INTEGER(KIND=1)' function. MASK: `INTEGER'; scalar; INTENT(IN). Intrinsic groups: `badu77'. Description: Sets the file creation mask to MASK and returns the old value. See `umask(2)'. Due to the side effects performed by this intrinsic, the function form is not recommended. For information on other intrinsics with the same name: *Note UMask Intrinsic (subroutine)::.  File: g77.info, Node: Unlink Intrinsic (function), Next: ZExt Intrinsic, Prev: UMask Intrinsic (function), Up: Other Intrinsics Unlink Intrinsic (function) ........................... Unlink(FILE) Unlink: `INTEGER(KIND=1)' function. FILE: `CHARACTER'; scalar; INTENT(IN). Intrinsic groups: `badu77'. Description: Unlink the file FILE. A null character (`CHAR(0)') marks the end of the name in FILE--otherwise, trailing blanks in FILE are ignored. Returns 0 on success or a non-zero error code. See `unlink(2)'. Due to the side effects performed by this intrinsic, the function form is not recommended. For information on other intrinsics with the same name: *Note Unlink Intrinsic (subroutine)::.  File: g77.info, Node: ZExt Intrinsic, Prev: Unlink Intrinsic (function), Up: Other Intrinsics ZExt Intrinsic .............. This intrinsic is not yet implemented. The name is, however, reserved as an intrinsic. Use `EXTERNAL ZExt' to use this name for an external procedure.  File: g77.info, Node: Other Compilers, Next: Other Languages, Prev: Other Dialects, Up: Top Other Compilers *************** An individual Fortran source file can be compiled to an object (`*.o') file instead of to the final program executable. This allows several portions of a program to be compiled at different times and linked together whenever a new version of the program is needed. However, it introduces the issue of "object compatibility" across the various object files (and libraries, or `*.a' files) that are linked together to produce any particular executable file. Object compatibility is an issue when combining, in one program, Fortran code compiled by more than one compiler (or more than one configuration of a compiler). If the compilers disagree on how to transform the names of procedures, there will normally be errors when linking such programs. Worse, if the compilers agree on naming, but disagree on issues like how to pass parameters, return arguments, and lay out `COMMON' areas, the earliest detected errors might be the incorrect results produced by the program (and that assumes these errors are detected, which is not always the case). Normally, `g77' generates code that is object-compatible with code generated by a version of `f2c' configured (with, for example, `f2c.h' definitions) to be generally compatible with `g77' as built by `gcc'. (Normally, `f2c' will, by default, conform to the appropriate configuration, but it is possible that older or perhaps even newer versions of `f2c', or versions having certain configuration changes to `f2c' internals, will produce object files that are incompatible with `g77'.) For example, a Fortran string subroutine argument will become two arguments on the C side: a `char *' and an `int' length. Much of this compatibility results from the fact that `g77' uses the same run-time library, `libf2c', used by `f2c', though `g77' gives its version the name `libg2c' so as to avoid conflicts when linking, installing them in the same directories, and so on. Other compilers might or might not generate code that is object-compatible with `libg2c' and current `g77', and some might offer such compatibility only when explicitly selected via a command-line option to the compiler. *Note: This portion of the documentation definitely needs a lot of work!* * Menu: * Dropping f2c Compatibility:: When speed is more important. * Compilers Other Than f2c:: Interoperation with code from other compilers.  File: g77.info, Node: Dropping f2c Compatibility, Next: Compilers Other Than f2c, Up: Other Compilers Dropping `f2c' Compatibility ============================ Specifying `-fno-f2c' allows `g77' to generate, in some cases, faster code, by not needing to allow to the possibility of linking with code compiled by `f2c'. For example, this affects how `REAL(KIND=1)', `COMPLEX(KIND=1)', and `COMPLEX(KIND=2)' functions are called. With `-fno-f2c', they are compiled as returning the appropriate `gcc' type (`float', `__complex__ float', `__complex__ double', in many configurations). With `-ff2c' in force, they are compiled differently (with perhaps slower run-time performance) to accommodate the restrictions inherent in `f2c''s use of K&R C as an intermediate language--`REAL(KIND=1)' functions return C's `double' type, while `COMPLEX' functions return `void' and use an extra argument pointing to a place for the functions to return their values. It is possible that, in some cases, leaving `-ff2c' in force might produce faster code than using `-fno-f2c'. Feel free to experiment, but remember to experiment with changing the way *entire programs and their Fortran libraries are compiled* at a time, since this sort of experimentation affects the interface of code generated for a Fortran source file--that is, it affects object compatibility. Note that `f2c' compatibility is a fairly static target to achieve, though not necessarily perfectly so, since, like `g77', it is still being improved. However, specifying `-fno-f2c' causes `g77' to generate code that will probably be incompatible with code generated by future versions of `g77' when the same option is in force. You should make sure you are always able to recompile complete programs from source code when upgrading to new versions of `g77' or `f2c', especially when using options such as `-fno-f2c'. Therefore, if you are using `g77' to compile libraries and other object files for possible future use and you don't want to require recompilation for future use with subsequent versions of `g77', you might want to stick with `f2c' compatibility for now, and carefully watch for any announcements about changes to the `f2c'/`libf2c' interface that might affect existing programs (thus requiring recompilation). It is probable that a future version of `g77' will not, by default, generate object files compatible with `f2c', and that version probably would no longer use `libf2c'. If you expect to depend on this compatibility in the long term, use the options `-ff2c -ff2c-library' when compiling all of the applicable code. This should cause future versions of `g77' either to produce compatible code (at the expense of the availability of some features and performance), or at the very least, to produce diagnostics. (The library `g77' produces will no longer be named `libg2c' when it is no longer generally compatible with `libf2c'. It will likely be referred to, and, if installed as a distinct library, named `libg77', or some other as-yet-unused name.)  File: g77.info, Node: Compilers Other Than f2c, Prev: Dropping f2c Compatibility, Up: Other Compilers Compilers Other Than `f2c' ========================== On systems with Fortran compilers other than `f2c' and `g77', code compiled by `g77' is not expected to work well with code compiled by the native compiler. (This is true for `f2c'-compiled objects as well.) Libraries compiled with the native compiler probably will have to be recompiled with `g77' to be used with `g77'-compiled code. Reasons for such incompatibilities include: * There might be differences in the way names of Fortran procedures are translated for use in the system's object-file format. For example, the statement `CALL FOO' might be compiled by `g77' to call a procedure the linker `ld' sees given the name `_foo_', while the apparently corresponding statement `SUBROUTINE FOO' might be compiled by the native compiler to define the linker-visible name `_foo', or `_FOO_', and so on. * There might be subtle type mismatches which cause subroutine arguments and function return values to get corrupted. This is why simply getting `g77' to transform procedure names the same way a native compiler does is not usually a good idea--unless some effort has been made to ensure that, aside from the way the two compilers transform procedure names, everything else about the way they generate code for procedure interfaces is identical. * Native compilers use libraries of private I/O routines which will not be available at link time unless you have the native compiler--and you would have to explicitly ask for them. For example, on the Sun you would have to add `-L/usr/lang/SCx.x -lF77 -lV77' to the link command.  File: g77.info, Node: Other Languages, Next: Installation, Prev: Other Compilers, Up: Top Other Languages *************** *Note: This portion of the documentation definitely needs a lot of work!* * Menu: * Interoperating with C and C++::  File: g77.info, Node: Interoperating with C and C++, Up: Other Languages Tools and advice for interoperating with C and C++ ================================================== The following discussion assumes that you are running `g77' in `f2c' compatibility mode, i.e. not using `-fno-f2c'. It provides some advice about quick and simple techniques for linking Fortran and C (or C++), the most common requirement. For the full story consult the description of code generation. *Note Debugging and Interfacing::. When linking Fortran and C, it's usually best to use `g77' to do the linking so that the correct libraries are included (including the maths one). If you're linking with C++ you will want to add `-lstdc++', `-lg++' or whatever. If you need to use another driver program (or `ld' directly), you can find out what linkage options `g77' passes by running `g77 -v'. * Menu: * C Interfacing Tools:: * C Access to Type Information:: * f2c Skeletons and Prototypes:: * C++ Considerations:: * Startup Code::  File: g77.info, Node: C Interfacing Tools, Next: C Access to Type Information, Up: Interoperating with C and C++ C Interfacing Tools ------------------- Even if you don't actually use it as a compiler, `f2c' from `ftp://ftp.netlib.org/f2c/src', can be a useful tool when you're interfacing (linking) Fortran and C. *Note Generating Skeletons and Prototypes with `f2c': f2c Skeletons and Prototypes. To use `f2c' for this purpose you only need retrieve and build the `src' directory from the distribution, consult the `README' instructions there for machine-specifics, and install the `f2c' program on your path. Something else that might be useful is `cfortran.h' from `ftp://zebra/desy.de/cfortran'. This is a fairly general tool which can be used to generate interfaces for calling in both directions between Fortran and C. It can be used in `f2c' mode with `g77'--consult its documentation for details.  File: g77.info, Node: C Access to Type Information, Next: f2c Skeletons and Prototypes, Prev: C Interfacing Tools, Up: Interoperating with C and C++ Accessing Type Information in C ------------------------------- Generally, C code written to link with `g77' code--calling and/or being called from Fortran--should `#include ' to define the C versions of the Fortran types. Don't assume Fortran `INTEGER' types correspond to C `int's, for instance; instead, declare them as `integer', a type defined by `g2c.h'. `g2c.h' is installed where `gcc' will find it by default, assuming you use a copy of `gcc' compatible with `g77', probably built at the same time as `g77'.  File: g77.info, Node: f2c Skeletons and Prototypes, Next: C++ Considerations, Prev: C Access to Type Information, Up: Interoperating with C and C++ Generating Skeletons and Prototypes with `f2c' ---------------------------------------------- A simple and foolproof way to write `g77'-callable C routines--e.g. to interface with an existing library--is to write a file (named, for example, `fred.f') of dummy Fortran skeletons comprising just the declaration of the routine(s) and dummy arguments plus `END' statements. Then run `f2c' on file `fred.f' to produce `fred.c' into which you can edit useful code, confident the calling sequence is correct, at least. (There are some errors otherwise commonly made in generating C interfaces with `f2c' conventions, such as not using `doublereal' as the return type of a `REAL' `FUNCTION'.) `f2c' also can help with calling Fortran from C, using its `-P' option to generate C prototypes appropriate for calling the Fortran.(1) If the Fortran code containing any routines to be called from C is in file `joe.f', use the command `f2c -P joe.f' to generate the file `joe.P' containing prototype information. `#include' this in the C which has to call the Fortran routines to make sure you get it right. *Note Arrays (DIMENSION): Arrays, for information on the differences between the way Fortran (including compilers like `g77') and C handle arrays. ---------- Footnotes ---------- (1) The files generated like this can also be used for inter-unit consistency checking of dummy and actual arguments, although the `ftnchek' tool from `ftp://ftp.netlib.org/fortran' or `ftp://ftp.dsm.fordham.edu' is probably better for this purpose.  File: g77.info, Node: C++ Considerations, Next: Startup Code, Prev: f2c Skeletons and Prototypes, Up: Interoperating with C and C++ C++ Considerations ------------------ `f2c' can be used to generate suitable code for compilation with a C++ system using the `-C++' option. The important thing about linking `g77'-compiled code with C++ is that the prototypes for the `g77' routines must specify C linkage to avoid name mangling. So, use an `extern "C"' declaration. `f2c''s `-C++' option will take care of this when generating skeletons or prototype files as above, and also avoid clashes with C++ reserved words in addition to those in C.  File: g77.info, Node: Startup Code, Prev: C++ Considerations, Up: Interoperating with C and C++ Startup Code ------------ Unlike with some runtime systems, it shouldn't be necessary (unless there are bugs) to use a Fortran main program unit to ensure the runtime--specifically the I/O system--is initialized. However, to use the `g77' intrinsics `GETARG' and `IARGC', either the `main' routine from the `libg2c' library must be used, or the `f_setarg' routine (new as of `egcs' version 1.1 and `g77' version 0.5.23) must be called with the appropriate `argc' and `argv' arguments prior to the program calling `GETARG' or `IARGC'. To provide more flexibility for mixed-language programming involving `g77' while allowing for shared libraries, as of `egcs' version 1.1 and `g77' version 0.5.23, `g77''s `main' routine in `libg2c' does the following, in order: 1. Calls `f_setarg' with the incoming `argc' and `argv' arguments, in the same order as for `main' itself. This sets up the command-line environment for `GETARG' and `IARGC'. 2. Calls `f_setsig' (with no arguments). This sets up the signaling and exception environment. 3. Calls `f_init' (with no arguments). This initializes the I/O environment, though that should not be necessary, as all I/O functions in `libf2c' are believed to call `f_init' automatically, if necessary. (A future version of `g77' might skip this explicit step, to speed up normal exit of a program.) 4. Arranges for `f_exit' to be called (with no arguments) when the program exits. This ensures that the I/O environment is properly shut down before the program exits normally. Otherwise, output buffers might not be fully flushed, scratch files might not be deleted, and so on. The simple way `main' does this is to call `f_exit' itself after calling `MAIN__' (in the next step). However, this does not catch the cases where the program might call `exit' directly, instead of using the `EXIT' intrinsic (implemented as `exit_' in `libf2c'). So, `main' attempts to use the operating environment's `onexit' or `atexit' facility, if available, to cause `f_exit' to be called automatically upon any invocation of `exit'. 5. Calls `MAIN__' (with no arguments). This starts executing the Fortran main program unit for the application. (Both `g77' and `f2c' currently compile a main program unit so that its global name is `MAIN__'.) 6. If no `onexit' or `atexit' is provided by the system, calls `f_exit'. 7. Calls `exit' with a zero argument, to signal a successful program termination. 8. Returns a zero value to the caller, to signal a successful program termination, in case `exit' doesn't exit on the system. All of the above names are C `extern' names, i.e. not mangled. When using the `main' procedure provided by `g77' without a Fortran main program unit, you need to provide `MAIN__' as the entry point for your C code. (Make sure you link the object file that defines that entry point with the rest of your program.) To provide your own `main' procedure in place of `g77''s, make sure you specify the object file defining that procedure *before* `-lg2c' on the `g77' command line. Since the `-lg2c' option is implicitly provided, this is usually straightforward. (Use the `--verbose' option to see how and where `g77' implicitly adds `-lg2c' in a command line that will link the program. Feel free to specify `-lg2c' explicitly, as appropriate.) However, when providing your own `main', make sure you perform the appropriate tasks in the appropriate order. For example, if your `main' does not call `f_setarg', make sure the rest of your application does not call `GETARG' or `IARGC'. And, if your `main' fails to ensure that `f_exit' is called upon program exit, some files might end up incompletely written, some scratch files might be left lying around, and some existing files being written might be left with old data not properly truncated at the end. Note that, generally, the `g77' operating environment does not depend on a procedure named `MAIN__' actually being called prior to any other `g77'-compiled code. That is, `MAIN__' does not, itself, set up any important operating-environment characteristics upon which other code might depend. This might change in future versions of `g77', with appropriate notification in the release notes. For more information, consult the source code for the above routines. These are in `egcs/libf2c/libF77/', named `main.c', `setarg.c', `setsig.c', `getarg_.c', and `iargc_.c'. Also, the file `egcs/gcc/f/com.c' contains the code `g77' uses to open-code (inline) references to `IARGC'.  File: g77.info, Node: Installation, Next: Debugging and Interfacing, Prev: Other Languages, Up: Top Installing GNU Fortran ********************** The following information describes how to install `g77'. Note that, for users of the GCC-2.95 version of `g77', much of the information is obsolete, and is superceded by the GCC installation procedures. Such information is accordingly omitted and flagged as such. The following information was last updated on 1999-07-17: * Menu: * Prerequisites:: Make sure your system is ready for `g77'. * Problems Installing:: Known trouble areas. * Settings:: Changing `g77' internals before building. * Quick Start:: The easier procedure for non-experts. * Complete Installation:: For experts, or those who want to be: the details. * Distributing Binaries:: If you plan on distributing your `g77'.  File: g77.info, Node: Prerequisites, Next: Problems Installing, Up: Installation Prerequisites ============= For users of the GCC-2.95 version of `g77', this information is superceded by the GCC installation instructions.  File: g77.info, Node: Problems Installing, Next: Settings, Prev: Prerequisites, Up: Installation Problems Installing =================== This is a list of problems (and some apparent problems which don't really mean anything is wrong) that show up when configuring, building, installing, or porting GNU Fortran. *Note Installation Problems: (gcc)Installation Problems, for more information on installation problems that can afflict either `gcc' or `g77'. * Menu: * General Problems:: Problems afflicting most or all systems. * System-specific Problems:: Problems afflicting particular systems. * Cross-compiler Problems:: Problems afflicting cross-compilation setups.  File: g77.info, Node: General Problems, Next: System-specific Problems, Up: Problems Installing General Problems ---------------- These problems can occur on most or all systems. * Menu: * GNU C Required:: Why even ANSI C is not enough. * Patching GNU CC:: Why `gcc' needn't be patched. * Building GNU CC Necessary:: Why you can't build *just* Fortran. * Missing strtoul or bsearch:: When linking `f771' fails. * Cleanup Kills Stage Directories:: For `g77' developers. * LANGUAGES Macro Ignored:: Sometimes `LANGUAGES' is ignored.  File: g77.info, Node: GNU C Required, Next: Patching GNU CC, Up: General Problems GNU C Required .............. Compiling `g77' requires GNU C, not just ANSI C. Fixing this wouldn't be very hard (just tedious), but the code using GNU extensions to the C language is expected to be rewritten for 0.6 anyway, so there are no plans for an interim fix. This requirement does not mean you must already have `gcc' installed to build `g77'. As long as you have a working C compiler, you can use a "bootstrap" build to automate the process of first building `gcc' using the working C compiler you have, then building `g77' and rebuilding `gcc' using that just-built `gcc', and so on.  File: g77.info, Node: Patching GNU CC, Next: Building GNU CC Necessary, Prev: GNU C Required, Up: General Problems Patching GNU CC ............... `g77' no longer requires application of a patch file to the `gcc' compiler tree. In fact, no such patch file is distributed with `g77'. This is as of version 0.5.23 and `egcs' version 1.0.  File: g77.info, Node: Building GNU CC Necessary, Next: Missing strtoul or bsearch, Prev: Patching GNU CC, Up: General Problems Building GNU CC Necessary ......................... It should be possible to build the runtime without building `cc1' and other non-Fortran items, but, for now, an easy way to do that is not yet established.  File: g77.info, Node: Missing strtoul or bsearch, Next: Cleanup Kills Stage Directories, Prev: Building GNU CC Necessary, Up: General Problems Missing strtoul or bsearch .......................... This information does not apply to the GCC-2.95 version of `g77',  File: g77.info, Node: Cleanup Kills Stage Directories, Next: LANGUAGES Macro Ignored, Prev: Missing strtoul or bsearch, Up: General Problems Cleanup Kills Stage Directories ............................... It'd be helpful if `g77''s `Makefile.in' or `Make-lang.in' would create the various `stageN' directories and their subdirectories, so developers and expert installers wouldn't have to reconfigure after cleaning up. That help has arrived as of version 0.5.23 of `g77' and version 1.1 of `egcs'. Configuration itself no longer creates any particular directories that are unique to `g77'. The build procedures in `Make-lang.in' take care of that, on demand.  File: g77.info, Node: LANGUAGES Macro Ignored, Prev: Cleanup Kills Stage Directories, Up: General Problems LANGUAGES Macro Ignored ....................... Prior to version 0.5.23 of `g77' and version 1.1 of `egcs', `g77' would sometimes ignore the absence of `f77' and `F77' in the `LANGUAGES' macro definition used for the `make' command being processed. As of `g77' version 0.5.23 and `egcs' version 1.1, `g77' now obeys this macro in all relevant situations. However, in versions of `gcc' through 2.8.1, non-`g77' portions of `gcc', such as `g++', are known to go ahead and perform various language-specific activities when their respective language strings do not appear in the `LANGUAGES' macro in effect during that invocation of `make'. It is expected that these remaining problems will be fixed in a future version of `gcc'.  File: g77.info, Node: System-specific Problems, Next: Cross-compiler Problems, Prev: General Problems, Up: Problems Installing System-specific Problems ------------------------ A linker bug on some versions of AIX 4.1 might prevent building when `g77' is built within `gcc'. It might also occur when building within `egcs'. *Note LINKFAIL::.  File: g77.info, Node: Cross-compiler Problems, Prev: System-specific Problems, Up: Problems Installing Cross-compiler Problems ----------------------- `g77' has been in alpha testing since September of 1992, and in public beta testing since February of 1995. Alpha testing was done by a small number of people worldwide on a fairly wide variety of machines, involving self-compilation in most or all cases. Beta testing has been done primarily via self-compilation, but in more and more cases, cross-compilation (and "criss-cross compilation", where a version of a compiler is built on one machine to run on a second and generate code that runs on a third) has been tried and has succeeded, to varying extents. Generally, `g77' can be ported to any configuration to which `gcc', `f2c', and `libf2c' can be ported and made to work together, aside from the known problems described in this manual. If you want to port `g77' to a particular configuration, you should first make sure `gcc' and `libf2c' can be ported to that configuration before focusing on `g77', because `g77' is so dependent on them. Even for cases where `gcc' and `libf2c' work, you might run into problems with cross-compilation on certain machines, for several reasons. * There is one known bug (a design bug to be fixed in 0.6) that prevents configuration of `g77' as a cross-compiler in some cases, though there are assumptions made during configuration that probably make doing non-self-hosting builds a hassle, requiring manual intervention. * `gcc' might still have some trouble being configured for certain combinations of machines. For example, it might not know how to handle floating-point constants. * Improvements to the way `libg2c' is built could make building `g77' as a cross-compiler easier--for example, passing and using `$(LD)' and `$(AR)' in the appropriate ways. (This is improved in the `egcs' version of `g77', especially as of version 1.1.) * There are still some challenges putting together the right run-time libraries (needed by `libg2c') for a target system, depending on the systems involved in the configuration. (This is a general problem with cross-compilation, and with `gcc' in particular.)  File: g77.info, Node: Settings, Next: Quick Start, Prev: Problems Installing, Up: Installation Changing Settings Before Building ================================= Here are some internal `g77' settings that can be changed by editing source files in `egcs/gcc/f/' before building. This information, and perhaps even these settings, represent stop-gap solutions to problems people doing various ports of `g77' have encountered. As such, none of the following information is expected to be pertinent in future versions of `g77'. * Menu: * Larger File Unit Numbers:: Raising `MXUNIT'. * Always Flush Output:: Synchronizing write errors. * Maximum Stackable Size:: Large arrays forced off the stack. * Floating-point Bit Patterns:: Possible programs building `g77' as a cross-compiler. * Large Initialization:: Large arrays with `DATA' initialization. * Alpha Problems Fixed:: Problems with 64-bit systems like Alphas now fixed?  File: g77.info, Node: Larger File Unit Numbers, Next: Always Flush Output, Up: Settings Larger File Unit Numbers ------------------------ As distributed, whether as part of `f2c' or `g77', `libf2c' accepts file unit numbers only in the range 0 through 99. For example, a statement such as `WRITE (UNIT=100)' causes a run-time crash in `libf2c', because the unit number, 100, is out of range. If you know that Fortran programs at your installation require the use of unit numbers higher than 99, you can change the value of the `MXUNIT' macro, which represents the maximum unit number, to an appropriately higher value. To do this, edit the file `egcs/libf2c/libI77/fio.h' in your `g77' source tree, changing the following line: #define MXUNIT 100 Change the line so that the value of `MXUNIT' is defined to be at least one *greater* than the maximum unit number used by the Fortran programs on your system. (For example, a program that does `WRITE (UNIT=255)' would require `MXUNIT' set to at least 256 to avoid crashing.) Then build or rebuild `g77' as appropriate. *Note:* Changing this macro has *no* effect on other limits your system might place on the number of files open at the same time. That is, the macro might allow a program to do `WRITE (UNIT=100)', but the library and operating system underlying `libf2c' might disallow it if many other files have already been opened (via `OPEN' or implicitly via `READ', `WRITE', and so on). Information on how to increase these other limits should be found in your system's documentation.  File: g77.info, Node: Always Flush Output, Next: Maximum Stackable Size, Prev: Larger File Unit Numbers, Up: Settings Always Flush Output ------------------- Some Fortran programs require output (writes) to be flushed to the operating system (under UNIX, via the `fflush()' library call) so that errors, such as disk full, are immediately flagged via the relevant `ERR=' and `IOSTAT=' mechanism, instead of such errors being flagged later as subsequent writes occur, forcing the previously written data to disk, or when the file is closed. Essentially, the difference can be viewed as synchronous error reporting (immediate flagging of errors during writes) versus asynchronous, or, more precisely, buffered error reporting (detection of errors might be delayed). `libg2c' supports flagging write errors immediately when it is built with the `ALWAYS_FLUSH' macro defined. This results in a `libg2c' that runs slower, sometimes quite a bit slower, under certain circumstances--for example, accessing files via the networked file system NFS--but the effect can be more reliable, robust file I/O. If you know that Fortran programs requiring this level of precision of error reporting are to be compiled using the version of `g77' you are building, you might wish to modify the `g77' source tree so that the version of `libg2c' is built with the `ALWAYS_FLUSH' macro defined, enabling this behavior. To do this, find this line in `egcs/libf2c/f2c.h' in your `g77' source tree: /* #define ALWAYS_FLUSH */ Remove the leading `/* ', so the line begins with `#define', and the trailing ` */'. Then build or rebuild `g77' as appropriate.  File: g77.info, Node: Maximum Stackable Size, Next: Floating-point Bit Patterns, Prev: Always Flush Output, Up: Settings Maximum Stackable Size ---------------------- `g77', on most machines, puts many variables and arrays on the stack where possible, and can be configured (by changing `FFECOM_sizeMAXSTACKITEM' in `egcs/gcc/f/com.c') to force smaller-sized entities into static storage (saving on stack space) or permit larger-sized entities to be put on the stack (which can improve run-time performance, as it presents more opportunities for the GBE to optimize the generated code). *Note:* Putting more variables and arrays on the stack might cause problems due to system-dependent limits on stack size. Also, the value of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and arrays. *Note But-bugs::, for more information.  File: g77.info, Node: Floating-point Bit Patterns, Next: Large Initialization, Prev: Maximum Stackable Size, Up: Settings Floating-point Bit Patterns --------------------------- The `g77' build will crash if an attempt is made to build it as a cross-compiler for a target when `g77' cannot reliably determine the bit pattern of floating-point constants for the target. Planned improvements for version 0.6 of `g77' will give it the capabilities it needs to not have to crash the build but rather generate correct code for the target. (Currently, `g77' would generate bad code under such circumstances if it didn't crash during the build, e.g. when compiling a source file that does something like `EQUIVALENCE (I,R)' and `DATA R/9.43578/'.)  File: g77.info, Node: Large Initialization, Next: Alpha Problems Fixed, Prev: Floating-point Bit Patterns, Up: Settings Initialization of Large Aggregate Areas --------------------------------------- A warning message is issued when `g77' sees code that provides initial values (e.g. via `DATA') to an aggregate area (`COMMON' or `EQUIVALENCE', or even a large enough array or `CHARACTER' variable) that is large enough to increase `g77''s compile time by roughly a factor of 10. This size currently is quite small, since `g77' currently has a known bug requiring too much memory and time to handle such cases. In `egcs/gcc/f/data.c', the macro `FFEDATA_sizeTOO_BIG_INIT_' is defined to the minimum size for the warning to appear. The size is specified in storage units, which can be bytes, words, or whatever, on a case-by-case basis. After changing this macro definition, you must (of course) rebuild and reinstall `g77' for the change to take effect. Note that, as of version 0.5.18, improvements have reduced the scope of the problem for *sparse* initialization of large arrays, especially those with large, contiguous uninitialized areas. However, the warning is issued at a point prior to when `g77' knows whether the initialization is sparse, and delaying the warning could mean it is produced too late to be helpful. Therefore, the macro definition should not be adjusted to reflect sparse cases. Instead, adjust it to generate the warning when densely initialized arrays begin to cause responses noticeably slower than linear performance would suggest.  File: g77.info, Node: Alpha Problems Fixed, Prev: Large Initialization, Up: Settings Alpha Problems Fixed -------------------- `g77' used to warn when it was used to compile Fortran code for a target configuration that is not basically a 32-bit machine (such as an Alpha, which is a 64-bit machine, especially if it has a 64-bit operating system running on it). That was because `g77' was known to not work properly on such configurations. As of version 0.5.20, `g77' is believed to work well enough on such systems. So, the warning is no longer needed or provided. However, support for 64-bit systems, especially in areas such as cross-compilation and handling of intrinsics, is still incomplete. The symptoms are believed to be compile-time diagnostics rather than the generation of bad code. It is hoped that version 0.6 will completely support 64-bit systems.  File: g77.info, Node: Quick Start, Next: Complete Installation, Prev: Settings, Up: Installation Quick Start =========== For users of the GCC-2.95 version of `g77', this information is superceded by the GCC installation instructions.  File: g77.info, Node: Complete Installation, Next: Distributing Binaries, Prev: Quick Start, Up: Installation Complete Installation ===================== For users of the GCC-2.95 version of `g77', this information is superceded by the GCC installation instructions.  File: g77.info, Node: Distributing Binaries, Prev: Complete Installation, Up: Installation Distributing Binaries ===================== For users of the GCC-2.95 version of `g77', this information is superceded by the GCC installation instructions.  File: g77.info, Node: Debugging and Interfacing, Next: Collected Fortran Wisdom, Prev: Installation, Up: Top Debugging and Interfacing ************************* GNU Fortran currently generates code that is object-compatible with the `f2c' converter. Also, it avoids limitations in the current GBE, such as the inability to generate a procedure with multiple entry points, by generating code that is structured differently (in terms of procedure names, scopes, arguments, and so on) than might be expected. As a result, writing code in other languages that calls on, is called by, or shares in-memory data with `g77'-compiled code generally requires some understanding of the way `g77' compiles code for various constructs. Similarly, using a debugger to debug `g77'-compiled code, even if that debugger supports native Fortran debugging, generally requires this sort of information. This section describes some of the basic information on how `g77' compiles code for constructs involving interfaces to other languages and to debuggers. *Caution:* Much or all of this information pertains to only the current release of `g77', sometimes even to using certain compiler options with `g77' (such as `-fno-f2c'). Do not write code that depends on this information without clearly marking said code as nonportable and subject to review for every new release of `g77'. This information is provided primarily to make debugging of code generated by this particular release of `g77' easier for the user, and partly to make writing (generally nonportable) interface code easier. Both of these activities require tracking changes in new version of `g77' as they are installed, because new versions can change the behaviors described in this section. * Menu: * Main Program Unit:: How `g77' compiles a main program unit. * Procedures:: How `g77' constructs parameter lists for procedures. * Functions:: Functions returning floating-point or character data. * Names:: Naming of user-defined variables, procedures, etc. * Common Blocks:: Accessing common variables while debugging. * Local Equivalence Areas:: Accessing `EQUIVALENCE' while debugging. * Complex Variables:: How `g77' performs complex arithmetic. * Arrays:: Dealing with (possibly multi-dimensional) arrays. * Adjustable Arrays:: Special consideration for adjustable arrays. * Alternate Entry Points:: How `g77' implements alternate `ENTRY'. * Alternate Returns:: How `g77' handles alternate returns. * Assigned Statement Labels:: How `g77' handles `ASSIGN'. * Run-time Library Errors:: Meanings of some `IOSTAT=' values.  File: g77.info, Node: Main Program Unit, Next: Procedures, Up: Debugging and Interfacing Main Program Unit (PROGRAM) =========================== When `g77' compiles a main program unit, it gives it the public procedure name `MAIN__'. The `libg2c' library has the actual `main()' procedure as is typical of C-based environments, and it is this procedure that performs some initial start-up activity and then calls `MAIN__'. Generally, `g77' and `libg2c' are designed so that you need not include a main program unit written in Fortran in your program--it can be written in C or some other language. Especially for I/O handling, this is the case, although `g77' version 0.5.16 includes a bug fix for `libg2c' that solved a problem with using the `OPEN' statement as the first Fortran I/O activity in a program without a Fortran main program unit. However, if you don't intend to use `g77' (or `f2c') to compile your main program unit--that is, if you intend to compile a `main()' procedure using some other language--you should carefully examine the code for `main()' in `libg2c', found in the source file `egcs/libf2c/libF77/main.c', to see what kinds of things might need to be done by your `main()' in order to provide the Fortran environment your Fortran code is expecting. For example, `libg2c''s `main()' sets up the information used by the `IARGC' and `GETARG' intrinsics. Bypassing `libg2c''s `main()' without providing a substitute for this activity would mean that invoking `IARGC' and `GETARG' would produce undefined results. When debugging, one implication of the fact that `main()', which is the place where the debugged program "starts" from the debugger's point of view, is in `libg2c' is that you won't be starting your Fortran program at a point you recognize as your Fortran code. The standard way to get around this problem is to set a break point (a one-time, or temporary, break point will do) at the entrance to `MAIN__', and then run the program. A convenient way to do so is to add the `gdb' command tbreak MAIN__ to the file `.gdbinit' in the directory in which you're debugging (using `gdb'). After doing this, the debugger will see the current execution point of the program as at the beginning of the main program unit of your program. Of course, if you really want to set a break point at some other place in your program and just start the program running, without first breaking at `MAIN__', that should work fine.  File: g77.info, Node: Procedures, Next: Functions, Prev: Main Program Unit, Up: Debugging and Interfacing Procedures (SUBROUTINE and FUNCTION) ==================================== Currently, `g77' passes arguments via reference--specifically, by passing a pointer to the location in memory of a variable, array, array element, a temporary location that holds the result of evaluating an expression, or a temporary or permanent location that holds the value of a constant. Procedures that accept `CHARACTER' arguments are implemented by `g77' so that each `CHARACTER' argument has two actual arguments. The first argument occupies the expected position in the argument list and has the user-specified name. This argument is a pointer to an array of characters, passed by the caller. The second argument is appended to the end of the user-specified calling sequence and is named `__g77_length_X', where X is the user-specified name. This argument is of the C type `ftnlen' (see `egcs/libf2c/g2c.h.in' for information on that type) and is the number of characters the caller has allocated in the array pointed to by the first argument. A procedure will ignore the length argument if `X' is not declared `CHARACTER*(*)', because for other declarations, it knows the length. Not all callers necessarily "know" this, however, which is why they all pass the extra argument. The contents of the `CHARACTER' argument are specified by the address passed in the first argument (named after it). The procedure can read or write these contents as appropriate. When more than one `CHARACTER' argument is present in the argument list, the length arguments are appended in the order the original arguments appear. So `CALL FOO('HI','THERE')' is implemented in C as `foo("hi","there",2,5);', ignoring the fact that `g77' does not provide the trailing null bytes on the constant strings (`f2c' does provide them, but they are unnecessary in a Fortran environment, and you should not expect them to be there). Note that the above information applies to `CHARACTER' variables and arrays *only*. It does *not* apply to external `CHARACTER' functions or to intrinsic `CHARACTER' functions. That is, no second length argument is passed to `FOO' in this case: CHARACTER X EXTERNAL X CALL FOO(X) Nor does `FOO' expect such an argument in this case: SUBROUTINE FOO(X) CHARACTER X EXTERNAL X Because of this implementation detail, if a program has a bug such that there is disagreement as to whether an argument is a procedure, and the type of the argument is `CHARACTER', subtle symptoms might appear.  File: g77.info, Node: Functions, Next: Names, Prev: Procedures, Up: Debugging and Interfacing Functions (FUNCTION and RETURN) =============================== `g77' handles in a special way functions that return the following types: * `CHARACTER' * `COMPLEX' * `REAL(KIND=1)' For `CHARACTER', `g77' implements a subroutine (a C function returning `void') with two arguments prepended: `__g77_result', which the caller passes as a pointer to a `char' array expected to hold the return value, and `__g77_length', which the caller passes as an `ftnlen' value specifying the length of the return value as declared in the calling program. For `CHARACTER*(*)', the called function uses `__g77_length' to determine the size of the array that `__g77_result' points to; otherwise, it ignores that argument. For `COMPLEX', when `-ff2c' is in force, `g77' implements a subroutine with one argument prepended: `__g77_result', which the caller passes as a pointer to a variable of the type of the function. The called function writes the return value into this variable instead of returning it as a function value. When `-fno-f2c' is in force, `g77' implements a `COMPLEX' function as `gcc''s `__complex__ float' or `__complex__ double' function (or an emulation thereof, when `-femulate-complex' is in effect), returning the result of the function in the same way as `gcc' would. For `REAL(KIND=1)', when `-ff2c' is in force, `g77' implements a function that actually returns `REAL(KIND=2)' (typically C's `double' type). When `-fno-f2c' is in force, `REAL(KIND=1)' functions return `float'.  File: g77.info, Node: Names, Next: Common Blocks, Prev: Functions, Up: Debugging and Interfacing Names ===== Fortran permits each implementation to decide how to represent names as far as how they're seen in other contexts, such as debuggers and when interfacing to other languages, and especially as far as how casing is handled. External names--names of entities that are public, or "accessible", to all modules in a program--normally have an underscore (`_') appended by `g77', to generate code that is compatible with `f2c'. External names include names of Fortran things like common blocks, external procedures (subroutines and functions, but not including statement functions, which are internal procedures), and entry point names. However, use of the `-fno-underscoring' option disables this kind of transformation of external names (though inhibiting the transformation certainly improves the chances of colliding with incompatible externals written in other languages--but that might be intentional. When `-funderscoring' is in force, any name (external or local) that already has at least one underscore in it is implemented by `g77' by appending two underscores. (This second underscore can be disabled via the `-fno-second-underscore' option.) External names are changed this way for `f2c' compatibility. Local names are changed this way to avoid collisions with external names that are different in the source code--`f2c' does the same thing, but there's no compatibility issue there except for user expectations while debugging. For example: Max_Cost = 0 Here, a user would, in the debugger, refer to this variable using the name `max_cost__' (or `MAX_COST__' or `Max_Cost__', as described below). (We hope to improve `g77' in this regard in the future--don't write scripts depending on this behavior! Also, consider experimenting with the `-fno-underscoring' option to try out debugging without having to massage names by hand like this.) `g77' provides a number of command-line options that allow the user to control how case mapping is handled for source files. The default is the traditional UNIX model for Fortran compilers--names are mapped to lower case. Other command-line options can be specified to map names to upper case, or to leave them exactly as written in the source file. For example: Foo = 9.436 Here, it is normally the case that the variable assigned will be named `foo'. This would be the name to enter when using a debugger to access the variable. However, depending on the command-line options specified, the name implemented by `g77' might instead be `FOO' or even `Foo', thus affecting how debugging is done. Also: Call Foo This would normally call a procedure that, if it were in a separate C program, be defined starting with the line: void foo_() However, `g77' command-line options could be used to change the casing of names, resulting in the name `FOO_' or `Foo_' being given to the procedure instead of `foo_', and the `-fno-underscoring' option could be used to inhibit the appending of the underscore to the name.