bug#22186: Use {C,CPLUS,OBJC}_INCLUDE_PATH instead of CPATH

[Andy Wingo]

Hi,

I am building GDB from git, because I want to hack on GDB.  I have a few
build-related things in my profile, including GCC.  I enter an
environment for GDB like this:

  guix environment gdb --ad-hoc flex autoconf-2.64

Cool.  Very good.  I build:

  mkdir +2.0
  cd +2.0
  ../configure --prefix=/opt/gdb
  make

However, eventually:

  /bin/sh ./libtool --tag=CC   --mode=compile ccache gcc -DHAVE_CONFIG_H -I. 
-I../../bfd -I. -I../../bfd -I../../bfd/../include  -DHAVE_x86_64_elf64_vec 
-DHAVE_i386_elf32_vec -DHAVE_iamcu_elf32_vec -DHAVE_x86_64_elf32_vec 
-DHAVE_i386_aout_linux_vec -DHAVE_i386_pei_vec -DHAVE_x86_64_pei_vec 
-DHAVE_l1om_elf64_vec -DHAVE_k1om_elf64_vec -DHAVE_elf64_le_vec 
-DHAVE_elf64_be_vec -DHAVE_elf32_le_vec -DHAVE_elf32_be_vec -DHAVE_plugin_vec  
-DBINDIR='"/opt/guile-2.0/bin"'  -W -Wall -Wstrict-prototypes 
-Wmissing-prototypes -Wshadow -Werror -I../../bfd/../zlib -g -O2 -MT peigen.lo 
-MD -MP -MF .deps/peigen.Tpo -c -o peigen.lo peigen.c
  libtool: compile:  ccache gcc -DHAVE_CONFIG_H -I. -I../../bfd -I. -I../../bfd 
-I../../bfd/../include -DHAVE_x86_64_elf64_vec -DHAVE_i386_elf32_vec 
-DHAVE_iamcu_elf32_vec -DHAVE_x86_64_elf32_vec -DHAVE_i386_aout_linux_vec 
-DHAVE_i386_pei_vec -DHAVE_x86_64_pei_vec -DHAVE_l1om_elf64_vec 
-DHAVE_k1om_elf64_vec -DHAVE_elf64_le_vec -DHAVE_elf64_be_vec 
-DHAVE_elf32_le_vec -DHAVE_elf32_be_vec -DHAVE_plugin_vec 
-DBINDIR=\"/opt/guile-2.0/bin\" -W -Wall -Wstrict-prototypes 
-Wmissing-prototypes -Wshadow -Werror -I../../bfd/../zlib -g -O2 -MT peigen.lo 
-MD -MP -MF .deps/peigen.Tpo -c peigen.c -o peigen.o
  In file included from peigen.c:66:0:
  /home/wingo/.guix-profile/include/wchar.h: In function 'wctob':
  /home/wingo/.guix-profile/include/wchar.h:397:47: error: comparison of 
unsigned expression >= 0 is always true [-Werror=type-limits]
   { return (__builtin_constant_p (__wc) && __wc >= L'\0' && __wc <= L'\x7f'
                                                 ^
This is an error, and the error is in wchar.h, not in the invocation or
use of wchar.h.  Let's see where this file comes from:

  ls -l /home/wingo/.guix-profile/include/wchar.h
  lrwxrwxrwx 21 root guixbuild 79 Jan  1  1970 
/home/wingo/.guix-profile/include/wchar.h -> 
/gnu/store/q7k2dc3ylpjnjlhb59f01bxxab8fjxr6-gcc-toolchain-5.2.0/include/wchar.h

So!  gcc-toolchain-5.2.  Why is there an error?  Well, of course,
although harmless, the "error" exists in the source, though perhaps GCC
itself doesn't build with -Werror=type-limits, so they didn't see this
error in the release.  The error comes from the combination of the
-Werror and warning flags that GDB is building with and the files from
gcc-toolchain.

Backing up a bit, it's not something that I actually care about right
now.  I'm working on GDB, the error is innocuous, and I can't easily fix
GCC right now, nor do I care.  I'm also surprised this is happening --
wouldn't it be caught by some other distro user?  Well yes, except that
normally this header is in /usr/include, and by default, all warnings
are disabled for system headers.

And there's the rub!  Why am I getting a warning for code in
~/.guix-profile/include ?

The answer is interesting!  I quote the GCC manual, section "Environment
Variables":

    Some additional environment variables affect the behavior of the
    preprocessor.

    'CPATH'
    'C_INCLUDE_PATH'
    'CPLUS_INCLUDE_PATH'
    'OBJC_INCLUDE_PATH'
         Each variable's value is a list of directories separated by a
         special character, much like 'PATH', in which to look for header
         files.  The special character, 'PATH_SEPARATOR', is
         target-dependent and determined at GCC build time.  For Microsoft
         Windows-based targets it is a semicolon, and for almost all other
         targets it is a colon.

         'CPATH' specifies a list of directories to be searched as if
         specified with '-I', but after any paths given with '-I' options on
         the command line.  This environment variable is used regardless of
         which language is being preprocessed.

         The remaining environment variables apply only when preprocessing
         the particular language indicated.  Each specifies a list of
         directories to be searched as if specified with '-isystem', but
         after any paths given with '-isystem' options on the command line.

         In all these variables, an empty element instructs the compiler to
         search its current working directory.  Empty elements can appear at
         the beginning or end of a path.  For instance, if the value of
         'CPATH' is ':/special/include', that has the same effect as
         '-I. -I/special/include'.

So!  CPATH is like -I but C_INCLUDE_PATH et al are like -isystem.
Here's the docs for -isystem ("Preprocessor Options"):

    '-isystem DIR'
         Search DIR for header files, after all directories specified by
         '-I' but before the standard system directories.  Mark it as a
         system directory, so that it gets the same special treatment as is
         applied to the standard system directories.  If DIR begins with
         '=', then the '=' will be replaced by the sysroot prefix; see
         '--sysroot' and '-isysroot'.

What is a system directory?  Well, it's searched for after all -I
includes, but also header files in it are marked as system headers.
Many warnings are not issued for system headers; search the manual for
the phrase "system headers".  For example:

    '-Wsystem-headers'
         Issue warnings for code in system headers.  These are normally
         unhelpful in finding bugs in your own code, therefore suppressed.
         If you are responsible for the system library, you may want to see
         them.

So.  We should be using C_INCLUDE_PATH instead of CPATH, to mark system
headers as system headers.  Except that C_INCLUDE_PATH only works for C,
so we need to also set CPLUS_INCLUDE_PATH and OBJC_INCLUDE_PATH.  And
that's the proposal of this bug :)

Andy