Troubleshooting a framework which appears in red in my project in XCode 4.5

Question

When building any Mac OS X application which uses any framework which doesn't come in built in to the core, that is, some third party frameworks, it seems fairly common that I have problems where the framework appears in red when I look at it in XCode 4.5.

There are two most common places where it can appear in red, one in the project navigator pane (left side) and one in the build phases area. And a third place, in the Copy Files area, is often shown in red. All three have different causes.

Here's what it looks like when all three places are showing in red:

Clues for the observant among us: Some grayed out text after the red part suggests that XCode is possibly erroneously looking for the framework in question inside the XCode.app bundle. Also note that the framework is shown without any framework icon, just a place-holder icon is shown for the invalid framework in the image above.

If a framework is not found at all, then, when I build, the framework's header files cannot be imported, so I get a "Lexical or Preprocessor issue". The resolution there is to usually fix the Framework search path. However, even when that seems to be correct, I still often get the red-framework.

Sometimes, the icon is red, and yet, the framework search path works well enough that the compile works fine (#import <Thingy/Thingy.h> works and I don't get any lexical-or-preprocessor-issue), but the project won't link or crashes when run, because the framework is referenced accurately at the compile stage, but not at the link or not at the copy files phase.

Here is a sample of what it would have looked like if XCode could not import the header file that is inside the framework:

This question is supposed to be general, and useful to anyone in future who sees a "red" framework in the list of frameworks. Yes, I've gone to the vendor to ask the vendor for help with their framework, that should be step one. However, I feel that the "XCode shows framework in red" is confusing enough that it deserves a general helpful answer, thus this question. Also, I have reason to believe that in this case, the vendor's installer works just fine, and this is a local problem on my machine, that other people might have in the future and might like help understanding and fixing.

After tearing my hair out, I figured out I can solve this problem in a really bad way, by copying the frameworks which appear in red into /Applications/Xcode.app/Contents/Developer/Library/Frameworks but that is probably NOT the right way to do it. It just seems wrong to do that. If I copy the frameworks that are located in /Developer/VendorName into the xcode app bundle's library/Frameworks, I can avoid the compiler not finding the framework.

The third party frameworks are currently automatically installed into a folder underneath /Developer that is named for the company that made the frameworks. Is XCode supposed to search all folders automatically under /Developer and locate those frameworks somehow?
Currently I'm guessing, that no it can't, so XCode probably has to be told exactly the path to find this third party framework, each and every time.

I have not been able to locate the Apple documentation on "how Xcode finds frameworks". There is a question here that asks just that, but the answers all deal with GCC header search paths, not with how Xcode finds frameworks and builds that search path.

What folders does XCode 4.5 search to locate libraries? Is the /Developer folder still searched even though XCode 4.5 itself is no longer in /Developer?

When a third party framework is to be installed for Mac OS X client usage, where should it be installed to, and how do you check if the installer worked? Is there some command line invocation that can list all available frameworks that are visible to XCode and installed on my system?

Footnote: A second style of working is to use the "Add Other" button to find a framework which is not in a known location, if I use that, then I often end up stuck with a project that builds, but which still fails at runtime, because the Copy Files feature doesn't find and copy things, because adding a framework to the copy phase using the plus button appears to be broken in XCode. There is a workaround though. I am asking initially how to work so that you don't need to use Add Other, but, if Add Other is the only way to go for third party frameworks, then, I still get stuck with the Copy Files feature not working. I believe that the solution to this is that the XCode project's own Framework Search path is not set up correctly for my system, and that's all I need to do to fix this particular case. In a nutshell, I'm wondering what the Global "Framework Search Path" is, and where it's set? Or is there ONLY an XCode project search path, and not a global framework search path? If I clean up the Framework search path, and then use Add Other to add the new framework, and carefully right-click and remove all Red items from the project navigator pane, and if I use only mouse drag and drop and do not use the + button to add frameworks to the Copy files, then I can get a framework in a private search path location to build and copy. Any attempt to use the + button in the Copy Files area, and to add a framework via that dialog appears to be blocked from working by some kind of odd XCode bugs where it adds the framework at the wrong location, as shown in the first picture above, where it has mis-remembered or cached that the third-party Framework is supposed to be in the Developer/Library/Frameworks folder inside the XCode.app bundle.

Answer 1

When I use third-party frameworks in an Xcode project, what works for me is to install the frameworks in /Library/Frameworks on my Mac and to add them the way you described in your footnote. If the project fails to build, adding a search path for /Library/Frameworks to the Framework Search Paths build setting is usually enough to get the project to build.

If you're copying frameworks to your app bundle and the copying isn't working, add the following setting to the Runtime Search Paths build setting:

`@loader_path/../Frameworks`

I'm not sure if you need the quotes at the beginning and end. I'm just quoting a comment to a blog post I wrote on SDL from someone who found the SDL framework wasn't being copied to the app bundle.

Regarding your question on where to install third-party frameworks on an end user's machine, if your app uses a framework and you want the user to be able to run your app without having to install the framework, copy the framework to your app bundle. If you need to install the framework on the user's Mac, /Library/Frameworks is the usual location for third-party frameworks.

Answer 2

Yeah this is a good question. I have been meaning to come and do a post on a related issue: creating a bundle for a static library project that includes a compiled momd file in it I could only get to work by having the library project nested under the project using the bundle. That is, nested inside Xcode, at the filesystem level it still appears as a peer. This has to do with how projects find the products of other projects.

Meantime, on your specific issue, I have used OCHamcrest on every project I've done for years and have never been able to get that to work reliably unless I actually install the framework files inside the project. Ideally, I would want to install OCHamcrest in one of the locations like /Library/Developer/Frameworks, but trying to make that work was so painful it was insane.

I have read documentation about where Xcode looks for frameworks and it is in /Developer/Library/Frameworks, and /Library/Frameworks. If you look in there, you'll only see apple stuff. Also, keep in mind that /Developer used to be a separate directory, until Xcode 4, so it didn't seem so stupid. Now, if you decide to go use a beta, you will be screwed. I am pretty sure that when Xcode 4.5 updates itself, though, in Applications, it will copy the Frameworks.

I hope someone has some better ideas!