+++ /dev/null
-@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.
projects / msp430-gcc.git / blobdiff