-@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
+@c 2000, 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation, Inc.
@c This is part of the GCC manual.
-@c For copying conditions, see the file gcc.texi.
+@c For copying conditions, see the file gccint.texi.
@node Host Config
-@chapter Host Configuration Headers
+@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
+
+@deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size}, int @var{fd})
+This host hook returns the address of some space that is likely to be
+free in some subsequent invocation of the compiler. We intend to load
+the PCH data at this address such that the data need not be relocated.
+The area should be able to hold @var{size} bytes. If the host uses
+@code{mmap}, @var{fd} is an open file descriptor that can be used for
+probing.
+@end deftypefn
+
+@deftypefn {Host Hook} int HOST_HOOKS_GT_PCH_USE_ADDRESS (void * @var{address}, size_t @var{size}, int @var{fd}, size_t @var{offset})
+This host hook is called when a PCH file is about to be loaded.
+We want to load @var{size} bytes from @var{fd} at @var{offset}
+into memory at @var{address}. The given address will be the result of
+a previous invocation of @code{HOST_HOOKS_GT_PCH_GET_ADDRESS}.
+Return @minus{}1 if we couldn't allocate @var{size} bytes at @var{address}.
+Return 0 if the memory is allocated but the data is not loaded. Return 1
+if the hook has performed everything.
+
+If the implementation uses reserved address space, free any reserved
+space beyond @var{size}, regardless of the return value. 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 @minus{}1. 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
+
+@deftypefn {Host Hook} size_t HOST_HOOKS_GT_PCH_ALLOC_GRANULARITY (void);
+This host hook returns the alignment required for allocating virtual
+memory. Usually this is the same as getpagesize, but on some hosts the
+alignment for reserving memory differs from the pagesize for committing
+memory.
+@end deftypefn
+
+@node Filesystem
+@section Host Filesystem
@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.
+GCC needs to know a number of things about the semantics of the host
+machine's filesystem. Filesystems with Unix and MS-DOS semantics are
+automatically detected. For other systems, you can define the
+following macros in @file{xm-@var{machine}.h}.
@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{;}).
+This macro is automatically defined by @file{system.h} 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.
@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{\}.
+separators for directory names within a file specification.
+@file{system.h} will automatically give them appropriate values on
+Unix and MS-DOS file systems. If your file system is neither of
+these, define one or both appropriately in @file{xm-@var{machine}.h}.
+
+However, operating systems like VMS, where constructing a pathname is
+more complicated than just stringing together directory names
+separated by a special character, should not define either of these
+macros.
+
+@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, but not
+always, use semicolon (@samp{;}).
+
+@item VMS
+Define this macro if the host system is VMS@.
@item HOST_OBJECT_SUFFIX
Define this macro to be a C string representing the suffix for object
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
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}.
+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.
+@item DELETE_IF_ORDINARY
+Define this macro to be a C statement (sans semicolon) that performs
+host-dependent removal of ordinary temp files in the compilation driver.
+
+If you do not define this macro, GCC will use the default version. You
+should define this macro if the default version does not reliably remove
+the temp file as, for example, on VMS which allows multiple versions
+of a file.
+
+@item HOST_LACKS_INODE_NUMBERS
+Define this macro if the host filesystem does not report meaningful inode
+numbers in struct stat.
+@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 HOST_LONG_LONG_FORMAT
+If defined, the string used to indicate an argument of type @code{long
+long} to functions like @code{printf}. The default value is
+@code{"ll"}.
@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}.
projects / msp430-gcc.git / blobdiff