MacDevSetupGuide

Recently I changed my development mac from Intel based Machine to Apple's M1 Max. Since they are two different architectures I decided to ditch Time Machine backup and start fresh on the new Chip. However I found myself having to redo the process of configuring my development environment from scratch. It's something which I did years ago on my intel based Mac as you might have guessed it's difficult to remember all the steps without searching around the web.

To avoid going through the same route in the future every time I change to a new Machine I have decided to document all the steps. I made them public so that new devs or other senior devs can take advantage of it when needed.

Enough talking below are the steps to setup new MacBook for development.

Disclamer: These configurations are based on my experience as an iOS Dev so it might not work well for other fields but can be useful if your main development Machine runs MacOS.

1. Homebrew

• The first this I do is setting up homebrew for it to act as a package manager for most of the apps/CLI tools I use in my day to day development.
• Note: Even though homebrew require Xcode Command lines tools to be installed first you don't need to manually install them as the command to install homebrew will automatically install Xcode select tools for you if not installed already.
• The magic command needed is as follows: -

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• Further installation details and other guidelines can be found on the official homebrew website

2. Xcodes App

• Note it's Xcodes notice the "s" at the end, Not Xcode. This is a cool app to speed up Apple's Xcode download as well as maintaining multiple versions of Xcode.
• I normally use homebrew to handle the installation process for me using the following command : -

  brew install --cask xcodes

• Other details on how the app work or alternative ways to install it can be found via the following link : -
  • App Version
  • Command Line Version

3. iterm2

• iTerm2 is a replacement for Terminal and the successor to iTerm. It works on Macs with macOS 10.14 or newer. iTerm2 brings the terminal into the modern age with features you never knew you always wanted.

  brew install --cask iterm2

4. zsh (Only if not pre-installed)

• Zsh is a shell designed for interactive use, although it is also a powerful scripting language.
• Before running the following command, make sure that there is no pre-installed zsh in your system by running zsh --version.

  brew install zsh

5. zsh-syntax-highlighting

• zsh sytanx highlighting provides syntax highlighting for the shell zsh. It enables highlighting of commands whilst they are typed at a zsh prompt into an interactive terminal. This helps in reviewing commands before running them, particularly in catching syntax errors.

  brew install zsh-syntax-highlighting

• After running brew install command above follow the instructions here on how to activate it.

6. zsh-autosuggestions

• zsh-autosuggestions add the ability to auto-complete as you type.
• Easily install it via homebrew as follows : -

  brew install zsh-autosuggestions

• Similar to syntax highlighting to active the plugin simply add the following line at the bottom of .zshrc file. source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh

7. ohmyzsh

• Oh My Zsh is an open source, community-driven framework for managing your zsh configuration.
• There are various ways to install this but, I used curl by running the following command on my iterm : -

  sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

• After installation follow instructions here on how to take full advantage of it.
• Just for reference the following are some of the settings in my .zshrc conf file.

  #plugins
  plugins=(
  git
  )

7.1 ohmyzsh themes

To set other themes than the default one See Themes Wiki As a reference the following is a theme which I use on my custom configuration.

Inside a .zshrc file add the following: -

ZSH_THEME="jonathan"

8. Custom scripts

• As you can see throwing all custominizations in .zshrc file can get out of control as you add more scripts. To handle this situation I prefer to put all my custom alias/shortcuts into their own file. I named this file as .customMuchabBashCommands.sh located in root folder. Then I load it as follows in .zshrc file.

    # Load from custom scripts (More about this will be explained on the future sections)
    #source ~/.customMuchabBashCommands.sh

9. CocoaPods

• Even though currently Swift Package manager is continue to be adopted still there are lots of projects which are still heavily relying on cocoapods so install it in advance.

  brew install cocoapods

10. carthage

• Carthage is intended to be the simplest way to add frameworks to your Cocoa application.

  brew install carthage

• A note about carthage issue on M1 Macs. There is a known issue which happens during build phase of Xcode Project having libraries/frameworks depending on carthage. To fix this issue you need to create a symbolic link to carthage version mananged by brew.

Important: Make sure you have a bin folder located in /usr/local first otherwise you will get an error of missing directory.

• Step 1: Create bin directory

   # assuming that you are inside /user/local folder.
    sudo mkdir bin
  

• step 2: Create a symbolic link

   sudo ln -s /opt/homebrew/bin/carthage /usr/local/bin/carthage
  

11. gitignore file

