Bug 13498 - CPP include search path documentation is incorrect
Summary: CPP include search path documentation is incorrect
Alias: None
Product: gcc
Classification: Unclassified
Component: preprocessor (show other bugs)
Version: 3.3.2
: P3 minor
Target Milestone: ---
Assignee: sandra
Keywords: documentation
Depends on:
Reported: 2003-12-27 18:09 UTC by fcusack
Modified: 2017-01-08 02:01 UTC (History)
2 users (show)

See Also:
Known to work:
Known to fail:
Last reconfirmed: 2005-11-02 01:41:20

documentation patch (909 bytes, patch)
2004-05-27 23:52 UTC, fcusack
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description fcusack 2003-12-27 18:09:14 UTC
The Search Path node of the CPP docs says:

On a normal Unix system, if you do not instruct it otherwise, it will look for headers requested with 
#include <file> in:

This is incorrect AFAICT.  The default search path on my system (as seen from gcc -v ...) is:

I didn't pass any special options to configure (eg --with-local-prefix), and the path doesn't seem 
to come from a specs file, so I'm guessing this is the hardcoded default.  To be absolutely clear, 
the two errors I see are the missing GCC_EXEC_PREFIX/include (2nd dir in path), and the doc 
simply says "/usr" when actually it's GCC_EXEC_PREFIX.  (I'm using GCC_EXEC_PREFIX as shorthand 
for the --exec-prefix arg I passed to configure.)

On a system where GCC_EXEC_PREFIX = /usr, the docs are correct, however that is a specific 
configuration; for the general case the docs are in error (apparently).  It's especially worth noting 
that the /usr/include dir is always last even if, by the rules for the general case, it would be 2nd.

Ultimately, I guess it comes down to, what is a "normal unix system"?  Given that /usr/local is the 
default prefix, I think the docs should be updated.
Comment 1 Andrew Pinski 2003-12-27 19:35:14 UTC
It is better on the mainline, In the manual:

Which is closer than before.
Here is what I get from cpp -v x.c -o /dev/null:
Comment 2 fcusack 2004-05-27 23:52:40 UTC
Created attachment 6406 [details]
documentation patch

I removed the paragraph about dirs appearing twice based on my
testing, however you should verify before committing.
Comment 3 sandra 2017-01-06 21:34:42 UTC
The search path reported by -v for various versions/targets of CPP I have installed here doesn't look like what was reported from the previous discussion on this ticket back in 2003.  I think the best way to correct/robustify/future-proof this documentation is to tell users to use -v, instead of hard-coding a directory list in the CPP manual.  (Maybe as a future enhancement it would be friendlier to have a new -print-include-path option specifically to get this information, instead of having to dig through the -v output.)

I also confirmed that the "paragraph about dirs appearing twice" is inaccurate per current behavior, and will take that out as part of the rewrite.
Comment 4 sandra 2017-01-07 22:46:44 UTC
Author: sandra
Date: Sat Jan  7 22:46:13 2017
New Revision: 244201

URL: https://gcc.gnu.org/viewcvs?rev=244201&root=gcc&view=rev
2017-01-07  Sandra Loosemore  <sandra@codesourcery.com>

	PR preprocessor/13498

	* doc/cpp.texi (Search Path): Rewrite to remove obsolete and
	redudant material, and reflect new command-line options.
	(System Headers): Likewise.

Comment 5 sandra 2017-01-08 02:01:17 UTC
Fixed for GCC 7.