fragments.texi, [...]: Update to reflect current (lack of) need for host configuration by hand.

	* doc/fragments.texi, doc/hostconfig.texi: Update to reflect
	current (lack of) need for host configuration by hand.

	* doc/gccint.texi, doc/rtl.texi, doc/tm.texi: Adjust cross
	references.  Documentation of some target macros moved from
	hostconfig.texi to tm.texi.

From-SVN: r49142

6 files changed, 168 insertions, 226 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index aa3774b..b643950 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,12 @@
+2002-01-23  Zack Weinberg  <zack@codesourcery.com>
+
+	* doc/fragments.texi, doc/hostconfig.texi: Update to reflect
+	current (lack of) need for host configuration by hand.
+
+	* doc/gccint.texi, doc/rtl.texi, doc/tm.texi: Adjust cross
+	references.  Documentation of some target macros moved from
+	hostconfig.texi to tm.texi.
+
 2002-01-23  Will Cohen  <wcohen@redhat.com>
 
 	* config/arm/arm.h (THUMB_FUNCTION_PROFILER): Define if not currently
diff --git a/gcc/doc/fragments.texi b/gcc/doc/fragments.texi
index e2031b3..f9ef3d2 100644
--- a/gcc/doc/fragments.texi
+++ b/gcc/doc/fragments.texi
@@ -7,26 +7,36 @@
 @chapter Makefile Fragments
 @cindex makefile fragment
 
-When you configure GCC using the @file{configure} script,
-it will construct the file @file{Makefile} from
-the template file @file{Makefile.in}.  When it does this, it will
-incorporate makefile fragment files from the @file{config} directory,
-named @file{t-@var{target}} and @file{x-@var{host}}.  If these files do
-not exist, it means nothing needs to be added for a given target or
-host.
+When you configure GCC using the @file{configure} script, it will
+construct the file @file{Makefile} from the template file
+@file{Makefile.in}.  When it does this, it can incorporate makefile
+fragments from the @file{config} directory.  These are used to set
+Makefile parameters that are not amenable to being calculated by
+autoconf.  The list of fragments to incorporate is set by
+@file{config.gcc}; @xref{System Config}.
+
+Fragments are named either @file{t-@var{target}} or @file{x-@var{host}},
+depending on whether they are relevant to configuring GCC to produce
+code for a particular target, or to configuring GCC to run on a
+particular host.  Here @var{target} and @var{host} are mnemonics
+which usually have some relationship to the canonical system name, but
+no formal connection.
+
+If these files do not exist, it means nothing needs to be added for a
+given target or host.  Most targets need a few @file{t-@var{target}}
+fragments, but needing @file{x-@var{host}} fragments is rare.
 
 @menu
-* Target Fragment:: Writing the @file{t-@var{target}} file.
-* Host Fragment::   Writing the @file{x-@var{host}} file.
+* Target Fragment:: Writing @file{t-@var{target}} files.
+* Host Fragment::   Writing @file{x-@var{host}} files.
 @end menu
 
 @node Target Fragment
-@section The Target Makefile Fragment
+@section Target Makefile Fragments
 @cindex target makefile fragment
 @cindex @file{t-@var{target}}
 
-The target makefile fragment, @file{t-@var{target}}, defines special
-target dependent variables and targets used in the @file{Makefile}:
+Target makefile fragments can set these Makefile variables.
 
 @table @code
 @findex LIBGCC2_CFLAGS
@@ -141,19 +151,40 @@ of options to be used for all builds.
 @end table
 
 @node Host Fragment
-@section The Host Makefile Fragment
+@section Host Makefile Fragments
 @cindex host makefile fragment
 @cindex @file{x-@var{host}}
 
-The host makefile fragment, @file{x-@var{host}}, defines special host
-dependent variables and targets used in the @file{Makefile}:
+The use of @file{x-@var{host}} fragments is discouraged.  You should do
+so only if there is no other mechanism to get the behavior desired.
+Host fragments should never forcibly override variables set by the
+configure script, as they may have been adjusted by the user.
+
+Variables provided for host fragments to set include:
 
 @table @code
-@findex CC
-@item CC
-The compiler to use when building the first stage.
 
-@findex INSTALL
-@item INSTALL
-The install program to use.
+@item X_CFLAGS
+@itemx X_CPPFLAGS
+These are extra flags to pass to the C compiler and preprocessor,
+respectively.  They are used both when building GCC, and when compiling
+things with the just-built GCC.
+
+@item XCFLAGS
+These are extra flags to use when building the compiler.  They are not
+used when compiling @file{libgcc.a}.  However, they @emph{are} used when
+recompiling the compiler with itself in later stages of a bootstrap.
+
+@item BOOT_LDFLAGS
+Flags to be passed to the linker when recompiling the compiler with
+itself in later stages of a bootstrap.  You might need to use this if,
+for instance, one of the front ends needs more text space than the
+linker provides by default.
+
+@item EXTRA_PROGRAMS
+A list of additional programs required to use the compiler on this host,
+which should be compiled with GCC and installed alongside the front
+ends.  If you set this variable, you must also provide rules to build
+the extra programs.
+
 @end table
