In my last post I alluded to the problem of Xcode showing multiple products with the same name without differentiation in the UI:

It’s bad enough to have two items there with exactly the same description, but it’s particularly annoying (especially when the products list is quite long) that the ordering of items in this section apparently cannot be customized at all.

If memory serves correctly, the Products folder used to just be an ordinary group in Xcode, where you might happen to organize your “product items.” It’s only recently that Apple has barred reordering of the items in the group.

It occurred to me that I could probably hand-edit the project.pbxproj file inside the Xcode project. Sure enough, rearranging the lines of the file such that the “children” of the “Products” PBXGroup item are in the desired order does the trick.

However, I won’t be hand-editing Xcode project files for this purpose anytime soon, because If found another glitch in Xcode that makes it even simpler. Just rename the “Products” group to anything but Products, then rearrange at will:

Change the name back to “Products” when you’re done, and you’re done.

When Apple introduced the Mac App Store, it was clear that I would need to produce two distinct versions of my apps: one custom-built so suit the specific requirements of the App Store, and one built the way it always ever was, to be distributed directly to customers.

The approach I took was to simply duplicate the application target in all of my Xcode projects, such that for every final app target, there is a counterpart for the App Store:

Because the vast majority of build settings for all of my products are specified in Xcode configuration files, there isn’t much duplication here. True, each of the targets has to list its dependencies, resources, linked libraries, etc., but for the most part I go about editing source files on a day-to-day basis and when I ship an app update it just comes down to building and archiving each target in turn.

If you look carefully at the screenshot above, you will see that the MarsEdit App Store target has “MarsEdit” set as its product name. This is good, because I want each of the resulting apps to be named “MarsEdit.app.” As far as I know, there is no getting around it: the two targets have to share the same product name in order for them to build differing products that nonetheless have the same name.

This mostly works fine, in spite of a few Xcode glitches. One example is the auto-generated “Products” group in the project navigator shows two entries called “MarsEdit.app,” and doesn’t give any indication of which one is which. This can make it slightly annoying to easily e.g. right-click on a product and reveal it in the Finder.

Now as it happens I also define multiple targets that share the same product name in some of my supporting framework projects. Particularly since Apple started supporting the use of frameworks for iOS code, I’ve changed my iOS static library bundles over to frameworks. So where I used to have RSFoundation.framework and RSFoundation.o, I now have two targets, each producing a framework for the desired platform. Here’s an example where Xcode actually handles the doppelgängers with some aplomb. If you go to add a framework to a target and there are duplicates with the same name, it takes care to differentiate them:

Recently I ran into a troubling behavior with Xcode’s testing schemes, that I’ve correlated with the scenario of having a testing bundle target in a project that specifies as its test host a specific one of two targets whose product names match. The bug, in a nutshell, is Xcode can end up deciding that both targets should be built as forced dependencies of the test bundle, leading to annoying, hard to explain behaviors. I wrote this up as Radar 19924983 if you’re interested in reading more. And here’s the sample project I included with the bug, if that is something you’re interested in checking out.

On the whole I’m pretty happy with the approach of using separate targets with the same name. I am pretty sure I could work around whatever bugs I come across by resorting to splitting the two targets up into independent Xcode projects, but that feels a lot less elegant to me. The fact that Xcode supports duplicate names as well as it does in e.g. the “add libraries” panel I showed above gives me hope that support for namesake product targets will continue to improve in the future.

When Apple announced support for clang modules a few years ago, I jumped right in. I was curious to see what the build-time improvements might be, among other promised advantages.

Unfortunately things didn’t go well at the beginning. I ran into at least one bug, and probably more if I scratch my memory a bit harder. As cool as modules might turn out to be, they were not ready, at least for me.

Time heals some wounds, so I decided to take another look recently. I was annoyed by mysterious Xcode build failures, and at least some of them had to do with precompiled headers. I remembered in the back of my mind that modules were meant to (at your discretion) completely supersede precompiled headers, so I decided to give them another try.

True to form, I ran into another bug. This time, though, I could see a workaround in breaking down my monolithic project structure into smaller pieces. It was something I wanted to do anyway, and it would work around the modules problem. Win, win?

When I say I wanted to “break down” a monolithic project, I mean that, for example, a single ABC.xcodeproj that contains targets for A.framework, B.framework, and C.framework should be broken up so that each framework has its own .xcodeproj file. The monolithic structure is not too problematic on the face of it, but when you end up harboring references to specific targets in the monolithic project from various levels of other projects, things get a little hairy. In the case of the modules bug I reported, it seemed that some amount of cyclical referencing was responsible for surfacing the issue.

