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