The developers machine

Setting up a Mac made easy

We all know this story:

A new developer enters the company. Part of his Onboarding is setting up his Macbook and getting ready to work on the team. “There is some documentation in the wiki. Oh.. and here is the repository, where you can find the code. You'll figure it out.”

I’ve seen this quite often. Sometimes I was lucky and the documentation in the wiki was useful. Sometimes it wasn’t. It’s fate for documentation to get outdated, especially if it is not used very often. An easy step for improvement is by creating a setup script. This will install everything necessary to work. You need a specific Ruby version? Here it is. Some tool for linting? Here you go. By having this script and (of course) keeping it updated, you have some kind of living documentation and even a reproducible development environment. In this post we write a basic script to get you started. Sadly not everything can be automated. One of these problems are the command-line tools. You will have to install them yourself:

xcode-select --install

Having done this, let’s get started. Open a terminal and type the following:

mkdir -p <project-name>/Scripts
cd <project-name>/Scripts
touch Setup.sh
echo "#!/bin/bash" > Setup.sh
chmod +x Setup.sh

We have to fill our script with whatever we need. I use Brew as a packet-manager.

Add the following to your Setup.sh

# =========== Install brew ==========
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew update

Everyone who has used Ruby knows of Bundler. There is something similar for Brew, so let’s use it.

# ========= Install Apps ==========
brew tap Homebrew/bundle

In the same directory create a `Brewfile`. Within we will use all the necessary tools installed via brew.
Before we can continue, we need some more tools to install apps with a UI (brew cask) and even from the AppStore (mas). Add the following to your Brewfile:

cask_args appdir: "/Applications"
tap "caskroom/cask"
brew "mas"

Finally we can start adding the tools, we will use. This is just a selection. In future article you will find more to add.

• OpenSSL (macOS version is just plain old)
• Sublime Text (for any textfile other than Swift/Objective-C code)
• Chrome (I don't like Safari)
• Sourcetree (I prefer it over Tower or Xcode git)
• Xcode (no way around this one)

Add this to your Brewfile:

brew "openssl"
tap "sublime"
tap "chrome"
tap "sourcetree"
mas "Xcode", id: 497799835

And to your setup script:

brew bundle

This will install all listed apps. But there are a few more steps. Due to brew not wanting to link it, OpenSSL is a little bit more complicated to set up on macOS. So we have to do it by hand. Add to your setup script:

# ========== Linking OpenSSL ==========
ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/
ln -s /usr/local/Cellar/openssl/<version>/bin/openssl /usr/local/bin/openssl
ln -s /usr/local/Cellar/openssl/<version>/include/openssl /usr/local/include/openssl
Replace <version> with the installed openssl version

Okay.. here we can find one teeny tiny problem. Brew does not have any kind of version numbers. Instead it’s always installing the latest version. You can change this by creating your own tap with all Formulas in the correct version. I might create a post about it later on, but for now, we ignore it.

As you can see, creating a setup script is not too hard. Having one will amaze a new developer every time he gets started on the project. Using a script will reduce his setup time drastically. Furthermore it will reduce our documentation to:

1. Install command-line tools via 'xcode-select install'
2. Login into the AppStore
3. Checkout Project
4. execute Setup.sh

Our final script looks like this:

And this is our final Brewfile:

Alternatives

In case you don't want to install Xcode from the AppStore, you can also use xcode-install. Using this, multiple versions can be installed. One problem though is the resulting filesize of Xcode. It seems like the version from the AppStore is smaller.

# =========== install xcode ==========
gem install xcode-install
xcversion install 8.3

For this to work, you will have to set a few environment variables with username and password of your developer account. Furthermore you'll need a current version of Ruby. Since we are not using it (including xcode-install) yet, we will care about Ruby and controlling its versions later.

Conclusion

With our setup script so far, any developer joining us, will have the project environment setup within minutes instead of hours or days. We shouldn't forget to update the script though…

Next: Conventions

Previous: Blog introduction