| blob | 5c38313efd21e4cf2420862f33f3d68c67d6ef0f |
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gccint.texi.
6 @node Host Config
7 @chapter Host Configuration
8 @cindex host configuration
10 Most details about the machine and system on which the compiler is
11 actually running are detected by the @command{configure} script. Some
12 things are impossible for @command{configure} to detect; these are
13 described 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
15 by the @var{out_host_hook_obj} variable in @file{config.gcc}. (The
16 intention is that very few hosts will need a header file but nearly
17 every fully supported host will need to override some hooks.)
19 If you need to define only a few macros, and they have simple
20 definitions, consider using the @code{xm_defines} variable in your
21 @file{config.gcc} entry instead of creating a host configuration
22 header. @xref{System Config}.
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
30 @node Host Common
31 @section Host Common
32 @cindex host hooks
33 @cindex host functions
35 Some things are just not portable, even between similar operating systems,
36 and are too difficult for autoconf to detect. They get implemented using
37 hook functions in the file specified by the @var{host_hook_obj}
38 variable in @file{config.gcc}.
40 @deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
41 This host hook is used to set up handling for extra signals. The most
42 common thing to do in this hook is to detect stack overflow.
43 @end deftypefn
45 @deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size})
46 This host hook returns the address of some space in which a PCH may be
47 loaded with @samp{HOST_HOOKS_PCH_LOAD_PCH}. The space will need to
48 have @var{size} bytes. If insufficient space is available,
49 @samp{NULL} may be returned; the PCH machinery will try to find a
50 suitable address using a heuristic.
52 The memory does not have to be available now. In fact, usually
53 @samp{HOST_HOOKS_PCH_LOAD_PCH} will already have been called. The memory
54 need only be available in future invocations of GCC.
55 @end deftypefn
57 @deftypefn {Host Hook} bool HOST_HOOKS_GT_PCH_USE_ADDRESS (size_t @var{size}, void * @var{address})
58 This host hook is called when a PCH file is about to be loaded. If
59 @var{address} is the address that would have been returned by
60 @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS}, and @var{size} is smaller than
61 the maximum than @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS} would have
62 accepted, return true, otherwise return false.
64 In addition, free any address space reserved that isn't needed to hold
65 @var{size} bytes (whether or not true is returned). The PCH machinery will
66 use @samp{mmap} with @samp{MAP_FIXED} to load the PCH if @samp{HAVE_MMAP_FILE},
67 or will use @samp{fread} otherwise.
69 If no PCH will be loaded, this hook may be called with @var{size}
70 zero, in which case all reserved address space should be freed.
72 Do not try to handle values of @var{address} that could not have been
73 returned by this executable; just return false. Such values usually
74 indicate an out-of-date PCH file (built by some other GCC executable),
75 and such a PCH file won't work.
76 @end deftypefn
78 @node Filesystem
79 @section Host Filesystem
80 @cindex configuration file
81 @cindex @file{xm-@var{machine}.h}
83 GCC needs to know a number of things about the semantics of the host
84 machine's filesystem. Filesystems with Unix and MS-DOS semantics are
85 automatically detected. For other systems, you can define the
86 following macros in @file{xm-@var{machine}.h}.
88 @ftable @code
89 @item HAVE_DOS_BASED_FILE_SYSTEM
90 This macro is automatically defined by @file{system.h} if the host
91 file system obeys the semantics defined by MS-DOS instead of Unix.
92 DOS file systems are case insensitive, file specifications may begin
93 with a drive letter, and both forward slash and backslash (@samp{/}
94 and @samp{\}) are directory separators.
96 @item DIR_SEPARATOR
97 @itemx DIR_SEPARATOR_2
98 If defined, these macros expand to character constants specifying
99 separators for directory names within a file specification.
100 @file{system.h} will automatically give them appropriate values on
101 Unix and MS-DOS file systems. If your file system is neither of
102 these, define one or both appropriately in @file{xm-@var{machine}.h}.
104 However, operating systems like VMS, where constructing a pathname is
105 more complicated than just stringing together directory names
106 separated by a special character, should not define either of these
107 macros.
109 @item PATH_SEPARATOR
110 If defined, this macro should expand to a character constant
111 specifying the separator for elements of search paths. The default
112 value is a colon (@samp{:}). DOS-based systems usually, but not
113 always, use semicolon (@samp{;}).
115 @item VMS
116 Define this macro if the host system is VMS@.
118 @item HOST_OBJECT_SUFFIX
119 Define this macro to be a C string representing the suffix for object
120 files on your host machine. If you do not define this macro, GCC will
121 use @samp{.o} as the suffix for object files.
123 @item HOST_EXECUTABLE_SUFFIX
124 Define this macro to be a C string representing the suffix for
125 executable files on your host machine. If you do not define this macro,
126 GCC will use the null string as the suffix for executable files.
128 @item HOST_BIT_BUCKET
129 A pathname defined by the host operating system, which can be opened as
130 a file and written to, but all the information written is discarded.
131 This is commonly known as a @dfn{bit bucket} or @dfn{null device}. If
132 you do not define this macro, GCC will use @samp{/dev/null} as the bit
133 bucket. If the host does not support a bit bucket, define this macro to
134 an invalid filename.
136 @item UPDATE_PATH_HOST_CANONICALIZE (@var{path})
137 If defined, a C statement (sans semicolon) that performs host-dependent
138 canonicalization when a path used in a compilation driver or
139 preprocessor is canonicalized. @var{path} is a malloc-ed path to be
140 canonicalized. If the C statement does canonicalize @var{path} into a
141 different buffer, the old path should be freed and the new buffer should
142 have been allocated with malloc.
144 @item DUMPFILE_FORMAT
145 Define this macro to be a C string representing the format to use for
146 constructing the index part of debugging dump file names. The resultant
147 string must fit in fifteen bytes. The full filename will be the
148 concatenation of: the prefix of the assembler file name, the string
149 resulting from applying this format to an index number, and a string
150 unique to each dump file kind, e.g. @samp{rtl}.
152 If you do not define this macro, GCC will use @samp{.%02d.}. You should
153 define this macro if using the default will create an invalid file name.
154 @end ftable
156 @node Host Misc
157 @section Host Misc
158 @cindex configuration file
159 @cindex @file{xm-@var{machine}.h}
161 @ftable @code
162 @item FATAL_EXIT_CODE
163 A C expression for the status code to be returned when the compiler
164 exits after serious errors. The default is the system-provided macro
165 @samp{EXIT_FAILURE}, or @samp{1} if the system doesn't define that
166 macro. Define this macro only if these defaults are incorrect.
168 @item SUCCESS_EXIT_CODE
169 A C expression for the status code to be returned when the compiler
170 exits without serious errors. (Warnings are not serious errors.) The
171 default is the system-provided macro @samp{EXIT_SUCCESS}, or @samp{0} if
172 the system doesn't define that macro. Define this macro only if these
173 defaults are incorrect.
175 @item USE_C_ALLOCA
176 Define this macro if GCC should use the C implementation of @code{alloca}
177 provided by @file{libiberty.a}. This only affects how some parts of the
178 compiler itself allocate memory. It does not change code generation.
180 When GCC is built with a compiler other than itself, the C @code{alloca}
181 is always used. This is because most other implementations have serious
182 bugs. You should define this macro only on a system where no
183 stack-based @code{alloca} can possibly work. For instance, if a system
184 has a small limit on the size of the stack, GCC's builtin @code{alloca}
185 will not work reliably.
187 @item COLLECT2_HOST_INITIALIZATION
188 If defined, a C statement (sans semicolon) that performs host-dependent
189 initialization when @code{collect2} is being initialized.
191 @item GCC_DRIVER_HOST_INITIALIZATION
192 If defined, a C statement (sans semicolon) that performs host-dependent
193 initialization when a compilation driver is being initialized.
195 @item SMALL_ARG_MAX
196 Define this macro if the host system has a small limit on the total
197 size of an argument vector. This causes the driver to take more care
198 not to pass unnecessary arguments to subprocesses.
199 @end ftable
201 In addition, if @command{configure} generates an incorrect definition of
202 any of the macros in @file{auto-host.h}, you can override that
203 definition in a host configuration header. If you need to do this,
204 first see if it is possible to fix @command{configure}.