diff --git a/gcc/doc/gccint.texi b/gcc/doc/gccint.texi
index e5f6040..82a7d31 100644
--- a/gcc/doc/gccint.texi
+++ b/gcc/doc/gccint.texi
@@ -165,7 +165,7 @@ Additional tutorial information is linked to from
 * RTL::             The intermediate representation that most passes work on.
 * Machine Desc::    How to write machine description instruction patterns.
 * Target Macros::   How to write the machine description C macros and functions.
-* Config::          Writing the @file{xm-@var{machine}.h} file.
+* Host Config::     Writing the @file{xm-@var{machine}.h} file.
 * Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
 * Collect2::        How @code{collect2} works; how it finds @code{ld}.
 * Header Dirs::     Understanding the standard header file directories.
diff --git a/gcc/doc/hostconfig.texi b/gcc/doc/hostconfig.texi
index 1c7ae77..33c0a3b 100644
--- a/gcc/doc/hostconfig.texi
+++ b/gcc/doc/hostconfig.texi
@@ -1,38 +1,32 @@
 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
-@node Config
-@chapter The Configuration File
+@node Host Config
+@chapter Host Configuration Headers
 @cindex configuration file
 @cindex @file{xm-@var{machine}.h}
 
-The configuration file @file{xm-@var{machine}.h} contains macro
-definitions that describe the machine and system on which the compiler
-is running, unlike the definitions in @file{@var{machine}.h}, which
-describe the machine for which the compiler is producing output.  Most
-of the values in @file{xm-@var{machine}.h} are actually the same on all
-machines that GCC runs on, so large parts of all configuration files
-are identical.  But there are some macros that vary:
+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.
 
-@table @code
-@findex USG
-@item USG
-Define this macro if the host system is System V@.
+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.
 
-@findex VMS
+@ftable @code
 @item VMS
 Define this macro if the host system is VMS@.
 
-@findex FATAL_EXIT_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.
 
-@findex SUCCESS_EXIT_CODE
 @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
@@ -40,189 +34,66 @@ 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.
 
-@findex HOST_WORDS_BIG_ENDIAN
-@item HOST_WORDS_BIG_ENDIAN
-Defined if the host machine stores words of multi-word values in
-big-endian order.  (GCC does not depend on the host byte ordering
-within a word.)
-
-@findex HOST_FLOAT_WORDS_BIG_ENDIAN
-@item HOST_FLOAT_WORDS_BIG_ENDIAN
-Define this macro to be 1 if the host machine stores @code{DFmode},
-@code{XFmode} or @code{TFmode} floating point numbers in memory with the
-word containing the sign bit at the lowest address; otherwise, define it
-to be zero.
-
-This macro need not be defined if the ordering is the same as for
-multi-word integers.
-
-@findex HOST_FLOAT_FORMAT
-@item HOST_FLOAT_FORMAT
-A numeric code distinguishing the floating point format for the host
-machine.  See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
-alternatives and default.
-
-@findex HOST_BITS_PER_CHAR
-@item HOST_BITS_PER_CHAR
-A C expression for the number of bits in @code{char} on the host
-machine.
-
-@findex HOST_BITS_PER_SHORT
-@item HOST_BITS_PER_SHORT
-A C expression for the number of bits in @code{short} on the host
-machine.
-
-@findex HOST_BITS_PER_INT
-@item HOST_BITS_PER_INT
-A C expression for the number of bits in @code{int} on the host
-machine.
-
-@findex HOST_BITS_PER_LONG
-@item HOST_BITS_PER_LONG
-A C expression for the number of bits in @code{long} on the host
-machine.
-
-@findex HOST_BITS_PER_LONGLONG
-@item HOST_BITS_PER_LONGLONG
-A C expression for the number of bits in @code{long long} on the host
-machine.
-
-@findex ONLY_INT_FIELDS
-@item ONLY_INT_FIELDS
-Define this macro to indicate that the host compiler only supports
-@code{int} bit-fields, rather than other integral types, including
-@code{enum}, as do most C compilers.
-
-@findex OBSTACK_CHUNK_SIZE
-@item OBSTACK_CHUNK_SIZE
-A C expression for the size of ordinary obstack chunks.
-If you don't define this, a usually-reasonable default is used.
-
-@findex OBSTACK_CHUNK_ALLOC
-@item OBSTACK_CHUNK_ALLOC
-The function used to allocate obstack chunks.
-If you don't define this, @code{xmalloc} is used.
-
-@findex OBSTACK_CHUNK_FREE
-@item OBSTACK_CHUNK_FREE
-The function used to free obstack chunks.
-If you don't define this, @code{free} is used.
-
-@findex USE_C_ALLOCA
 @item USE_C_ALLOCA
