gcc/doc/hostconfig.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Host Config
   7 @chapter Host Configuration Headers
   8 @cindex configuration file
   9 @cindex @file{xm-@var{machine}.h}
  10
  11 Host configuration headers contain macro definitions that describe the
  12 machine and system on which the compiler is running.  They are usually
  13 unnecessary.  Most of the things GCC needs to know about the host
  14 system can be deduced by the @command{configure} script.
  15
  16 If your host does need a special configuration header, it should be
  17 named @file{xm-@var{machine}.h}, where @var{machine} is a short mnemonic
  18 for the machine.  Here are some macros which this header can define.
  19
  20 @ftable @code
  21 @item VMS
  22 Define this macro if the host system is VMS@.
  23
  24 @item FATAL_EXIT_CODE
  25 A C expression for the status code to be returned when the compiler
  26 exits after serious errors.  The default is the system-provided macro
  27 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
  28 macro.  Define this macro only if these defaults are incorrect.
  29
  30 @item SUCCESS_EXIT_CODE
  31 A C expression for the status code to be returned when the compiler
  32 exits without serious errors.  (Warnings are not serious errors.)  The
  33 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
  34 the system doesn't define that macro.  Define this macro only if these
  35 defaults are incorrect.
  36
  37 @item USE_C_ALLOCA
  38 Define this macro if GCC should use the C implementation of @code{alloca}
  39 provided by @file{libiberty.a}.  This only affects how some parts of the
  40 compiler itself allocate memory.  It does not change code generation.
  41
  42 When GCC is built with a compiler other than itself, the C @code{alloca}
  43 is always used.  This is because most other implementations have serious
  44 bugs.  You should define this macro only on a system where no
  45 stack-based @code{alloca} can possibly work.  For instance, if a system
  46 has a small limit on the size of the stack, GCC's builtin @code{alloca}
  47 will not work reliably.
  48
  49 @item HAVE_DOS_BASED_FILE_SYSTEM
  50 Define this macro if the host file system obeys the semantics defined by
  51 MS-DOS instead of Unix.  DOS file systems are case insensitive, file
  52 specifications may begin with a drive letter, and both forward slash and
  53 backslash (@samp{/} and @samp{\}) are directory separators.  If you
  54 define this macro, you probably need to define the next three macros too.
  55
  56 @item PATH_SEPARATOR
  57 If defined, this macro should expand to a character constant specifying
  58 the separator for elements of search paths.  The default value is a
  59 colon (@samp{:}).  DOS-based systems usually use semicolon (@samp{;}).
  60
  61 @item DIR_SEPARATOR
  62 @itemx DIR_SEPARATOR_2
  63 If defined, these macros expand to character constants specifying
  64 separators for directory names within a file specification.  They are
  65 used somewhat inconsistently throughout the compiler.  If your system
  66 behaves like Unix (only forward slash separates pathnames), define
  67 neither of them.  If your system behaves like DOS (both forward and
  68 backward slash can be used), define @code{DIR_SEPARATOR} to @samp{/}
  69 and @code{DIR_SEPARATOR_2} to @samp{\}.
  70
  71 @item HOST_OBJECT_SUFFIX
  72 Define this macro to be a C string representing the suffix for object
  73 files on your host machine.  If you do not define this macro, GCC will
  74 use @samp{.o} as the suffix for object files.
  75
  76 @item HOST_EXECUTABLE_SUFFIX
  77 Define this macro to be a C string representing the suffix for
  78 executable files on your host machine.  If you do not define this macro,
  79 GCC will use the null string as the suffix for executable files.
  80
  81 @item HOST_BIT_BUCKET
  82 A pathname defined by the host operating system, which can be opened as
  83 a file and written to, but all the information written is discarded.
  84 This is commonly known as a @dfn{bit bucket} or @dfn{null device}.  If
  85 you do not define this macro, GCC will use @samp{/dev/null} as the bit
  86 bucket.  If the host does not support a bit bucket, define this macro to
  87 an invalid filename.
  88
  89 @item COLLECT2_HOST_INITIALIZATION
  90 If defined, a C statement (sans semicolon) that performs host-dependent
  91 initialization when @code{collect2} is being initialized.
  92
  93 @item GCC_DRIVER_HOST_INITIALIZATION
  94 If defined, a C statement (sans semicolon) that performs host-dependent
  95 initialization when a compilation driver is being initialized.
  96
  97 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
  98 If defined, a C statement (sans semicolon) that performs host-dependent
  99 canonicalization when a path used in a compilation driver or
 100 preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
 101 canonicalized.  If the C statement does canonicalize @var{path} into a
 102 different buffer, the old path should be freed and the new buffer should
 103 have been allocated with malloc.
 104
 105 @item DUMPFILE_FORMAT
 106 Define this macro to be a C string representing the format to use for
 107 constructing the index part of debugging dump file names.  The resultant
 108 string must fit in fifteen bytes.  The full filename will be the
 109 concatenation of: the prefix of the assembler file name, the string
 110 resulting from applying this format to an index number, and a string
 111 unique to each dump file kind, e.g. @samp{rtl}.
 112
 113 If you do not define this macro, GCC will use @samp{.%02d.}.  You should
 114 define this macro if using the default will create an invalid file name.
 115
 116 @item SMALL_ARG_MAX
 117 Define this macro if the host system has a small limit on the total
 118 size of an argument vector.  This causes the driver to take more care
 119 not to pass unnecessary arguments to subprocesses.
 120 @end ftable
 121
 122 In addition, if @command{configure} generates an incorrect definition of
 123 any of the macros in @file{auto-host.h}, you can override that
 124 definition in a host configuration header.  If you need to do this,
 125 first see if it is possible to fix @command{configure}.
 126
 127 If you need to define only a few of these macros, and they have simple
 128 definitions, consider using the @code{xm_defines} variable in your
 129 @file{config.gcc} entry instead of creating a host configuration header.
 130 @xref{System Config}.