XCode Header Path Confusion

XCode’s search rules for header paths are a strange beast. The most obvious aspects to take into consideration:

• Correct SDK root
• “Header Search Paths” (Project Settings)
• “User Header Search Paths” (Project Settings)
• “Always search user headers” (Project Settings)

But there is one more element that will throw a spanner-of-confusing-impending-doom into the works: Header Maps.

This nifty and undocumented feature is basically a dictionary of all the filenames in your project (just the filename, not a fully qualified path), supposedly to speed up building, but it definitely gets in the way (in a big way) sometimes.

To keep a long story really short, if your build looks like the header search paths are very confused for example #include <math.h> actually includes a file in your project named Math.h regardless of folder depth that resides somewhere in your project (you can check this using  ”Build” > “Preprocess” and check which files its actually #included’ed)

Project > Edit Project Settings > (Cog Button Bottom Left) > Add User-Defined Setting

Name the setting USE_HEADERMAP and set its value to NO (EDIT 24/11/11: this was incorrectly USE_HEADERMAPS – should not be plural, thanks Simon for pointing this out)

Now all header includes MUST be relative to the file they are included from OR be explicitly relative from any of your specified header search paths.

More reading provided below:

http://web.archiveorange.com/archive/v/JT06F65y3o5h2vjWtjBo

http://www.openradar.me/7840694

http://www.omnigroup.com/mailman/archive/macosx-dev/2005-March/056049.html

http://stackoverflow.com/questions/2596695/controlling-which-project-header-file-xcode-will-include

Excuse the keyword dump here, it was hard to find this out so I hope this will help others looking:
cannot find correct system headers, header path order, include path order, search path order, Xcode include file quotes, header maps, hmap, import directive, include confused, incorrect include search path