gcc/doc/hostconfig.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
   2 @c 2000, 2001, 2002, 2003 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 @node Filesystem
  46 @section Host Filesystem
  47 @cindex configuration file
  48 @cindex @file{xm-@var{machine}.h}
  49
  50 GCC supports some filesystems that are very different to standard Unix
  51 filesystems.  These macros, defined in @file{xm-@var{machine}.h},
  52 let you choose.
  53
  54 @ftable @code
  55 @item VMS
  56 Define this macro if the host system is VMS@.
  57
  58 @item HAVE_DOS_BASED_FILE_SYSTEM
  59 Define this macro if the host file system obeys the semantics defined by
  60 MS-DOS instead of Unix.  DOS file systems are case insensitive, file
  61 specifications may begin with a drive letter, and both forward slash and
  62 backslash (@samp{/} and @samp{\}) are directory separators.  If you
  63 define this macro, you probably need to define the next three macros too.
  64
  65 @item PATH_SEPARATOR
  66 If defined, this macro should expand to a character constant specifying
  67 the separator for elements of search paths.  The default value is a
  68 colon (@samp{:}).  DOS-based systems usually use semicolon (@samp{;}).
  69
  70 @item DIR_SEPARATOR
  71 @itemx DIR_SEPARATOR_2
  72 If defined, these macros expand to character constants specifying
  73 separators for directory names within a file specification.  They are
  74 used somewhat inconsistently throughout the compiler.  If your system
  75 behaves like Unix (only forward slash separates pathnames), define
  76 neither of them.  If your system behaves like DOS (both forward and
  77 backward slash can be used), define @code{DIR_SEPARATOR} to @samp{/}
  78 and @code{DIR_SEPARATOR_2} to @samp{\}.
  79
  80 @item HOST_OBJECT_SUFFIX
  81 Define this macro to be a C string representing the suffix for object
  82 files on your host machine.  If you do not define this macro, GCC will
  83 use @samp{.o} as the suffix for object files.
  84
  85 @item HOST_EXECUTABLE_SUFFIX
  86 Define this macro to be a C string representing the suffix for
  87 executable files on your host machine.  If you do not define this macro,
  88 GCC will use the null string as the suffix for executable files.
  89
  90 @item HOST_BIT_BUCKET
  91 A pathname defined by the host operating system, which can be opened as
  92 a file and written to, but all the information written is discarded.
  93 This is commonly known as a @dfn{bit bucket} or @dfn{null device}.  If
  94 you do not define this macro, GCC will use @samp{/dev/null} as the bit
  95 bucket.  If the host does not support a bit bucket, define this macro to
  96 an invalid filename.
  97
  98 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
  99 If defined, a C statement (sans semicolon) that performs host-dependent
 100 canonicalization when a path used in a compilation driver or
 101 preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
 102 canonicalized.  If the C statement does canonicalize @var{path} into a
 103 different buffer, the old path should be freed and the new buffer should
 104 have been allocated with malloc.
 105
 106 @item DUMPFILE_FORMAT
 107 Define this macro to be a C string representing the format to use for
 108 constructing the index part of debugging dump file names.  The resultant
 109 string must fit in fifteen bytes.  The full filename will be the
 110 concatenation of: the prefix of the assembler file name, the string
 111 resulting from applying this format to an index number, and a string
 112 unique to each dump file kind, e.g. @samp{rtl}.
 113
 114 If you do not define this macro, GCC will use @samp{.%02d.}.  You should
 115 define this macro if using the default will create an invalid file name.
 116 @end ftable
 117
 118 @node Host Misc
 119 @section Host Misc
 120 @cindex configuration file
 121 @cindex @file{xm-@var{machine}.h}
 122
 123 @ftable @code
 124 @item FATAL_EXIT_CODE
 125 A C expression for the status code to be returned when the compiler
 126 exits after serious errors.  The default is the system-provided macro
 127 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
 128 macro.  Define this macro only if these defaults are incorrect.
 129
 130 @item SUCCESS_EXIT_CODE
 131 A C expression for the status code to be returned when the compiler
 132 exits without serious errors.  (Warnings are not serious errors.)  The
 133 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
 134 the system doesn't define that macro.  Define this macro only if these
 135 defaults are incorrect.
 136
 137 @item USE_C_ALLOCA
 138 Define this macro if GCC should use the C implementation of @code{alloca}
 139 provided by @file{libiberty.a}.  This only affects how some parts of the
 140 compiler itself allocate memory.  It does not change code generation.
 141
 142 When GCC is built with a compiler other than itself, the C @code{alloca}
 143 is always used.  This is because most other implementations have serious
 144 bugs.  You should define this macro only on a system where no
 145 stack-based @code{alloca} can possibly work.  For instance, if a system
 146 has a small limit on the size of the stack, GCC's builtin @code{alloca}
 147 will not work reliably.
 148
 149 @item COLLECT2_HOST_INITIALIZATION
 150 If defined, a C statement (sans semicolon) that performs host-dependent
 151 initialization when @code{collect2} is being initialized.
 152
 153 @item GCC_DRIVER_HOST_INITIALIZATION
 154 If defined, a C statement (sans semicolon) that performs host-dependent
 155 initialization when a compilation driver is being initialized.
 156
 157 @item SMALL_ARG_MAX
 158 Define this macro if the host system has a small limit on the total
 159 size of an argument vector.  This causes the driver to take more care
 160 not to pass unnecessary arguments to subprocesses.
 161 @end ftable
 162
 163 In addition, if @command{configure} generates an incorrect definition of
 164 any of the macros in @file{auto-host.h}, you can override that
 165 definition in a host configuration header.  If you need to do this,
 166 first see if it is possible to fix @command{configure}.