Open Radar

 
Summary: 
The use by XCode of the header map feature is very nice, but sometimes it totally prevents successfully building a project. In those cases, this feature must be disabled using the USE_HEADERMAP=NO custom build setting.

However, there are two problems:

1- the USE_HEADERMAP build setting is missing from the information panels (whether the project information panel or the target information panel). This makes this setting totally impossible to discover.

2- the USE_HEADERMAP is not documented anywhere that I could find. There are only a few mentions of it on the internet.

These two problems compound each other to make this very important setting totally obscure and impossible to discover.

Steps to Reproduce:
I could find to reasonable cases where the problem occurs:

1- a project header file has the same name as a system header file.
2- a project includes several variations of the same library with header files named identically. Typically, each variation of the library will be used by a different target in the project.

I was in case 2. My Xcode project was structured the same as my file hierarchy, like this:

MyProject
  TheirOldLib
    theirLib.h
    theirLib.cpp
  TheirNewLib
    theirLib.h
    theirLib.cpp
myCode.cpp

and myCode.cpp does thing such as:

#include "theirLib.h"
…
somecode()
{
#if OLDVERSION
  theirOldLibCall(…);
#else
  theirNewLibCall(…);
#endif
}
And of course, I define OLDVERSION for one target and not for the other.

Expected Results:
I expected to find a way to tell Xcode which header file was to be included by each target. I was unable to discover one until an Apple employee told me about the USE_HEADERMAP build setting.

Actual Results:
With header mappings, Xcode will include one of the two theirLib.h header files, the same for the two targets. So the one target for which this is the wrong header will not compile. I was unable to determine how Xcode decided which header to use.

Regression:
I reproduced that issue with Xcode 3.2.2. Similar problems are reported on the net by people using much older versions of Xcode.

Notes:
I found two workarounds:
1- rename one (or more) of the header to remove homonyms. This also implies changing many implementation file to include the newly named headers.
2- remove the header file from the project and then use header paths to get to the correct header.

Needless to say, both workarounds are extremely annoying.