This is a guide for setting up an Apple Mac for software development. Current versions of macOS have a fairly good default configuration for general-purpose use, but you do need to to adjust some of the security settings. In addition, you need to install several pieces of software in order to make the system useful for development.
Do This First!
Log in once, run Software Update, and ensure that the operating system is at the latest point release. After all of the updates have been applied, restart the computer.
Log in again and create an Admin user account for your use. If other people will be using the machine, create Standard accounts for them. Log out of the initial account, and log in to the Admin account that you have just created.
Always log in with this new Admin account. The benefit of leaving the initial account untouched is that it ensures that you always have a working account to login with.
Admin accounts have sudo privileges: All Admin accounts on a Mac may use sudo to run command-line utilities with administrative (root) privileges.
You should also find an external hard drive. Begin using Time Machine as soon as possible, as it provides the most easy method for backing up your system.
Configuring a User Account
Configuring The Trackpad
To make the trackpad behave correctly, ensure that these settings are enabled:
- System Preferences > Trackpad > Tap to click
- System Preferences > Accessibility > Mouse & Trackpad > Trackpad Options… > Enable dragging
Creating a Private Applications Folder
Once you have logged into your account, create a folder called Applications within your home folder. Whenever you are prompted to drag a new applications into the global Applications folder, put it in this private Applications folder instead. Some applications have to be installed to global folders, but in most cases you can keep the system directories clean by storing third-party products in your private Applications folder.
Securing the Safari Browser
Whether or not you regularly use Safari, you should open it once, and adjust the settings in case that you use it later.
First, choose Safari > Preferences > General and deselect the option Open “safe” files after downloading.
Then, check the plug-in settings. Go to Safari > Preferences > Security > Plug-in Settings… and review the plug-ins and settings.
Apple provide quite secure operating systems, but unfortunately convenience has won out over security in a few places. These can easily be corrected by changing a few settings. If you are using a laptop then you should probably make all of these changes as soon as possible.
Select System Preferences > Security & Privacy, and set the following:
- Under General, set require a password after sleep or screen saver begins to immediately
- Click Advanced… and select Require an administrator password to access system-wide preferences
- Under Firewall, click Turn Firewall On.
Enable File Vault NOW
Current versions of macOS include File Vault 2, a full-disk encryption system that has little in common with the much more limited File Vault 1. You should enable File Vault NOW, because it is the only protection against anyone with physical access to your computer. All other security measures will be completely bypassed if someone with physical access simply restarts the computer with a bootable pen drive.
File Vault really is secure, which means that you can permanently lose access to your data if you lose the passwords and the recovery key.
Set a Firmware Password
Set a password to stop access to the Recovery mode. Otherwise, any malicious individual can change the firmware settings to boot from a disc or device of their choosing. If you did not enable File Vault, then the attacker will have complete access to all of the files on the system.
Apple Knowledge Base article HT204455 provides full details.
Setting Up Time Machine Backups
Time Machine is simple to set up. Just take a suitably large external hard drive, plug it in to your Mac, and agree when prompted. The drive setup process will reformat the hard drive. The only settings that may need to change are the exclusions.
Choose System Preferences > Time Machine, and click Options. Add to the exclusions list any folders that contain ISO disk images, virtual machines, or database files (such as Entourage). If the external hard drive is short of space, exclude the System folder.
Setting Up for Development
The first step is to install a compiler. The easiest way to install one is with the Xcode Command Line Tools package.
Once you have the compiler that is provided by Xcode, you can use Homebrew to install everything else that you need. Homebrew itself manages packages for command-line tools and services. The Cask extension to Homebrew enables you to install graphical desktop applications.
Apple now provide the Xcode suite as a free download from the App Store. To install Xcode Command Line Tools, install Xcode from the App Store, then open a Terminal window and enter the following command:
Setting Up Homebrew
Homebrew provides a package management system for macOS, enabling you to quickly install and update the tools and libraries that you need. Follow the instructions on the site.
You should also amend your PATH, so that the versions of tools that are installed with Homebrew take precedence over others. To do this, edit the file .bashrc in your home directory to include this line:
You need to close all terminal windows for this change to take effect.
To check that Homebrew is installed correctly, run this command in a terminal window:
To update the index of available packages, run this command in a terminal window:
Once you have set up Homebrew, use the brew install command to add command-line software to your Mac, and brew cask install to add graphical software. For example, this command installs the Slack app:
brew cask install slack
Installing the Git Version Control System
The Xcode Command Line Tools include a copy of Git, which is now the standard for Open Source development, but this will be out of date.
To install a newer version of Git than Apple provide, use Homebrew. Enter this command in a terminal window:
brew install git
If you do not use Homebrew, go to the Web site and follow the link for Other Download Options to obtain a macOS disk image. Open your downloaded copy of the disk image and run the enclosed installer in the usual way, then dismount the disk image.
Always set your details before you create or clone repositories on a new system. This requires two commands in a terminal window:
git config --global user.name "Your Name" git config --global user.email "email@example.com"
The global option means that the setting will apply to every repository that you work with in the current user account.
To enable colors in the output, which can be very helpful, enter this command:
git config --global color.ui auto
Installations of macOS include older command-line versions of both Emacs and vim, as well as TextEdit, a desktop text editor. TextEdit is designed for light-weight word processing, and has no support for programming. This means that you will probably install your own preferred editor.
Setting The EDITOR Environment Variable
Whichever text editor you choose, remember to set the EDITOR environment variable in your ~/.bashrc file, so that this editor is automatically invoked by command-line tools like your version control system. For example, put this line in your profile to make Neovim (nvim) the favored text editor:
Setting Up Visual Studio Code
Both Visual Studio Code itself and many extensions from Microsoft use telemetry. Avoid using Visual Studio Code if you have concerns about privacy.
To install Visual Studio Code, enter this command in a terminal window:
brew cask install visual-studio-code
To make Visual Studio Code your default editor, use this line in your ~/.bashrc file:
export EDITOR="code -w"
Visual Studio Code enables telemetry and crash reporting by default. To disable these, set these options in Preferences > Settings:
"telemetry.enableTelemetry": false, "telemetry.enableCrashReporter": false
Microsoft and some other providers add telemetry to their extensions to Visual Studio Code. This means that you must check the description of each extension to know whether it will send data to remote services, even if you have disabled telemetry for Visual Studio Code itself.
If you use extensions, consider these:
- Support for your preferred languages, e.g. Python, Java, Ruby, or Go
- Git Lens to enhance the Git support in the user interface
- The Docker extension
- YAML Support
If you would like to enable Vim keybindings in Visual Studio Code, install the VSCodeVim extension.
Setting Up Neovim
To install Neovim on macOS with Homebrew, run this command:
brew install neovim
Remember to set the EDITOR environment variable in your ~/.bashrc file, so that this editor is automatically invoked by command-line tools like your version control system.
To make Neovim your default editor, use this line:
Once you have installed Neovim, create a file called ~/.config/nvim/init.vim. This is your configuration file for Neovim.
This command creates a init.vim file with the leader option specified to set a leader key:
echo 'let mapleader = ","' >> ~/.config/nvim/init.vim
Neovim and Vim 8 include support for plugins, which means that you do not need to use a third-party plugin manager.
To add plugins to current versions, first create a directory for plugins:
mkdir -p ~/.local/share/nvim/site/pack/git-plugins/start
Then add these lines to your init.vim file:
" Put these lines at the very end of your vimrc file. " Load all plugins now. " Plugins need to be added to runtimepath before helptags can be generated. packloadall " Load all of the helptags now, after plugins have been loaded. " All messages and errors will be ignored. silent! helptags ALL
You can now install plugins by using Git to download them to the packages directory. For example, this command installs the ALE plugin:
git clone https://github.com/w0rp/ale.git ~/.local/share/nvim/site/pack/git-plugins/start/ale
Oni automatically detects an existing Neovim configuration, and will offer to use instead of the default settings.
Setting Up A Directory Structure for Projects
To keep your projects tidy, I would recommend following the Go developer conventions. These guidelines may seem slightly fussy, but they pay off when you have many projects, some of which are on different version control hosts.
First create a top-level directory with a short, generic name like code. By default Go uses a directory called go, but you can change that when you set up a Go installation.
In this directory, create an src sub-directory. For each repository host, create a subdirectory in src that matches your username. Check out projects in the directory. The final directory structure looks like this:
code/ src/ bitbucket.org/ my-bitbucket-username/ a-project/ gitlab.com/ my-gitlab-username/ another-project/
Creating SSH Keys
You will frequently use SSH to access Git repositories or remote UNIX systems. macOS includes the standard OpenSSH suite of tools.
OpenSSH stores your SSH keys in a .ssh directory. To create this directory, run these commands in a terminal window:
mkdir $HOME/.ssh chmod 0700 $HOME/.ssh
To create an SSH key, run the ssh-keygen command in a terminal window. For example:
ssh-keygen -t rsa -b 4096 -C "Me MyName (MyDevice) <firstname.lastname@example.org>"
Use 4096-bit RSA keys for all systems. The older DSA standard only supports 1024-bit keys, which are now too small to be considered secure.
Setting Up Environments
Homebrew provides separate packages for each version of Node.js. To ensure that you are using the version of Node.js that you expect, specify the version when you install it. For example, enter this command in a Terminal window to install the Node.js 10, the current LTS release:
brew install node@10
Add the bin/ directory for this Node.js installation to your PATH:
If you need yarn, enter this command in a Terminal window to install it:
brew install yarn
Developer Tools for Go
brew install golang dep
The current version of Go includes experimental support for dependency management with modules, but existing projects are likely to either use dep, or an older tool.
Setting a GOPATH
By default, current versions of Go automatically create and use a go directory in your home directory as the GOPATH. To ensure that third-party tools and Terminal auto-completion work, you should still explicitly set the environment variables.
Set a GOPATH environment variable in your ~/.bashrc file:
Then, add this to your PATH:
Close the Terminal and open it again for the changes to take effect.
AdoptOpenJDK for Java Development
Install the macOS package of the OpenJDK from the AdoptOpenJDK project to avoid potential licensing and support issues. The versions of Java on the OpenJDK Website are for testers, and the Oracle JDK is a proprietary product that requires license fees.
Use the LTS version of the OpenJDK, unless you need features that are in the latest releases.
To manually install a copy of the JDK:
- Download the version of the JDK that you need from AdoptOpenJDK
- Unzip the download
- Copy the JDK directory to /usr/local/lib
- Edit your ~/.bashrc file to set environment variables. For example, to use jdk-11.0.1+13 as the Java version:
Most Java projects use the Apache Maven build tool. To manually install a copy of Apache Maven:
- Download the latest version of Maven
- Unzip the download
- Copy the Maven directory to /usr/local/lib/
- Add /usr/local/lib/MAVEN-DIRECTORY to your PATH environment variable
Replace MAVEN-DIRECTORY with the name of the directory that Maven uses, such as apache-maven-3.6.0.
Maven is written in Java, which means that the same package works on any operating system that has a JVM installed.
pipenv for Python Development
Unfortunately, macOS includes a copy of Python 2, so you will need to install Python 3 yourself. To maintain current and clean Python environments, you should also install pipenv. It drives the pip and virtual environment features that are included with Python itself, but is more powerful and easier to use than working with these features directly.
Enter this command to install Python 3 and pipenv using Homebrew:
brew install python3 pipenv
The pipenv tool itself will use the copy of Python 3 from Homebrew by default. To use this Python 3 interpreter without pipenv, specify python3 on the command-line and in your scripts, rather than python:
If you need to run the pip utility, rather than setting up a development environment with pipenv, always use the command pip3:
The Python Guide tutorial shows you how to work with pipenv.
rustup for Rust Development
The official rustup utility enables you to install the tools for building software with the Rust programming language. Click on the Install button on the front page of the Rust Website, and follow the instructions.
By default, the installer adds the correct directory to your path. If this does not work, add this to your PATH manually:
This process installs all of the tools into your home directory, and does not add any files into system directories.
RVM for Ruby Development
All macOS systems include a copy of Ruby, but it is outdated. To maintain current and clean Ruby environments, use the RVM system.
RVM relies on Git, so you must have a working installation of Git before you can set up RVM.
By default, RVM downloads copies of Ruby that have been compiled for your operating system. If there is no compiled version, RVM then falls back to downloading the source code and then compiling it on your computer. Enter this command to ensure that the requirements for compiling Ruby are on your system, using Homebrew:
brew install autoconf automake gdbm gmp libksba libtool libyaml openssl pkg-config readline
Finally, you can speed up installation of gem packages by disabling the generation of local documentation. To do this, create a file in your home directory with the name .gemrc and put this line in it:
gem: --no-ri --no-rdoc
If you develop any kind of database-driven application, it is useful to have a version of the database server available on your system. Consider using Docker containers for this. If you prefer to install services directly on to your workstation, Homebrew provides packages for PostgreSQL, MariaDB and MySQL.
To install PostgreSQL using Homebrew, enter this command in a terminal window:
brew install postgresql
This command installs the server, the command-line tools, and the client libraries that are needed to compile adapters for programming languages.
Homebrew also provides some commands for managing your PostgreSQL installation. For example, to start the server, follow the instructions that are displayed after the installation process is completed. If you upgrade your copy of PostgreSQL, you should use the postgresql-upgrade-database command that Homebrew gives you.
Installing MariaDB or MySQL
To install MariaDB using Homebrew, enter this command in a terminal window:
brew install mariadb
To install MySQL using Homebrew, enter this command in a terminal window:
brew install mysql
These commands install the server, the command-line tools, and the client libraries that are needed to compile adapters for programming languages. To start the server, follow the instructions that are displayed after the installation process is completed.
For compatibility, MariaDB uses the same names for command-line tools as MySQL.
Remember to set a password for the root accounts. First, login with the mysql command-line utility:
mysql -u root -q
The -q Option Disables Command History: By default, the command-line client stores the full text of every command in a history file. If you know that you are going to run statements that include passwords or other sensitive data, use the -q option.
Run these statements to change the password for root access:
UPDATE mysql.user SET password = PASSWORD('yourpassword') WHERE user LIKE ‘root’; FLUSH PRIVILEGES; EXIT;
You now need a password to login to the installation as root. To login with root again, use this command:
mysql -u root -p
Enter the password when prompted.
You should also remove the anonymous accounts and test database that MySQL automatically includes:
DROP DATABASE test; DELETE FROM mysql.user WHERE user = ’’; FLUSH PRIVILEGES;
If you intend to duplicate a production environment for testing, create a configuration file on your Mac. Production installations of MySQL should be configured with appropriate SQL modes to enable data integrity safeguards. By default, MySQL permits various types of invalid data to be entered.
Other Useful Desktop Applications for Developers
- LibreOffice suite: brew cask install libreoffice
- VirtualBox virtual machine management: brew cask install virtualbox
- Docker container management: brew cask install docker
- MySQL Workbench: brew cask install mysqlworkbench
Apple offer overviews and task-orientated help on their support Web site for new macOS users.
Every new user should probably read How to switch to the Mac, by Rui Carmo.