Unfortunately, breaking an Xcode project up can be fraught with peril. There is no easy way to say “take this target from ABC.xcodeproj, and move it to A.xcodeproj.” On the face of it, you’re stuck making a new A.xcodeproj and then painstakingly recreating the target definitions, file references, build phases, etc., that make up the rules for generating the target’s products.

A trick I use in this situation is to literally duplicate the ABC.xcodeproj file, then go in and hack out everything that isn’t contributing to the target you care about preserving. In this case, to get A.xcodeproj, I make a copy, then delete from the project any files that are solely used for B.framework or C.framework. The result is a standalone project for building A.framework. Of course, to avoid harboring redundant build targets for A.framework, you also remove from ABC.xcodeproj any of the files that are solely meant for building it.

That solves part of the problem, and you end up with a shiny new A.xcodeproj. But now you have to go trawling through your source bases, looking for any references to ABC.xcodeproj that expect to link to A.framework through it. These builds will now fail, because ABC.xcodeproj doesn’t have a target for the desired build. Worse, the way Xcode copes with this failure (dependent target suddenly missing), is to simply remove the dependent framework from both the dependencies and linked libraries list for the higher-level target.

To solve the problem, you have to add a project reference to the new A.xcodeproj, and then reconstitute both the dependency and linkage rules for the target. Once you do this for all the possibly umpteen-million targets that previously referenced A.framework in ABC.xcodeproj, you will once again enjoy a working build.

Ah, but thanks to an insidiously helpful new feature of modules, you don’t strictly have to do all of this. Enabling modules for your Xcode targets also opens the door to a feature called automatic linking which will cause modules that are imported by a target’s sources to be automatically linked. So, in a nutshell as long as my source code still contains references like:

#import <A/A.h>

Then Xcode and clang will helpfully also add the required framework linkage when building my target.

Ugh, that is so frustrating!

This sounds so helpful, how could I possibly be against it? The problem with auto linking is it will quietly mask any absent-minded dependencies on frameworks that violate the separation of concerns you have diligently instilled on your codebase. Put more bluntly: auto linking encourages spaghetti code.

One of the great advantages of frameworks is that they put up firm put permeable walls between the various components of a source base. If a given framework in your source base is intended to operate independently of the user interface, it’s easy to maintain this discipline by, for example, abstaining from linking with UIKit, AppKit, or whatever other user-interface frameworks may be at your disposal. Then when you absent-mindedly add a dependency to NSImage in your Foundation-level code, you’ll be greeted by a compiler error when it goes to link.

Not so with auto linking. The build completes without error, and now your LowLevelStuff.framework depends on UI frameworks. The permeable walls afforded by frameworks are no longer firm. You might argue: “What’s the big deal? It’s one little NSImage reference.” True, but it’s one little chink in the dam that gives you any sense of ownership or sanity about the scope of your code. Let that dam erode and you have cross-references not just between UI and Foundation layers of your code, but among and between any and all frameworks of varying, allegedly precise purposes. I.e. spaghetti code.

Discipline is one of the greatest and most rewarding challenges of programming. To the extent we successfully impose effortless standards on ourselves, we make the task of maintaining discipline that much easier. The firm walls of framework dependency are one such standard: a gentle reminder in the course of our daily work that things are running, even if only slightly, off the rails. Without those gentle reminders we’re bound to discover only months or years from now just how far we’ve diverged from our intended course.

In summary: enable clang modules, they’re pretty good.

CLANG_ENABLE_MODULES = YES

But automatic framework linking leads to lack of insight about actual dependencies between targets.

CLANG_MODULES_AUTOLINK = NO

Now that my source base is completely converted to using modules and eschewing precompiled headers, I feel good. I haven’t noticed any particular speed improvements, but I feel on board for the future. Adopting them sets me up for easier interoperation with Swift, when the time comes, and will surely spare me any bugs that sprout up specifically with precompiled headers, which Apple is no longer strongly motivated to fix.

In the course of practicing my on-again, off-again unit testing discipline, I find myself frequently wanting to zero in on just a few tests, so that I can quickly invoke tests from Xcode (Cmd-U) without suffering the lengthy re-running of a bunch that I already trust will pass.

Luckily the Xcode scheme editor provides for this, allowing tests to be disabled or enabled by file and even by individual test method. Instead of testing with Cmd-U, use Cmd-Opt-U to bring up the scheme configuration panel.

However, I’ve found the logic behind whether Xcode will enable or disable a whole slew of tests to be somewhat unpredictable. You can hold down the option key while clicking to affect its behavior, but I inevitably wind up clicking it the wrong way, such that the test I actually want to click is no longer enabled (because its parent file is unchecked).

