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

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 . 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.