• On every new project this file should be the first thing to configure. So since I work on iOS projects most of the time. I have a common file which I include in almost all iOS projects.

  # On every new project folder, before any new file is created run. 
  touch .gitignore

  • Then populate it with the contents of this file

12. GitHub CLI

• From the official website GitHub CLI, or gh, is a command-line interface to GitHub for use in your terminal or your scripts.
• To install using homebrew run the following command : -

   brew install gh

• After installing make sure you follow the instructions on how to authenticate with Github so that you can quickly start working on existing projects hosted on Github. TL,DR version of the doc, simply run the following command and follow the interactive terminal guidelines.

  gh auth login

13. Configure Git's user name & email.

 git config --global --edit

Doing so will open vim editor. Proceed by updating configurations. As a reference the following are my configurations as for the time of writing this (May 26, 2022). Note that if other things don't make sense at least configure the [user] section with your name and email then google sections which you don't understand.

 [filter "lfs"]
    process = git-lfs filter-process
    required = true
    clean = git-lfs clean -- %f
    smudge = git-lfs smudge -- %f
 [user]
    name = <your name>
    email = <your email>
 [core]
    excludesfile = ~/.gitignore_global
 [merge]
    tool = opendiff
    ff = false
  [mergetool]
    keepBackup = false
 [pager]
    branch = false
    log = true
[pull]
    rebase = false
    ff = only
[init]
    defaultBranch = main

14. Get up and running with your remote git projects

• Clone a git repo. This will only clone the master/main branch.

  git clone <remote URL>

• To work with git branches I found the following commands very useful.

  # To list remote branches:
  git branch -r
  
  #You can check them out as local branches with:
  
  git checkout -b LocalName origin/remotebranchname
  

• Note you might need to set git credentials using github access token. Below is the method I normally use to do so globally as described below.

• Step 1:

git config --global credential.helper

• Step 2:

git config --global --unset credential.helper

• Step 3:

git config --global credential.helper osxkeychain

After the three steps above you can try an of the git commands such as git pull or git clone, you should be prompted to enter your access token. Follow the instructions on Github to Create an Access Token in Github.

Reference: add-update-refresh-github-access-token-on-mac

Automatically create git remote branch if it doesn't exist.

git config --global --add --bool push.autoSetupRemote true

15. Show Build time on Xcode

defaults write com.apple.dt.Xcode ShowBuildOperationDuration YES

16. Rectangle

• Rectangle is an opensource app which help to save a lot of time by quickly use keyboard shortcuts to move or resize windows on MacOS. It is very similar to Spectacle but unfortunately Spectacle is no longer maintained but it still working as I have been using on my old intel based Mac with no issues.
• To install Rectangle simply run the following command

  brew install --cask rectangle

• Important: there is an issue mentioned in the official rectangle doc that iTerm2 resizing is somehow off due to it's internal restriction. Read more on the relevant link for more info. But to fix the issue simply run the following command on your terminal.

    defaults write com.googlecode.iterm2 DisableWindowSizeSnap -integer 1

17. Git Large File Storage

From the official site definition Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server like GitHub.com or GitHub Enterprise.

To install run the following command

     brew install git-lfs

It is very easy to use this tool, simple follow the instructions on the official website here

18. FengNiao

A command line tool for cleaning unused resources in Xcode. It is useful if you have a huge project or legacy project with logs of old image assets which are no longer needed.

To install it, you need to use Mint,

    brew install mint
    mint install onevcat/fengniao

19. fui

A tool to help finding unused Objecitve-C imports. For those who have inherited legacy Objective-C projects. This tool can be very useful to find used legacy code as you port it to another language eg: Swift.

Installation

sudo gem install fui

20. rbenv

A ruby version manager. Useful when you are working with tools such as fastlane which are heavily relying on a certain version of ruby.

Installation

brew install rbenv ruby-build

Then add the following in .zhrc file to lLoad rbenv automatically.

eval "$(rbenv init - zsh)"

Suggested build enviroment

Before doing anything with rbevn the following setup are recommended

If you haven't done so, install Xcode Command Line Tools (xcode-select --install) and Homebrew

For Ruby versions 2.x–3.0:

brew install openssl@1.1 readline libyaml gmp
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)"

Ruby 3.1 and above requires OpenSSL 3:

brew install openssl@3 readline libyaml gmp
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix > openssl@3)"

