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