From 807633e5a30bbc6229c7cd46c2b69ab52eb45b6c Mon Sep 17 00:00:00 2001 From: Zack Weinberg Date: Wed, 23 Jan 2002 17:30:28 +0000 Subject: [PATCH] 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 --- gcc/ChangeLog | 9 ++ gcc/doc/fragments.texi | 73 +++++++---- gcc/doc/gccint.texi | 2 +- gcc/doc/hostconfig.texi | 259 +++++++++++----------------------------- gcc/doc/rtl.texi | 6 +- gcc/doc/tm.texi | 35 ++++-- 6 files changed, 163 insertions(+), 221 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index aa3774b5e7a..b643950bfb1 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,12 @@ +2002-01-23 Zack Weinberg + + * 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 * config/arm/arm.h (THUMB_FUNCTION_PROFILER): Define if not currently diff --git a/gcc/doc/fragments.texi b/gcc/doc/fragments.texi index e2031b3597c..f9ef3d22b82 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 e5f604094ae..82a7d317a40 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 1c7ae77e935..33c0a3bb28b 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.) +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. -If you do define this macro, you should probably do it as follows: +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. -@example -#ifndef __GNUC__ -#define USE_C_ALLOCA -#else -#define alloca __builtin_alloca -#endif -@end example +@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. -@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 @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. +@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 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. - -@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. +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. -@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 @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 a50a9db1c87..5b614090b28 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 c81461d1b5a..706cca47b4c 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