Steps to build SelfControl from scratch with no prior OSX dev experience

Preamble

This post documents the steps required to be able to clone and build SelfControl from absolute scratch – as in, you haven’t done any Mac development to speak of before at all *as of Feb 12, 2016*. I assume you’re running El Capitan.

The only prerequisite I’m going to assume you have is Xcode because:

  1. I really don’t want to try to fully uninstall it from my machine for the purposes of this walkthrough and
  2. if you haven’t got it fully installed, the steps to getting that going are trivial (if you try to run something and it says you need to install more components, install those components. If it says you need to accept the command-line license, page through the full license text in the Terminal and type ‘agree’ (or whatever it asks you to type – I don’t recall the exact text)

(Edited: the above is not quite true. While writing the below I realized that I’m also assuming you are using Homebrew. Look, I’ve tried Macports, and I’ve tried Homebrew, and although there are a lot of pluses about Macports, the developer zeitgeist seems to be around Homebrew. It’s just easier, ok?)

Other than that, I’m assuming you don’t have any extra libraries or tools installed. The reason I’ve listed an exact date above is that I think that part of why this didn’t work for me but did for others is because of a recent change to Ruby that broke CocoaPods. So others couldn’t help me because either they weren’t using that version of Ruby or they’d already gotten their pods successfully installed; the SelfControl build wasn’t failing for them.

Steps

We’ll start with the official build instructions & go from there. I may submit a pull request to update some of the steps – step 2 is definitely wrong once you install the CocoaPods.

  1. Clone the repository
  2. Open SelfControl.xcodeproj in Xcode
  3. Switch the Scheme selector (upper-left-hand corner) to SelfControl — not Distribution
  4. Build!
1. Clone the repository

This is completely correct. However, if your goal is to contribute to SelfControl, you probably want to fork the repo and then clone your fork instead (after all, why are you building from scratch if you aren’t planning to contribute?). But for this walkthrough, you can just clone the official repo if you want. Go to the directory where you want to do your build and run:

git clone https://github.com/SelfControlApp/selfcontrol.git

If you forked the repo, you’d just replace it with your copy, e.g.

git clone https://github.com/karamcnair/selfcontrol.git

That’s what I did. Here’s what you’ll have in the directory after the clone.

 

git_clone

2. Open SelfControl.xcodeproj in Xcode

Nope. I’m not sure if the instructions are just out of date or whether there are multiple paths to building this project with CocoaPods but if you follow the instructions directly and try to build the .xcodeproj file you’ll get missing dependencies because the CocoaPod libraries aren’t there.

See?

So we’re going to take a detour from the official instructions at this point because this is what threw me off last summer and where we’re going off-road in our quest to get this working.

Let’s install CocoaPods

The way we do that is to use ‘gem’, the Ruby package manager.  The process should be:

  1. gem install cocoapods 
  2. pod install ***

WARNING: CocoaPods is currently (remember, this post is as of 2016-02-12) in beta for a new version with a totally different Podfile format. At first I accepted their suggestion to upgrade to the beta version, ended up rewriting the file, and it STILL didn’t work. Do not accept the beta version at this point. That’s not what the problem is.

Note the error we’re getting here: Undefined method ‘to_ary’ ? ¯_(ツ)_/¯

And at the end of the output we see this:

Something that took me longer than I’m happy with to notice:

/usr/local/lib/ruby/gems/2.3.0/gems

[But why would I even care? It knows what it’s doing, right?]

So what is the problem? How come everyone else building SelfControl doesn’t have this error. Well, it turns out that we’re too up to date, my friend! Our systems are too pristine, too fresh! We have the newest Ruby, the version that ships with OSX, and it’s version 2.3.0 (in my case) and not version 2.2. And there’s a problem with 2.3.x, as far as CocoaPods is concerned.

github_writeup

(Look familiar?)

Let’s see if that’s the problem. What Ruby we have now?

Yup. That’s probably it. So how do we fix that? This helpful person has an answer for us:

 

pod_solution

To do that, we use these instructions and to install rvm (Ruby Version Manager) to tell OSX which version of Ruby we want to use. But before we do that, let’s get rid of our current (bad) install of CocoaPods.

I know I could have just had you start by using rvm to pick Ruby 2.2 so that you wouldn’t hit the failing pod install but there are two reasons I didn’t:

  1. there are probably a non-zero number of people out there who have the same problem with the bad CocoaPods & by following these steps, this includes how to recover from that setup and
  2. it’s useful to document thought processes of how to debug & fix borked systems

gem uninstall cocoapods

Then install RVM as per the instructions:

Huzzah! We have the right Ruby! Let’s see if we can fix the Pod Problem!

Let’s REALLY install CocoaPods

So

gem install cocoapods

followed by

pod install

Hey! look at that! It worked.

So here’s where something weird is, that I don’t want to take the time to fully replicate on a freshly installed machine: The first time I got this working, THIS was the output from the ‘pod install’ command:

Note that it says to use the .xcworkspace file, not the .xcproject file. And it’s telling the truth. My directory has a SelfControl.xcworkspace file in it after ‘pod install’ but it didn’t tell me to use it this time. But if I don’t, and use the SelfControl.xcproject file, here’s what Xcode complains about:

See? The pod dependencies aren’t built. So we use the Workspace instead:

Cool, cool. Now we’re actually getting somewhere. The pods are building and so is SelfControl! But. Here come the promised code signing issues.

 

codesign1

OK, this post is too long now. And the code signing issues are ones that are likely common to multiple projects that have nothing to do with CocoaPods, so I’ll be adding a follow-on post just to walk through the OSX Code Signing traps!

Leave a Reply

Your email address will not be published. Required fields are marked *