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