-Define this macro to indicate that the compiler is running with the
-@code{alloca} implemented in C@.  This version of @code{alloca} can be
-found in the file @file{alloca.c}; to use it, you must also alter the
-@file{Makefile} variable @code{ALLOCA}.  (This is done automatically
-for the systems on which we know it is needed.)
-
-If you do define this macro, you should probably do it as follows:
-
-@example
-#ifndef __GNUC__
-#define USE_C_ALLOCA
-#else
-#define alloca __builtin_alloca
-#endif
-@end example
-
-@noindent
-so that when the compiler is compiled with GCC it uses the more
-efficient built-in @code{alloca} function.
-
-@item FUNCTION_CONVERSION_BUG
-@findex FUNCTION_CONVERSION_BUG
-Define this macro to indicate that the host compiler does not properly
-handle converting a function value to a pointer-to-function when it is
-used in an expression.
-
-@findex MULTIBYTE_CHARS
-@item MULTIBYTE_CHARS
-Define this macro to enable support for multibyte characters in the
-input to GCC@.  This requires that the host system support the ISO C
-library functions for converting multibyte characters to wide
-characters.
-
-@findex POSIX
-@item POSIX
-Define this if your system is POSIX.1 compliant.
-
-@findex PATH_SEPARATOR
+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
-Define this macro to be a C character constant representing the
-character used to separate components in paths.  The default value is
-the colon character
+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{;}).
 
-@findex DIR_SEPARATOR
 @item DIR_SEPARATOR
-If your system uses some character other than slash to separate
-directory names within a file specification, define this macro to be a C
-character constant specifying that character.  When GCC displays file
-names, the character you specify will be used.  GCC will test for
-both slash and the character you specify when parsing filenames.
-
-@findex DIR_SEPARATOR_2
-@item DIR_SEPARATOR_2
-If your system uses an alternative character other than
-@samp{DIR_SEPARATOR} to separate directory names within a file
-specification, define this macro to be a C character constant specifying
-that character.  If you define this macro, GCC will test for slash,
-@samp{DIR_SEPARATOR}, and @samp{DIR_SEPARATOR_2} when parsing filenames.
-
-@findex TARGET_OBJECT_SUFFIX
-@item TARGET_OBJECT_SUFFIX
-Define this macro to be a C string representing the suffix for object
-files on your target machine.  If you do not define this macro, GCC will
-use @samp{.o} as the suffix for object files.
+@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{\}.
 
-@findex TARGET_EXECUTABLE_SUFFIX
-@item TARGET_EXECUTABLE_SUFFIX
-Define this macro to be a C string representing the suffix to be
-automatically added to executable files on your target machine.  If you
-do not define this macro, GCC will use the null string as the suffix for
-executable files.
-
-@findex HOST_OBJECT_SUFFIX
 @item HOST_OBJECT_SUFFIX
 Define this macro to be a C string representing the suffix for object
-files on your host machine (@samp{xm-*.h}).  If you do not define this
-macro, GCC will use @samp{.o} as the suffix for object files.
+files on your host machine.  If you do not define this macro, GCC will
+use @samp{.o} as the suffix for object files.
 
-@findex HOST_EXECUTABLE_SUFFIX
 @item HOST_EXECUTABLE_SUFFIX
 Define this macro to be a C string representing the suffix for
-executable files on your host machine (@samp{xm-*.h}).  If you do not
-define this macro, GCC will use the null string as the suffix for
-executable files.
+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.
 
-@findex HOST_BIT_BUCKET
 @item HOST_BIT_BUCKET
-The name of a file or file-like object on the host system which acts as
-a ``bit bucket''.  If you do not define this macro, GCC will use
-@samp{/dev/null} as the bit bucket.  If the target does not support a
-bit bucket, this should be defined to the null string, or some other
-invalid filename.  If the bit bucket is not writable, GCC will use a
-temporary file instead.
-
-@findex COLLECT_EXPORT_LIST
-@item COLLECT_EXPORT_LIST
-If defined, @code{collect2} will scan the individual object files
-specified on its command line and create an export list for the linker.
-Define this macro for systems like AIX, where the linker discards
-object files that are not referenced from @code{main} and uses export
-lists.
-
-@findex COLLECT2_HOST_INITIALIZATION
+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 COLLECT2_HOST_INITIALIZATION
 If defined, a C statement (sans semicolon) that performs host-dependent
 initialization when @code{collect2} is being initialized.
 
