gcc/doc/hostconfig.texi

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