Cross-GCC/sys-include bug

[Kai Ruottu <kai dot ruottu at luukku dot com>]

Hi,

there is a serious bug in the current GCC config files, when handling
the target headers in a cross-compiler. While the RMS's "Using and
Porting the GNU Compiler Collection (GCC)" clearly says :

-------------------- clip ---------------------------------------------
   When you have found suitable header files, put them in the directory
`/usr/local/TARGET/include', before building the cross compiler.  Then
installation will run fixincludes properly and install the corrected
versions of the header files where the compiler will use them.
-------------------- clip ---------------------------------------------

The default $prefix is used here, but anyhow the preinstallation into
'$prefix/$target/include' should be very clear... Also the definition
of GCC_INCLUDE_DIR repeats the same facts:

-------------------- clip ---------------------------------------------
Standard Header File Directories
================================

`GCC_INCLUDE_DIR' means the same thing for native and cross.  It is
where GNU CC stores its private include files, and also where GNU CC
stores the fixed include files.  A cross compiled GNU CC runs
`fixincludes' on the header files in `$(tooldir)/include'.  (If the
cross compilation header files need to be fixed, they must be installed
before GNU CC is built.  If the cross compilation header files are
already suitable for ANSI C and GNU CC, nothing special need be done).
-------------------- clip ---------------------------------------------

 But the current config files require that the target headers must be
seen in '$prefix/$target/sys-include', the equivalent to SYS_INCLUDE_DIR
in a native compiler. This is seldom used and also the definition for
the CROSS_INCLUDE_DIR ($prefix/$target/sys-include) says:

-------------------- clip ---------------------------------------------
CROSS_INCLUDE_DIR is used only for a cross compiler.  GNU CC
doesn't install anything there.
-------------------- clip ---------------------------------------------

while for the TOOL_INCLUDE_DIR ($prefix/$target/include) has been said:

-------------------- clip ---------------------------------------------
TOOL_INCLUDE_DIR is used for both native and cross compilers.  It
is the place for other packages to install header files that GNU CC will
use.  For a cross-compiler, this is the equivalent of `/usr/include'.
When you build a cross-compiler, `fixincludes' processes any header
files in this directory.
-------------------- clip ---------------------------------------------

 Not very clearly said about the "alternative place for the 3rd party
headers for a native compiler" (besides the LOCAL_INCLUDE_DIR)... But
if someone misunderstands the words for a cross-compiler, it is a big
surprise...

 The buggy 'Makefile.in' and 'cross-make' use the name 'SYSTEM_HEADER_DIR'
about the native '/usr/include', which can cause misunderstandings... The
right name for it could be the 'STANDARD_HEADER_DIR', if following the
analogy with the GCC manual names and there is a reason to use the word
HEADER instead of INCLUDE :

-------------------- clip ---------------------------------------------
SYSTEM_INCLUDE_DIR
Define this macro as a C string constant if you wish to specify a
system-specific directory to search for header files before the standard
directory.  SYSTEM_INCLUDE_DIR comes before STANDARD_INCLUDE_DIR in the
search order.

Cross compilers do not use this macro and do not search the directory
specified.

STANDARD_INCLUDE_DIR
Define this macro as a C string constant if you wish to override the
standard choice of /usr/include as the default prefix to try when
searching for header files.

Cross compilers do not use this macro and do not search either
/usr/include or its replacement.
-------------------- clip ---------------------------------------------

 The search order with the GCC_INCLUDE_DIR, CROSS_INCLUDE_DIR and
TOOL_INCLUDE_DIR in a cross-compiler follows the search order with
the GCC_INCLUDE_DIR, SYSTEM_INCLUDE_DIR and STANDARD_INCLUDE_DIR
in a native compiler, so claiming the CROSS_INCLUDE_DIR and the
SYSTEM_INCLUDE_DIR being equivalents has a strong reason...

 Configure hacks like the '--with-headers=' (those who don't know
how to use the 'cp' command to copy the headers, e.g. from the
'newlib-1.9.0/newlib/libc/include' into '$prefix/$target/include'
prefer using this hack) also copy the pointed headers into the
'$prefix/$target/sys-include' not to the right place, while
building and installing newlib or glibc puts the target headers
into the right place... A clip from the 'gcc/doc/install.texi':

-------------------- clip ---------------------------------------------
Some options which only apply to building cross compilers:

--with-headers=dir

  Specifies a directory which has target include files. This
  options is required} when building a cross compiler, if
  $prefix}/$target/sys-include doesn't pre-exist. These include
  files will be copied into the gcc install directory.
  Fixincludes will be run on these files to make them compatible
  with gcc.
-------------------- clip ---------------------------------------------

 What does the undefined 'include files' mean? "Some not very
well known 3rd party headers perhaps needing fixing?  Using
"the headers" instead would have hinted them being "the standard
C headers". The previous quote from the GCC-manuals, like the
comment in the 'gcc/cross-make' hints the 'sys-include' being
aimed for the 3rd party headers ("Use CROSS_INCLUDE_DIR not
TOOL_INCLUDE_DIR for other vendor's headers"). Whoever wrote
this text, should elaborate a little, otherwise it cannot be
understood... And for a person who thinks knowing the purpose
for the 'sys-include', this will be naturally be interpreted
meaning those 3rd party stuff... Besides the newlib and glibc
headers SHOULDN'T NEED any fixing (Isn't it more sane to fix
the bugs in the sources?), but at least the 'limits.h' in Linux
headers must be 'seen' during the GCC build... It will not be
seen now after a glibc build/installation (using old GCC), when
updating the GCC and using the existing stuff in $prefix/$target.
(unless one does a symlink between the 'include' and 'sys-include')

 This has been a mess for a long time, so could someone fix this
and put the configuration scripts, Makefile.in and gcc/cross-make
to follow the RMS manual, please ?  The places where to fix can
easily be found using the 'grep sys-include' for the configure*,
Makefile.in and gcc/cross-make... Also the misleading name,
SYSTEM_HEADER_DIR, should be changed into the STANDARD_HEADER_DIR.

With best regards,
Kai