[PATCH] Document exec and start file search behaviours.

[Carlos O'Donell <carlos at codesourcery dot com>]

This patch updates the documentation to reflect the reality of our exec
and start file search behaviours.

OK for mainline?

Tested by running 'make html' and 'make info' and verifying the results.

Cheers,
Carlos.
-- 
Carlos O'Donell
CodeSourcery
carlos@codesourcery.com
(650) 331-3385 x716

2006-12-20  Carlos O'Donell  <carlos@codesourcery.com>

	* doc/tm.texi: Update documentation to reflect reality of exec
	and start file search behavours. 
	* doc/invoke.texi: Explain how GCC_EXEC_PREFIX is used to find
	header file directories.

Index: gcc/doc/tm.texi
===================================================================
--- gcc/doc/tm.texi	(revision 120099)
+++ gcc/doc/tm.texi	(working copy)
@@ -615,19 +615,25 @@ Here is the order of prefixes tried for 
 Any prefixes specified by the user with @option{-B}.
 
 @item
-The environment variable @code{GCC_EXEC_PREFIX}, if any.
+The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
+value based on the installed toolchain location.
 
 @item
 The directories specified by the environment variable @code{COMPILER_PATH}.
 
 @item
-The macro @code{STANDARD_EXEC_PREFIX}.
+The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
+in the configured @var{prefix} or this is a native compiler. 
 
 @item
-@file{/usr/lib/gcc/}.
+The location @file{/usr/lib/gcc/}, but only if this is a native compiler. 
 
 @item
-The macro @code{MD_EXEC_PREFIX}, if any.
+The location @file{/usr/libexec/gcc/}, but only if this is a native compiler. 
+
+@item
+The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
+compiler.
 @end enumerate
 
 Here is the order of prefixes tried for startfiles:
@@ -637,31 +643,45 @@ Here is the order of prefixes tried for 
 Any prefixes specified by the user with @option{-B}.
 
 @item
-The environment variable @code{GCC_EXEC_PREFIX}, if any.
+The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
+value based on the installed toolchain location.
 
 @item
 The directories specified by the environment variable @code{LIBRARY_PATH}
 (or port-specific name; native only, cross compilers do not use this).
 
 @item
-The macro @code{STANDARD_EXEC_PREFIX}.
+The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
+in the configured @var{prefix} or this is a native compiler. 
+
+@item
+The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
 
 @item
-@file{/usr/lib/gcc/}.
+The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
+compiler.
 
 @item
-The macro @code{MD_EXEC_PREFIX}, if any.
+The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a 
+native compiler, or we have a target system root.
 
 @item
-The macro @code{MD_STARTFILE_PREFIX}, if any.
+The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a 
+native compiler, or we have a target system root.
 
 @item
-The macro @code{STANDARD_STARTFILE_PREFIX}.
+The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications.
+If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and
+the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix.
 
 @item
+The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native
+compiler, or we have a target system root. The default for this macro is
 @file{/lib/}.
 
 @item
+The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native
+compiler, or we have a target system root. The default for this macro is
 @file{/usr/lib/}.
 @end enumerate
 
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 120099)
+++ gcc/doc/invoke.texi	(working copy)
@@ -13903,7 +13903,8 @@ If GCC cannot find the subprogram using 
 tries looking in the usual places for the subprogram.
 
 The default value of @env{GCC_EXEC_PREFIX} is
-@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value
+@file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
+the installed compiler. In many cases @var{prefix} is the value
 of @code{prefix} when you ran the @file{configure} script.
 
 Other prefixes specified with @option{-B} take precedence over this prefix.
@@ -13919,7 +13920,9 @@ replacing that beginning with the specif
 alternate directory name.  Thus, with @option{-Bfoo/}, GCC will search
 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
 These alternate directories are searched first; the standard directories
-come next.
+come next. If a standard directory begins with the configured 
+@var{prefix} then the value of @var{prefix} is replaced by 
+@env{GCC_EXEC_PREFIX} when looking for header files.
 
 @item COMPILER_PATH
 @findex COMPILER_PATH