IMPORTANT: In order to be able to use the installed openssl 3 certificate, brew gave gave the folowing suggestion.

brew suggestion

==> Caveats
A CA file has been bootstrapped using certificates from the system
keychain. To add additional certificates, place .pem files in
  /opt/homebrew/etc/openssl@3/certs

and run
  /opt/homebrew/opt/openssl@3/bin/c_rehash

openssl@3 is keg-only, which means it was not symlinked into /opt/homebrew,
because macOS provides LibreSSL.

If you need to have openssl@3 first in your PATH, run:
  echo 'export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"' >> ~/.zshrc

For compilers to find openssl@3 you may need to set:
  export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib"
  export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include"

I had to follow what homebrew suggested at the end of installation to make commands which rely on the installed certs to work.

In .zshrc file add the following.

# Installed openssl version 3, with command -> brew install openssl@3 readline libyaml gmp
# Got errors suggesting to add the following setups.
export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"
# Enable compilers to find openssl@3.
export LDFLAGS="-L/opt/homebrew/opt/openssl@3/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl@3/include"

Using RUBY_CONFIGURE_OPTS to link to a specific OpenSSL installation like suggested above is not a strict requirement for installing Ruby on macOS, but it will speed up your Ruby installation and avoid any OpenSSL compilation issues.

Ruby 3.2 and above requires the Rust compiler if you want to have YJIT enabled:

brew install rust

Ruby 3.2.0-dev and above (only -dev versions) require Bison 3+:

brew install bison

Finally to install ruby versions follow Installing Ruby versions guideline.

TR/DR

# Example to install ruby version 3.1.3
rbenv install 3.1.3

# After installation run the following to set global rbenv ruby version
rbenv global 3.1.3

21: Fastlane

Fastlane is useful for automating almost everything from development/release certificates generation to testing and releasing your app.

Setup

The following are an easy to follow setup guidelines.

1. Xcode commandline tools

xcode-select --install

2. Install fastlane using homebrew

This is the quickest way as it doensn't need you to separately install and manage ruby versions. Simply run the following command.

brew install fastlane

3. Set up environment variables

The following are instructions based on official documentation section about setting enviroment variables.

fastlane requires some environment variables set up to run correctly. In particular, having your locale not set to a UTF-8 locale will cause issues with building and uploading your build.

In your ~/.zshrc add the following lines:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

For making tools like update_fastlane action to work the following extra enviroment variables need to be set.

export GEM_HOME=~/.gems
export PATH=$PATH:~/.gems/bin

Advanced Option (Recommended)

The following steps are more advanced as they involve extra configurations for ruby version and installing bundler.

---

4. Ruby

Fastlane uses ruby so installing ruby is needed however you can also use system ruby but it is not recommended.

👉 Follow rbenv installation guidelines above to install managed ruby. As noted in the official fastlane documentation supported ruby versions are 2.5+.

5. Bundler

According to the official documentation

Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.

From fastlane docs

It is recommended that you use Bundler and Gemfile to define your dependency on fastlane. This will clearly define the fastlane version to be used and its dependencies, and will also speed up fastlane execution.

• Install Bundler by running gem install bundler
• Create a ./Gemfile in the root directory of your project with the content

source "https://rubygems.org"
gem "fastlane

• Run bundle update and add both the ./Gemfile and the ./Gemfile.lock to version control
• Every time you run fastlane, use bundle exec fastlane [lane]
• On your CI, add bundle install as your first build step
• To update fastlane, just run bundle update fastlane

Initilize fastlane for a project

To set up a project and start using fastlane right away nagivate to the project root directory and simply run the following command.

fastlane init

Lastly follow instructions on What's next? section on the official setup documentation page.

22. onefetch

onefetch is a Command-line Git information tool. It is useful if you want to show project stats, such as development languages, lines of code etc.

Installation

brew install onefetch

Usage

> cd /path/of/your/repo
> onefetch

23. Multiliner

An Xcode source extension to expand lengthy lines.

func sum(num1: Int, num2: Int, num3: Int) {..} 

// Will be changed to
sum(
num1: Int,
num2: Int,
num3: Int
) {..}

Works with Initilizers, functions array & swiftUI modifiers.

Installation

brew install hkamran80/things/multiliner

For more details, see Multiliner offical github repo

24. OpenSim

A tool which helps to deal with simulator folders. Useful to debug things like on device storage in Library folders etc.

Installation

 brew install opensim --cask

For more detals, see OpenSim official github repo