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.
- 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
- 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 : -
-
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
- 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 runningzsh --version
.brew install zsh
- 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.
- 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
- 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 )
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"
- 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
- 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
- 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
- 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
- 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
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
-
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
git config --global --add --bool push.autoSetupRemote true
defaults write com.apple.dt.Xcode ShowBuildOperationDuration YES
- 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
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
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
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
A ruby version manager. Useful when you are working with tools such as fastlane which are heavily relying on a certain version of ruby.
brew install rbenv ruby-build
Then add the following in .zhrc
file to lLoad rbenv automatically.
eval "$(rbenv init - zsh)"
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 [email protected])"
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
Fastlane is useful for automating almost everything from development/release certificates generation to testing and releasing your app.
The following are an easy to follow setup guidelines.
xcode-select --install
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
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
The following steps are more advanced as they involve extra configurations for ruby version and installing bundler.
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+.
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
andGemfile
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 contentsource "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
, usebundle exec fastlane [lane]
- On your CI, add bundle install as your first build step
- To update fastlane, just run
bundle update fastlane
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.
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
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.
brew install hkamran80/things/multiliner
For more details, see Multiliner offical github repo
A tool which helps to deal with simulator folders. Useful to debug things like on device storage in Library folders etc.
brew install opensim --cask
For more detals, see OpenSim official github repo