controlling which project header file Xcode will include

Question

My Xcode project builds to variations of the same product using two targets. The difference between the two is only on which version of an included library is used. For the

Answer 1

Why can't you just use different include paths in each target?

Answer 2

Xcode speeds up building by creating header map files.

Instead of providing the compiler with a list of directories where to search for headers, you can also provide it with header map files. A header map file is like a hashtable, the lookup keys are the include arguments, the values are the paths to the headers.

Here is an example for such a map file:
(Note: This is not the actual syntax of a header map file, it's just a human readable representation)

Foo.h -> /usr/include/Foo.h
Bar.h -> /home/user/Documents/ProjectA/src/include/Bar.h
foo/bar/foobar.h -> /home/user/Documents/ProjectB/inc/foo/bar/foobar.h

These three entries match

#include "Foo.h"
#include "Bar.h"
#include "foo/bar/foobar.h"

Now Xcode has three settings that control the generation of header map files.

1. HEADERMAP_INCLUDES_FLAT_ENTRIES_FOR_TARGET_BEING_BUILT
   If YES (default), all header files that belong to the target being built are added to the header map file and can be included using include "header.h". Note that headers can only belong to framework/library/bundle targets, not to application/program targets.

2. HEADERMAP_INCLUDES_FRAMEWORK_ENTRIES_FOR_ALL_PRODUCT_TYPES
   If YES (default), headers of all other targets are added to the header map file and can be included using include <TargetName/header.h>. Note that this is also true for non-framework targets.

3. HEADERMAP_INCLUDES_PROJECT_HEADERS
   If YES (default), all other headers present in the project file the built target belongs to are also added to the header map file and can be included using include "header.h".

Additionally there is the general setting USE_HEADERMAP that controls if a header map file shall be generated at all. Only if YES (default), Xcode will generate a header map file and pass it as argument to the compiler.

In case a header is not listed in a header map file or header maps aren't used, the compiler will search for the headers using one of two search strategies:

In case the header is imported with <...>, it will search in all directories specified with the -I option (HEADER_SEARCH_PATHS), all directories specified with the -isystem option (SYSTEM_HEADER_SEARCH_PATHS in Xcode), and in the stanadrd system header directories (/usr/include of the selected SDK and other directories belonging to the installed developer tools); in exactly that order and within each category in the order given.

In case the header is imported with "...", it will search in the same directory as the .c/.m file being built, in all directories specified with the -iquote option (USER_HEADER_SEARCH_PATHS in Xcode), and in the same directories it searches for <...>; in exactly that order and within each category in the order given.

Answer 3

Use USE_HEADERMAP=NO and in "User Header Search Paths" include your custom directory first and project directory recursively second: ${PROJECT_DIR}/TheirNewLib ${PROJECT_DIR}/**

Answer 4

USE_HEADERMAP=NO is overkill for some projects. It might be enough to just use HEADERMAP_INCLUDES_FLAT_ENTRIES_FOR_TARGET_BEING_BUILT=NO.

Documentation here:
https://developer.apple.com/library/archive/documentation/DeveloperTools/Reference/XcodeBuildSettingRef/1-Build_Setting_Reference/build_setting_ref.html

Answer 5

The key part of the answer is to use USE_HEADERMAP = NO as suggested by Chris in a comment. Here are the details.

Short recipe (checked in Xcode 3.2.2):

1. add a custom build setting of USE_HEADERMAP = NO for each concerned target. Here is how:
   1.1. Open the target's info panel on the "Build" pane.
   1.2. Pull down the action pop-up menu at the bottom left of the window, select "Add User-Defined Setting".
   1.3. In the newly added line, set the first column ("Setting") to USE_HEADERMAP, and the second column ("Value") to NO.

2. add the correct include path to each target (target Build settings "Header Search Paths"). In my example that would be:
   2.1. add TheirOldLib for "old" target
   2.2. add TheirNewLib for "new" target

Step 1 disables the automatic header map feature of Xcode, through which any header file included in the project is directly accessible through its name, whatever its actual path. When two headers have the same name, this feature leads to an unresolvable ambiguity.

Step 2 allows for the #include "theirLib.h" to work without qualifying the header file actual path name.

These two steps together fulfill my two constraints.

Finally, USE_HEADERMAP is not documented by Apple, as far as I can tell. I'll fill a bug report for that, as this setting is crucial in a number of cases, as googling for it reveals. Reported as rdar://7840694. Also on open Radar as http://openradar.appspot.com/radar?id=253401