@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, @c 2000, 2001, 2002, 2003 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gccint.texi. @node Host Config @chapter Host Configuration @cindex host configuration Most details about the machine and system on which the compiler is actually running are detected by the @command{configure} script. Some things are impossible for @command{configure} to detect; these are described in two ways, either by macros defined in a file named @file{xm-@var{machine}.h} or by hook functions in the file specified by the @var{out_host_hook_obj} variable in @file{config.gcc}. (The intention is that very few hosts will need a header file but nearly every fully supported host will need to override some hooks.) If you need to define only a few 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}. @menu * Host Common:: Things every host probably needs implemented. * Filesystem:: Your host can't have the letter `a' in filenames? * Host Misc:: Rare configuration options for hosts. @end menu @node Host Common @section Host Common @cindex host hooks @cindex host functions Some things are just not portable, even between similar operating systems, and are too difficult for autoconf to detect. They get implemented using hook functions in the file specified by the @var{host_hook_obj} variable in @file{config.gcc}. @deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void) This host hook is used to set up handling for extra signals. The most common thing to do in this hook is to detect stack overflow. @end deftypefn @c APPLE LOCAL begin pch @deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size}) This host hook returns the address of some space in which a PCH may be loaded with @samp{HOST_HOOKS_PCH_LOAD_PCH}. The space will need to have @var{size} bytes. If insufficient space is available, @samp{NULL} may be returned; the PCH machinery will try to find a suitable address using a heuristic. The memory does not have to be available now. In fact, usually @samp{HOST_HOOKS_PCH_LOAD_PCH} will already have been called. The memory need only be available in future invocations of GCC. @end deftypefn @deftypefn {Host Hook} bool HOST_HOOKS_GT_PCH_USE_ADDRESS (size_t @var{size}, void * @var{address}) This host hook is called when a PCH file is about to be loaded. If @var{address} is the address that would have been returned by @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS}, and @var{size} is smaller than the maximum than @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS} would have accepted, return true, otherwise return false. In addition, free any address space reserved that isn't needed to hold @var{size} bytes (whether or not true is returned). The PCH machinery will use @samp{mmap} with @samp{MAP_FIXED} to load the PCH if @samp{HAVE_MMAP_FILE}, or will use @samp{fread} otherwise. If no PCH will be loaded, this hook may be called with @var{size} zero, in which case all reserved address space should be freed. Do not try to handle values of @var{address} that could not have been returned by this executable; just return false. Such values usually indicate an out-of-date PCH file (built by some other GCC executable), and such a PCH file won't work. @end deftypefn @c APPLE LOCAL end pch @node Filesystem @section Host Filesystem @cindex configuration file @cindex @file{xm-@var{machine}.h} GCC supports some filesystems that are very different to standard Unix filesystems. These macros, defined in @file{xm-@var{machine}.h}, let you choose. @ftable @code @item VMS Define this macro if the host system is VMS@. @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 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. @end ftable @node Host Misc @section Host Misc @cindex configuration file @cindex @file{xm-@var{machine}.h} @ftable @code @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 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 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}.