gcc/doc/hostconfig.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
   2 @c 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gccint.texi.
   5
   6 @node Host Config
   7 @chapter Host Configuration
   8 @cindex host configuration
   9
  10 Most details about the machine and system on which the compiler is
  11 actually running are detected by the @command{configure} script.  Some
  12 things are impossible for @command{configure} to detect; these are
  13 described in two ways, either by macros defined in a file named
  14 @file{xm-@var{machine}.h} or by hook functions in the file specified
  15 by the @var{out_host_hook_obj} variable in @file{config.gcc}.  (The
  16 intention is that very few hosts will need a header file but nearly
  17 every fully supported host will need to override some hooks.)
  18
  19 If you need to define only a few macros, and they have simple
  20 definitions, consider using the @code{xm_defines} variable in your
  21 @file{config.gcc} entry instead of creating a host configuration
  22 header.  @xref{System Config}.
  23
  24 @menu
  25 * Host Common::         Things every host probably needs implemented.
  26 * Filesystem::          Your host can't have the letter `a' in filenames?
  27 * Host Misc::           Rare configuration options for hosts.
  28 @end menu
  29
  30 @node Host Common
  31 @section Host Common
  32 @cindex host hooks
  33 @cindex host functions
  34
  35 Some things are just not portable, even between similar operating systems,
  36 and are too difficult for autoconf to detect.  They get implemented using
  37 hook functions in the file specified by the @var{host_hook_obj}
  38 variable in @file{config.gcc}.
  39
  40 @deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
  41 This host hook is used to set up handling for extra signals.  The most
  42 common thing to do in this hook is to detect stack overflow.
  43 @end deftypefn
  44
  45 @deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size}, int @var{fd})
  46 This host hook returns the address of some space that is likely to be
  47 free in some subsequent invocation of the compiler.  We intend to load
  48 the PCH data at this address such that the data need not be relocated.
  49 The area should be able to hold @var{size} bytes.  If the host uses
  50 @code{mmap}, @var{fd} is an open file descriptor that can be used for
  51 probing.
  52 @end deftypefn
  53
  54 @deftypefn {Host Hook} int HOST_HOOKS_GT_PCH_USE_ADDRESS (void * @var{address}, size_t @var{size}, int @var{fd}, size_t @var{offset})
  55 This host hook is called when a PCH file is about to be loaded.
  56 We want to load @var{size} bytes from @var{fd} at @var{offset}
  57 into memory at @var{address}.  The given address will be the result of
  58 a previous invocation of @code{HOST_HOOKS_GT_PCH_GET_ADDRESS}.
  59 Return @minus{}1 if we couldn't allocate @var{size} bytes at @var{address}.
  60 Return 0 if the memory is allocated but the data is not loaded.  Return 1
  61 if the hook has performed everything.
  62
  63 If the implementation uses reserved address space, free any reserved
  64 space beyond @var{size}, regardless of the return value.  If no PCH will
  65 be loaded, this hook may be called with @var{size} zero, in which case
  66 all reserved address space should be freed.
  67
  68 Do not try to handle values of @var{address} that could not have been
  69 returned by this executable; just return @minus{}1.  Such values usually
  70 indicate an out-of-date PCH file (built by some other GCC executable),
  71 and such a PCH file won't work.
  72 @end deftypefn
  73
  74 @node Filesystem
  75 @section Host Filesystem
  76 @cindex configuration file
  77 @cindex @file{xm-@var{machine}.h}
  78
  79 GCC needs to know a number of things about the semantics of the host
  80 machine's filesystem.  Filesystems with Unix and MS-DOS semantics are
  81 automatically detected.  For other systems, you can define the
  82 following macros in @file{xm-@var{machine}.h}.
  83
  84 @ftable @code
  85 @item HAVE_DOS_BASED_FILE_SYSTEM
  86 This macro is automatically defined by @file{system.h} if the host
  87 file system obeys the semantics defined by MS-DOS instead of Unix.
  88 DOS file systems are case insensitive, file specifications may begin
  89 with a drive letter, and both forward slash and backslash (@samp{/}
  90 and @samp{\}) are directory separators.
  91
  92 @item DIR_SEPARATOR
  93 @itemx DIR_SEPARATOR_2
  94 If defined, these macros expand to character constants specifying
  95 separators for directory names within a file specification.
  96 @file{system.h} will automatically give them appropriate values on
  97 Unix and MS-DOS file systems.  If your file system is neither of
  98 these, define one or both appropriately in @file{xm-@var{machine}.h}.
  99
 100 However, operating systems like VMS, where constructing a pathname is
 101 more complicated than just stringing together directory names
 102 separated by a special character, should not define either of these
 103 macros.
 104
 105 @item PATH_SEPARATOR
 106 If defined, this macro should expand to a character constant
 107 specifying the separator for elements of search paths.  The default
 108 value is a colon (@samp{:}).  DOS-based systems usually, but not
 109 always, use semicolon (@samp{;}).
 110
 111 @item VMS
 112 Define this macro if the host system is VMS@.
 113
 114 @item HOST_OBJECT_SUFFIX
 115 Define this macro to be a C string representing the suffix for object
 116 files on your host machine.  If you do not define this macro, GCC will
 117 use @samp{.o} as the suffix for object files.
 118
 119 @item HOST_EXECUTABLE_SUFFIX
 120 Define this macro to be a C string representing the suffix for
 121 executable files on your host machine.  If you do not define this macro,
 122 GCC will use the null string as the suffix for executable files.
 123
 124 @item HOST_BIT_BUCKET
 125 A pathname defined by the host operating system, which can be opened as
 126 a file and written to, but all the information written is discarded.
 127 This is commonly known as a @dfn{bit bucket} or @dfn{null device}.  If
 128 you do not define this macro, GCC will use @samp{/dev/null} as the bit
 129 bucket.  If the host does not support a bit bucket, define this macro to
 130 an invalid filename.
 131
 132 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
 133 If defined, a C statement (sans semicolon) that performs host-dependent
 134 canonicalization when a path used in a compilation driver or
 135 preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
 136 canonicalized.  If the C statement does canonicalize @var{path} into a
 137 different buffer, the old path should be freed and the new buffer should
 138 have been allocated with malloc.
 139
 140 @item DUMPFILE_FORMAT
 141 Define this macro to be a C string representing the format to use for
 142 constructing the index part of debugging dump file names.  The resultant
 143 string must fit in fifteen bytes.  The full filename will be the
 144 concatenation of: the prefix of the assembler file name, the string
 145 resulting from applying this format to an index number, and a string
 146 unique to each dump file kind, e.g. @samp{rtl}.
 147
 148 If you do not define this macro, GCC will use @samp{.%02d.}.  You should
 149 define this macro if using the default will create an invalid file name.
 150
 151 @item DELETE_IF_ORDINARY
 152 Define this macro to be a C statement (sans semicolon) that performs
 153 host-dependent removal of ordinary temp files in the compilation driver.
 154
 155 If you do not define this macro, GCC will use the default version. You
 156 should define this macro if the default version does not reliably remove
 157 the temp file as, for example, on VMS which allows multiple versions
 158 of a file.
 159 @end ftable
 160
 161 @node Host Misc
 162 @section Host Misc
 163 @cindex configuration file
 164 @cindex @file{xm-@var{machine}.h}
 165
 166 @ftable @code
 167 @item FATAL_EXIT_CODE
 168 A C expression for the status code to be returned when the compiler
 169 exits after serious errors.  The default is the system-provided macro
 170 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
 171 macro.  Define this macro only if these defaults are incorrect.
 172
 173 @item SUCCESS_EXIT_CODE
 174 A C expression for the status code to be returned when the compiler
 175 exits without serious errors.  (Warnings are not serious errors.)  The
 176 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
 177 the system doesn't define that macro.  Define this macro only if these
 178 defaults are incorrect.
 179
 180 @item USE_C_ALLOCA
 181 Define this macro if GCC should use the C implementation of @code{alloca}
 182 provided by @file{libiberty.a}.  This only affects how some parts of the
 183 compiler itself allocate memory.  It does not change code generation.
 184
 185 When GCC is built with a compiler other than itself, the C @code{alloca}
 186 is always used.  This is because most other implementations have serious
 187 bugs.  You should define this macro only on a system where no
 188 stack-based @code{alloca} can possibly work.  For instance, if a system
 189 has a small limit on the size of the stack, GCC's builtin @code{alloca}
 190 will not work reliably.
 191
 192 @item COLLECT2_HOST_INITIALIZATION
 193 If defined, a C statement (sans semicolon) that performs host-dependent
 194 initialization when @code{collect2} is being initialized.
 195
 196 @item GCC_DRIVER_HOST_INITIALIZATION
 197 If defined, a C statement (sans semicolon) that performs host-dependent
 198 initialization when a compilation driver is being initialized.
 199
 200 @item SMALL_ARG_MAX
 201 Define this macro if the host system has a small limit on the total
 202 size of an argument vector.  This causes the driver to take more care
 203 not to pass unnecessary arguments to subprocesses.
 204 @end ftable
 205
 206 In addition, if @command{configure} generates an incorrect definition of
 207 any of the macros in @file{auto-host.h}, you can override that
 208 definition in a host configuration header.  If you need to do this,
 209 first see if it is possible to fix @command{configure}.