Today I discovered a handy trick which is probably an oversight on Apple’s part: even when the checkbox for a specific test is disabled, it can be selected by control-clicking on the test’s row and selecting “Enabled Test” from the popup menu.

The great thing about this method is it takes care of whatever other enabling needs to take place for the selected test to be allowed to be enabled. I’m sure I will use this trick often.

I maintain an extensive array of automated builds with Jenkins. The automatic reporting of inadvertent build failures empowers me to stay much more on top of the quality of my own code, which is shared across many projects and targets many platforms and OS releases.

Unfortunately, I have frequently run into trouble with “false negative” builds. Builds which fail for perplexing reasons that I can usually only chalk up to “welp, something changed in Xcode.”

Sometimes the problem has seemed to be rooted in its finicky behavior with respect to paths that have spaces in them. Fine, I’ve removed all the spaces from my paths.

Other times, the problems have been much more nuanced, having to do with the problematic (I guess) sharing of cached data between builds. I don’t know how much of this should be chalked up to the fact that I’m building multiple projects at once, or that I’m building multiple problems of the same name, but with different dependencies and platform target. In any case, I have come to realize that the key to making sure my builds, you know, build when they should is to isolate each build as much as possible from the others.

To this end, over the years I have taken advantage of Xcode build settings such as SYMROOT, the setting that defines where your “Built Products” should be stored. But that only affects where the final products are saved. To make sure intermediate files that are used to build a product don’t get mixed and matched, I also override OBJROOT.

Overriding those two gets you a long way towards isolating a build from other builds that may have happened recently, or that may be happening right now. But, as it turns out, they don’t get you far enough.

Apple has increasingly moved towards some valuable changes in their approach to handling “cache” type data, including precompiled headers, header maps, module caches, etc. To the extent that Apple can use these caching strategies to enable faster builds, I’m all for it. But on my build server, it’s inevitably led to confusion and disarray.

Recently I’ve run up against confounding build errors that I can’t quite trace to specific problems. All I know is that “wiping out the Derived Data folder” solves it. Adding yet more build setting overrides to my build process also seems to solve some of the issues. For example, faced with a litany of precompiled header errors along the lines of:

fatal error: file 'BlahBlah.h' has been modified since the precompiled header 'WhooHah_Prefix-fmvtpvxgevrsamfytqmaabjnyjyx/WhooHah_Prefix.pch.pch' was built

I have found some relief by adding another override, this time for the SHARED_PRECOMPS_DIR. Recently, I ran up against a similar kind of failure, presumably related to the fact that I have started taking advantage of Apple’s support for “modules”:

fatal error: malformed or corrupted AST file: 'Unable to load module "[...]/DerivedData/ModuleCache/LQKN4K4Q4BR6/Foundation-1SPG61SLRK6SC.pcm": module file out of date'

That’s fine, but where is the “modules” equivalent of SHARED_PRECOMPS_DIR? It probably exists, though it’s not documented on the aforelinked build settings reference. Worse, since the advent of the DerivedData folder, it seems some of the claims in the build settings reference about default values are no longer true.

“Fine,” I thought, “how the heck do I override the Derived Data folder location altogether?” I don’t know why it took me so long to pursue this line of thinking. Perhaps my allegiance to the idea of saving effort through shared caching was too strong for my own good. When it comes down to it: I don’t mind that builds take a little longer or use more disk space, so long as they are an utmost reliable reflection of the current status of my source bases.

But how do you override the Derived Data folder location? If there is a build setting for it, then like the module caches folder, is evidently too new to be well-documented. Examining the build process in Xcode, it seems to be defined at a higher level than any of the other environment-variable based settings that can be observed in the build log e.g. for custom build phases.

I know you can set the Derived Data folder location in Xcode’s UI, but that, I assumed, only affects the builds that happen within the app. The brilliant idea finally dawned on me to check the xcodebuild man page, and what do you know?

-derivedDataPath path

Overrides the folder that should be used for derived data when performing a build action on a scheme in a workspace.

Since the vast majority, if not all, of the various cache and cache-like folders I’m trying to override are in fact located by default within the “Derived Data” folder, overriding just it could be the lynchpin that ensures my builds are isolated from one another.

I adjusted my build scripts to no longer override OBJROOT, CACHE_ROOT, or SHARE_PRECOMPS_DIR. Instead, they simply pass -derivedDataPath to xcodebuild with a suitably unique path:

xcodebuild -project MyProj.xcodeproj -scheme "MyScheme" -derivedDataPath "./MyCache"

You know what? Suddenly all my Jenkins builds are passing all their tests. Son of a gun.