-@findex GCC_DRIVER_HOST_INITIALIZATION
 @item GCC_DRIVER_HOST_INITIALIZATION
 If defined, a C statement (sans semicolon) that performs host-dependent
 initialization when a compilation driver is being initialized.
 
-@findex UPDATE_PATH_HOST_CANONICALIZE
 @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
@@ -231,19 +102,29 @@ 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.
 
-@findex DUMPFILE_FORMAT
 @item DUMPFILE_FORMAT
-Define this macro to be a C string representing the format to use
-for constructing the index part of the dump file name on your host machine.
-If you do not define this macro, GCC will use @samp{.%02d.}.  The full
-filename will be the prefix of the assembler file name concatenated with
-the string resulting from applying this format concatenated with a string
+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}.
-@end table
-
-@findex bzero
-@findex bcmp
-In addition, configuration files for system V define @code{bcopy},
-@code{bzero} and @code{bcmp} as aliases.  Some files define @code{alloca}
-as a macro when compiled with GCC, in order to take advantage of the
-benefit of GCC's built-in @code{alloca}.
+
+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.
+@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}.
diff --git a/gcc/doc/rtl.texi b/gcc/doc/rtl.texi
index a50a9db..5b61409 100644
--- a/gcc/doc/rtl.texi
+++ b/gcc/doc/rtl.texi
@@ -57,9 +57,9 @@ expression (``RTX'', for short) is a C structure, but it is usually
 referred to with a pointer; a type that is given the typedef name
 @code{rtx}.
 
-An integer is simply an @code{int}; their written form uses decimal digits.
-A wide integer is an integral object whose type is @code{HOST_WIDE_INT}
-(@pxref{Config}); their written form uses decimal digits.
+An integer is simply an @code{int}; their written form uses decimal
+digits.  A wide integer is an integral object whose type is
+@code{HOST_WIDE_INT}; their written form uses decimal digits.
 
 A string is a sequence of characters.  In core it is represented as a
 @code{char *} in usual C fashion, and it is written in C syntax as well.
diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi
index c81461d..706cca4 100644
--- a/gcc/doc/tm.texi
+++ b/gcc/doc/tm.texi
@@ -1313,7 +1313,7 @@ need to define this macro when the format is IEEE@.
 
 @findex VAX_FLOAT_FORMAT
 @item VAX_FLOAT_FORMAT
-This code indicates the peculiar format used on the VAX.
+This code indicates the ``D float'' format used on the VAX@.
 
 @findex IBM_FLOAT_FORMAT
 @item IBM_FLOAT_FORMAT
@@ -1328,14 +1328,14 @@ This code indicates the format used on the TMS320C3x/C4x.
 This code indicates any other format.
 @end table
 
-The value of this macro is compared with @code{HOST_FLOAT_FORMAT}
-(@pxref{Config}) to determine whether the target machine has the same
-format as the host machine.  If any other formats are actually in use on
-supported machines, new codes should be defined for them.
+The value of this macro is compared with @code{HOST_FLOAT_FORMAT}, which
+is defined by the @command{configure} script, to determine whether the
+target machine has the same format as the host machine.  If any other
+formats are actually in use on supported machines, new codes should be
+defined for them.
 
 The ordering of the component words of floating point values stored in
-memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN} for the target
-machine and @code{HOST_FLOAT_WORDS_BIG_ENDIAN} for the host.
+memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN}.
 
 @end table
 
@@ -8600,4 +8600,25 @@ You may use @code{current_function_leaf_function} in the definition of the
 macro, functions that use @code{REG_N_SETS}, to determine if the hard
 register in question will not be clobbered.
 
+@findex TARGET_OBJECT_SUFFIX
+@item TARGET_OBJECT_SUFFIX
+Define this macro to be a C string representing the suffix for object
+files on your target machine.  If you do not define this macro, GCC will
+use @samp{.o} as the suffix for object files.
+
+@findex TARGET_EXECUTABLE_SUFFIX
+@item TARGET_EXECUTABLE_SUFFIX
+Define this macro to be a C string representing the suffix to be
+automatically added to executable files on your target machine.  If you
+do not define this macro, GCC will use the null string as the suffix for
+executable files.
+
+@findex COLLECT_EXPORT_LIST
+@item COLLECT_EXPORT_LIST
+If defined, @code{collect2} will scan the individual object files
+specified on its command line and create an export list for the linker.
+Define this macro for systems like AIX, where the linker discards
+object files that are not referenced from @code{main} and uses export
+lists.
+
 @end table