freebsd/contrib/gcc/doc/vms.texi

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node VMS
@chapter Using GCC on VMS

@c prevent bad page break with this line
Here is how to use GCC on VMS@.

@menu
* Include Files and VMS::  Where the preprocessor looks for the include files.
* Global Declarations::    How to do globaldef, globalref and globalvalue with
                           GCC.
* VMS Misc::		   Misc information.
@end menu

@node Include Files and VMS
@section Include Files and VMS

@cindex include files and VMS
@cindex VMS and include files
@cindex header files and VMS
Due to the differences between the filesystems of Unix and VMS, GCC
attempts to translate file names in @samp{#include} into names that VMS
will understand.  The basic strategy is to prepend a prefix to the
specification of the include file, convert the whole filename to a VMS
filename, and then try to open the file.  GCC tries various prefixes
one by one until one of them succeeds:

@enumerate
@item
The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
where GNU C header files are traditionally stored.  If you wish to store
header files in non-standard locations, then you can assign the logical
@samp{GNU_CC_INCLUDE} to be a search list, where each element of the
list is suitable for use with a rooted logical.

@item
The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
VAX-C header files are traditionally stored.

@item
If the include file specification by itself is a valid VMS filename, the
preprocessor then uses this name with no prefix in an attempt to open
the include file.

@item
If the file specification is not a valid VMS filename (i.e.@: does not
contain a device or a directory specifier, and contains a @samp{/}
character), the preprocessor tries to convert it from Unix syntax to
VMS syntax.

Conversion works like this: the first directory name becomes a device,
and the rest of the directories are converted into VMS-format directory
names.  For example, the name @file{X11/foobar.h} is
translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
whichever one can be opened.  This strategy allows you to assign a
logical name to point to the actual location of the header files.

@item
If none of these strategies succeeds, the @samp{#include} fails.
@end enumerate

Include directives of the form:

@example
#include foobar
@end example

@noindent
are a common source of incompatibility between VAX-C and GCC@.  VAX-C
treats this much like a standard @code{#include <foobar.h>} directive.
That is incompatible with the ISO C behavior implemented by GCC: to
expand the name @code{foobar} as a macro.  Macro expansion should
eventually yield one of the two standard formats for @code{#include}:

@example
#include "@var{file}"
#include <@var{file}>
@end example

If you have this problem, the best solution is to modify the source to
convert the @code{#include} directives to one of the two standard forms.
That will work with either compiler.  If you want a quick and dirty fix,
define the file names as macros with the proper expansion, like this:

@example
#define stdio <stdio.h>
@end example

@noindent
This will work, as long as the name doesn't conflict with anything else
in the program.

Another source of incompatibility is that VAX-C assumes that:

@example
#include "foobar"
@end example

@noindent
is actually asking for the file @file{foobar.h}.  GCC does not
make this assumption, and instead takes what you ask for literally;
it tries to read the file @file{foobar}.  The best way to avoid this
problem is to always specify the desired file extension in your include
directives.

GCC for VMS is distributed with a set of include files that is
sufficient to compile most general purpose programs.  Even though the
GCC distribution does not contain header files to define constants
and structures for some VMS system-specific functions, there is no
reason why you cannot use GCC with any of these functions.  You first
may have to generate or create header files, either by using the public
domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
extracting the relevant modules from one of the system macro libraries,
and using an editor to construct a C header file.

A @code{#include} file name cannot contain a DECNET node name.  The
preprocessor reports an I/O error if you attempt to use a node name,
whether explicitly, or implicitly via a logical name.

@node Global Declarations
@section Global Declarations and VMS

@findex GLOBALREF
@findex GLOBALDEF
@findex GLOBALVALUEDEF
@findex GLOBALVALUEREF
GCC does not provide the @code{globalref}, @code{globaldef} and
@code{globalvalue} keywords of VAX-C@.  You can get the same effect with
an obscure feature of GAS, the GNU assembler.  (This requires GAS
version 1.39 or later.)  The following macros allow you to use this
feature in a fairly natural way:

@smallexample
#ifdef __GNUC__
#define GLOBALREF(TYPE,NAME)                      \
  TYPE NAME                                       \
  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
#define GLOBALDEF(TYPE,NAME,VALUE)                \
  TYPE NAME                                       \
  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
    = VALUE
#define GLOBALVALUEREF(TYPE,NAME)                 \
  const TYPE NAME[1]                              \
  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
#define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
  const TYPE NAME[1]                              \
  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
    = @{VALUE@}
#else
#define GLOBALREF(TYPE,NAME) \
  globalref TYPE NAME
#define GLOBALDEF(TYPE,NAME,VALUE) \
  globaldef TYPE NAME = VALUE
#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
  globalvalue TYPE NAME = VALUE
#define GLOBALVALUEREF(TYPE,NAME) \
  globalvalue TYPE NAME
#endif
@end smallexample

@noindent
(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
name is removed by the assembler, after it has modified the attributes
of the symbol).  These macros are provided in the VMS binaries
distribution in a header file @file{GNU_HACKS.H}.  An example of the
usage is:

@example
GLOBALREF (int, ijk);
GLOBALDEF (int, jkl, 0);
@end example

The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
straightforwardly for arrays, since there is no way to insert the array
dimension into the declaration at the right place.  However, you can
declare an array with these macros if you first define a typedef for the
array type, like this:

@example
typedef int intvector[10];
GLOBALREF (intvector, foo);
@end example

Array and structure initializers will also break the macros; you can
define the initializer to be a macro of its own, or you can expand the
@code{GLOBALDEF} macro by hand.  You may find a case where you wish to
use the @code{GLOBALDEF} macro with a large array, but you are not
interested in explicitly initializing each element of the array.  In
such cases you can use an initializer like: @code{@{0,@}}, which will
initialize the entire array to @code{0}.

A shortcoming of this implementation is that a variable declared with
@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
example, the declaration:

@example
GLOBALVALUEREF(int, ijk);
@end example

@noindent
declares the variable @code{ijk} as an array of type @code{int [1]}.
This is done because a globalvalue is actually a constant; its ``value''
is what the linker would normally consider an address.  That is not how
an integer value works in C, but it is how an array works.  So treating
the symbol as an array name gives consistent results---with the
exception that the value seems to have the wrong type.  @strong{Don't
try to access an element of the array.}  It doesn't have any elements.
The array ``address'' may not be the address of actual storage.

The fact that the symbol is an array may lead to warnings where the
variable is used.  Insert type casts to avoid the warnings.  Here is an
example; it takes advantage of the ISO C feature allowing macros that
expand to use the same name as the macro itself.

@example
GLOBALVALUEREF (int, ss$_normal);
GLOBALVALUEDEF (int, xyzzy,123);
#ifdef __GNUC__
#define ss$_normal ((int) ss$_normal)
#define xyzzy ((int) xyzzy)
#endif
@end example

Don't use @code{globaldef} or @code{globalref} with a variable whose
type is an enumeration type; this is not implemented.  Instead, make the
variable an integer, and use a @code{globalvaluedef} for each of the
enumeration values.  An example of this would be:

@example
#ifdef __GNUC__
GLOBALDEF (int, color, 0);
GLOBALVALUEDEF (int, RED, 0);
GLOBALVALUEDEF (int, BLUE, 1);
GLOBALVALUEDEF (int, GREEN, 3);
#else
enum globaldef color @{RED, BLUE, GREEN = 3@};
#endif
@end example

@node VMS Misc
@section Other VMS Issues

@cindex exit status and VMS
@cindex return value of @code{main}
@cindex @code{main} and the exit status
GCC automatically arranges for @code{main} to return 1 by default if
you fail to specify an explicit return value.  This will be interpreted
by VMS as a status code indicating a normal successful completion.
Version 1 of GCC did not provide this default.

GCC on VMS works only with the GNU assembler, GAS@.  You need version
1.37 or later of GAS in order to produce value debugging information for
the VMS debugger.  Use the ordinary VMS linker with the object files
produced by GAS@.

@cindex shared VMS run time system
@cindex @file{VAXCRTL}
Under previous versions of GCC, the generated code would occasionally
give strange results when linked to the sharable @file{VAXCRTL} library.
Now this should work.

A caveat for use of @code{const} global variables: the @code{const}
modifier must be specified in every external declaration of the variable
in all of the source files that use that variable.  Otherwise the linker
will issue warnings about conflicting attributes for the variable.  Your
program will still work despite the warnings, but the variable will be
placed in writable storage.

@cindex name augmentation
@cindex case sensitivity and VMS
@cindex VMS and case sensitivity
Although the VMS linker does distinguish between upper and lower case
letters in global symbols, most VMS compilers convert all such symbols
into upper case and most run-time library routines also have upper case
names.  To be able to reliably call such routines, GCC (by means of
the assembler GAS) converts global symbols into upper case like other
VMS compilers.  However, since the usual practice in C is to distinguish
case, GCC (via GAS) tries to preserve usual C behavior by augmenting
each name that is not all lower case.  This means truncating the name
to at most 23 characters and then adding more characters at the end
which encode the case pattern of those 23.   Names which contain at
least one dollar sign are an exception; they are converted directly into
upper case without augmentation.

Name augmentation yields bad results for programs that use precompiled
libraries (such as Xlib) which were generated by another compiler.  You
can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
it makes external C functions and variables case-independent as is usual
on VMS@.  Alternatively, you could write all references to the functions
and variables in such libraries using lower case; this will work on VMS,
but is not portable to other systems.  The compiler option @samp{/NAMES}
also provides control over global name handling.

Function and variable names are handled somewhat differently with G++.
The GNU C++ compiler performs @dfn{name mangling} on function
names, which means that it adds information to the function name to
describe the data types of the arguments that the function takes.  One
result of this is that the name of a function can become very long.
Since the VMS linker only recognizes the first 31 characters in a name,
special action is taken to ensure that each function and variable has a
unique name that can be represented in 31 characters.

If the name (plus a name augmentation, if required) is less than 32
characters in length, then no special action is performed.  If the name
is longer than 31 characters, the assembler (GAS) will generate a
hash string based upon the function name, truncate the function name to
23 characters, and append the hash string to the truncated name.  If the
@samp{/VERBOSE} compiler option is used, the assembler will print both
the full and truncated names of each symbol that is truncated.

The @samp{/NOCASE_HACK} compiler option should not be used when you are
compiling programs that use libg++.  libg++ has several instances of
objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
indistinguishable in a case-insensitive environment.  This leads to
cases where you need to inhibit augmentation selectively (if you were
using libg++ and Xlib in the same program, for example).  There is no
special feature for doing this, but you can get the result by defining a
macro for each mixed case symbol for which you wish to inhibit
augmentation.  The macro should expand into the lower case equivalent of
itself.  For example:

@example
#define StuDlyCapS studlycaps
@end example

These macro definitions can be placed in a header file to minimize the
number of changes to your source code.