[RFC] Implementation and documentation of -iwithprefix do not match?

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

The GCC option -iwithprefix does not match the documentation.

Is there any reason for this discrepancy?

The GCC option -iwithprefix is documented in gcc/doc/cppopts.texi

@item -iwithprefix @var{dir}
@itemx -iwithprefixbefore @var{dir}
@opindex iwithprefix
@opindex iwithprefixbefore
Append @var{dir} to the prefix specified previously with
@option{-iprefix}, and add the resulting directory to the include search
path.  @option{-iwithprefixbefore} puts it in the same place @option{-I}
would; @option{-iwithprefix} puts it where @option{-idirafter} would.

However, -iwithprefix does not put the search path where -idirafter 
would, instead it puts the search path at the top of the SYSTEM chain.

See gcc/c-opts.c:
...
    case OPT_idirafter:
      add_path (xstrdup (arg), AFTER, 0, true);
      break;
...
    case OPT_iwithprefix:
      add_prefixed_path (arg, SYSTEM);
      break;

The order of the compilers SYSTEM paths is important to the correct 
processing of C++ header #include_next macros.

If you use -iwithprefix to modify the compilers -iprefix path to define 
a header that matches a SYSTEM header, the compiler removes the 
redundant SYSTEM path definition and leaves the one generated by 
-iwithprefix (it's the same path just in a different search order). 
However, since -iwithprefix moved the header definition to the *top* of 
the search list, when #include_next is used, it may result in a missing 
header.

If -iwithprefix implemented what was documented, then it appears that 
there would be no issue.

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