@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Host Config
@chapter Host Configuration Headers
@cindex configuration file
@cindex @file{xm-@var{machine}.h}

Host configuration headers contain macro definitions that describe the
machine and system on which the compiler is running.  They are usually
unnecessary.  Most of the things GCC needs to know about the host
system can be deduced by the @command{configure} script.

If your host does need a special configuration header, it should be
named @file{xm-@var{machine}.h}, where @var{machine} is a short mnemonic
for the machine.  Here are some macros which this header can define.

@ftable @code
@item VMS
Define this macro if the host system is VMS@.

@item FATAL_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits after serious errors.  The default is the system-provided macro
@samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
macro.  Define this macro only if these defaults are incorrect.

@item SUCCESS_EXIT_CODE
A C expression for the status code to be returned when the compiler
exits without serious errors.  (Warnings are not serious errors.)  The
default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
the system doesn't define that macro.  Define this macro only if these
defaults are incorrect.

@item USE_C_ALLOCA
Define this macro if GCC should use the C implementation of @code{alloca}
provided by @file{libiberty.a}.  This only affects how some parts of the
compiler itself allocate memory.  It does not change code generation.

When GCC is built with a compiler other than itself, the C @code{alloca}
is always used.  This is because most other implementations have serious
bugs.  You should define this macro only on a system where no
stack-based @code{alloca} can possibly work.  For instance, if a system
has a small limit on the size of the stack, GCC's builtin @code{alloca}
will not work reliably.

@item HAVE_DOS_BASED_FILE_SYSTEM
Define this macro if the host file system obeys the semantics defined by
MS-DOS instead of Unix.  DOS file systems are case insensitive, file
specifications may begin with a drive letter, and both forward slash and
backslash (@samp{/} and @samp{\}) are directory separators.  If you
define this macro, you probably need to define the next three macros too.

@item PATH_SEPARATOR
If defined, this macro should expand to a character constant specifying
the separator for elements of search paths.  The default value is a
colon (@samp{:}).  DOS-based systems usually use semicolon (@samp{;}).

@item DIR_SEPARATOR
@itemx DIR_SEPARATOR_2
If defined, these macros expand to character constants specifying
separators for directory names within a file specification.  They are
used somewhat inconsistently throughout the compiler.  If your system
behaves like Unix (only forward slash separates pathnames), define
neither of them.  If your system behaves like DOS (both forward and
backward slash can be used), define @code{DIR_SEPARATOR} to @samp{/}
and @code{DIR_SEPARATOR_2} to @samp{\}.

@item HOST_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
files on your host machine.  If you do not define this macro, GCC will
use @samp{.o} as the suffix for object files.

@item HOST_EXECUTABLE_SUFFIX
Define this macro to be a C string representing the suffix for
executable files on your host machine.  If you do not define this macro,
GCC will use the null string as the suffix for executable files.

@item HOST_BIT_BUCKET
A pathname defined by the host operating system, which can be opened as
a file and written to, but all the information written is discarded.
This is commonly known as a @dfn{bit bucket} or @dfn{null device}.  If
you do not define this macro, GCC will use @samp{/dev/null} as the bit
bucket.  If the host does not support a bit bucket, define this macro to
an invalid filename.

@item COLLECT2_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when @code{collect2} is being initialized.

@item GCC_DRIVER_HOST_INITIALIZATION
If defined, a C statement (sans semicolon) that performs host-dependent
initialization when a compilation driver is being initialized.

@item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
If defined, a C statement (sans semicolon) that performs host-dependent
canonicalization when a path used in a compilation driver or
preprocessor is canonicalized.  @var{path} is a malloc-ed path to be
canonicalized.  If the C statement does canonicalize @var{path} into a
different buffer, the old path should be freed and the new buffer should
have been allocated with malloc.

@item DUMPFILE_FORMAT
Define this macro to be a C string representing the format to use for
constructing the index part of debugging dump file names.  The resultant
string must fit in fifteen bytes.  The full filename will be the
concatenation of: the prefix of the assembler file name, the string
resulting from applying this format to an index number, and a string
unique to each dump file kind, e.g. @samp{rtl}.

If you do not define this macro, GCC will use @samp{.%02d.}.  You should
define this macro if using the default will create an invalid file name.

@item SMALL_ARG_MAX
Define this macro if the host system has a small limit on the total
size of an argument vector.  This causes the driver to take more care
not to pass unnecessary arguments to subprocesses.
@end ftable

In addition, if @command{configure} generates an incorrect definition of
any of the macros in @file{auto-host.h}, you can override that
definition in a host configuration header.  If you need to do this,
first see if it is possible to fix @command{configure}.

If you need to define only a few of these macros, and they have simple
definitions, consider using the @code{xm_defines} variable in your
@file{config.gcc} entry instead of creating a host configuration header.
@xref{System Config}.