Compile, Build or Archive problems with Xcode 4 (and dependencies)

Question

This question has evolved over the past several weeks to cover more general issues with xcode4 (and upgrading projects form older xcodes).

However many of the issues can be solved by following the same set of instructions.

If you have any of the following issues, try the methods in the accepted answer:

• Xcode 4 fails to archive an App
• Xcode 4 creates an unusable archive
• Xcode 4 does not create an .ipa
• Xcode 4 fails to compile due to preprocessor errors
• Xcode 4 cannot find headers
• Xcode 4's code complete is not working
• Project dependancies won't compile
• Adding a dependancy causes any of the above issues

Original Question

Title: "lexical or preprocessor issue file not found" in Xcode 4

I have a project in Xcode 4 that will build fine and run on the device and simulator but when trying to Archive it errors when looking for headers files associated with a static library:

In file included from /Volumes/Development/Path/LBProject/LBProject/LBProject-Prefix.pch:15:
In file included from /Volumes/Development/Path/LBProject/LBFDefines.h:23:
In file included from /Volumes/Development/Path/LBProject/Classes/LBProjectAppDelegate.h:11:
In file included from /Volumes/Development/Path/LBProject/LBProject/../FKNDirectory/FKNDirectoryManager.h:10:
/Volumes/Development/Path/LBProject/LBProject/../FKNDirectory/FKNDataModel.h:11:9: fatal error: 'Merchant.h' file not found [1]
 #import "Merchant.h"
         ^
1 error generated. 

Xcode gives the error

lexical or preprocessor issue file not found 

Much Googling has show many people are having this issue but no solution. Anyone got a fix or even a clue.

Update: The user header search paths are set to ${BUILT_PRODUCTS_DIR} in all configurations. It builds fine using any configuration except when archiving.

Update 2: Merchant.h is a Core Data class that is auto-generated and therefore inside .xcdatamodeld package, however the headers are all copied to the public headers directory when the library is built.

Answer 1

NB: The steps below will solve 90% of your Xcode archive issues however, from the comments it is suggested you try quitting Xcode first. This may save you hours of setting tweaking.

1. Check the "user header paths" are correct (Add "" to paths for spaces, both in your project and dependencies)
2. Set "Always search user paths" to YES
3. Create a group call "Indexing headers" in your project and drag the headers to this group, DO NOT add to any targets when prompted. This includes any headers inside your .xcdatamodeld, you'll need to right-click and view package contents to find them.
4. For all dependencies set "Skip Install" build setting to "Yes"
5. Moving any "Public" headers in Build Phases to "Project"
6. Set the Build Setting "Installation Directory" on your Target to $(LOCAL_APPS_DIR)
7. Change the target build setting "scan all source files for includes" to YES. (link)
8. With newer versions of Xcode (> 4.2) you might want to read this question related to workspaces.
9. Manually delete the project.xcworkspace files form all referenced projects