Matti Goes to Fab Academy

How to setup a fresh MacOS computer for Fab Academy

Setting up a fresh macOS computer with development tools

I just recently reinstalled macOS from scratch on my old Macbook Pro. It had all kinds of clutter from way back, since I had transferred data to it from at least one older computer and over several OS updates. I had all my things setup there nicely, but the hard drive was almost full and there were weird freezing issues all the time.

So I took a backup and decided to start all over again. Just like I feel like I’m doing with my life in many ways. Kind of scary but it’s really needed. Having to do this also for Fab Academy gives me a good opportunity to document how I should do this with a fresh computer for later. Hopefully this also helps someone struggling with the setup process.

MacOS comes with a lot already built-in, but the first thing to do is to install some essential tools and setup my workflow for developing websites and programming microcontrollers.

1. Download and Install iTerm2

The built in Terminal on a mac does the job, but I moved to using iTerm2 a while back and it’s just really hard to go back to the default one. Installation is simple, just download it from the website and drag the application to your Applications folder.

I recommend to also download these color schemes for iTerm

  1. Go here iterm2colorschemes.com/
  2. Download the archive on that site (.zip or .tar.gz) and extract it
  3. In iTerm, go to Preferences -> Profiles -> Colors -> Color Presets -> Import…
  4. From the archive you downloaded, find a folder callled schemes and select all the color schemes you would like to try out. You can seee the previews on the website.
  5. After importing, you can again select Color Presets and your imported presets should be there.

2. Install Homebrew + XCode Command Line Tools

Go to brew.sh/ and follow the installation instructions.

Follow the instructions of the installer. It will also install the XCode Command Line Tools that you will need. You might have different prompts depending on your computer so I will not list all the steps here. Just follow the instructions during the installation process.

I also installed XCode itself from the App Store. You might not need it specifically for the Fab Academy stuff but I use it a lot with openFrameworks or when working with iOS. XCode takes up a lot of disk space though, so skip XCode if you don’t plan to use it for something. You still need the Command Line Tools but the Homebrew installer should take care of that.

3. Install Oh My Zsh

Oh My Zsh is not really needed for making all of this work but it just makes me happy to have a pretty terminal (and there are actually all kinds of useful tools available).

Installation instructions can be found here

4. Install Powerlevel10k theme and customize it

This is another one of those things that you don’t exactly need but it sparks joy. Installation instructions are here.

Since I installed homebrew earlier, I can use:

brew install romkatv/powerlevel10k/powerlevel10k
echo "source $(brew --prefix)/opt/powerlevel10k/powerlevel10k.zsh-theme" >>~/.zshrc

5. Setting up Python

The default website for Fab Academy is built with MkDocs, which uses Python. Therefore, you will also need to get python and pip working on your computer. I’m not going to use MkDocs but I will need to use Python for some other things so better get it also up and running.

Many people say how easy Python is and how it should be the first programming language that you learn. Usually, these people are people who have programmed computers all their lives and understand the complex structures and concepts behind the simple syntax.

I am in no way a total beginner when it comes to working with technology or writing code, but I have always struggled with Python. It is really nice for some situations, but I have always felt that the easiness is more of an illusion, or it is easy if you already understand how programming and computers work. Just setting up the correct version to work properly is painful. I know I’m still going to need it, so here is my recommended way to install Python on macOS. I went with the recommendation to use pyenv to manage multiple versions of python on the same computer.

The main issues with macOS and python can be listed in a simplified way like this:

  • macOS (12.1 Monterey being the latest one as I write this) comes with Python 2.7 as the default version. You should not use 2.X for any actual work with python—but you absolutely should not try to remove it—since the OS itself needs it for something (I have never been interested enough to figure out what exactly).
  • There is also a built-in version of Python 3 in macOS, you could try to use it with python3in your terminal. It’s an older version that has some problems with the things I was trying to do so it should be updated. You could download a new version from the Python website (but don’t do it).
  • Homebrew would allow you to install a newer version of Python 3 and keep updating it (but don’t do it).

This xkcd comic explains my frustration quite well. Also one of the reasons why I wanted to format my hard drive and just start fresh.

This xkcd comic explains my frustration quite well

The best solution seems to be to use pyenv. It allows you to have multiple versions of python installed and enables an easy way to switch between them. I went through a lot of trial and error to get this to work properly as there are so many conflicting instructions online. Follow the installation instructions on Github.

Note the part that says:

Then follow the rest of the post-installation steps under Basic GitHub Checkout, starting with #2 (“Configure your shell’s environment for Pyenv”).

Here is a terminal capture of the entire process on how to do it right for Zsh on macOS. Note that I had already done this so most of the commands don’t actually do anything in this capture.

6. Install Visual Studio Code

Visual Studio Code is my preferred text editor for working with website development (and many other things). Download and install it.

Don’t forget to also install the shell command code for VS Code. The instructions are here. It allows you to easily open folders or files from the terminal in VS Code. To open a folder (like your documentation website) just navigate to your project folder using cd and type code . and Visual Studio Code will open your entire project folder.

7. List of other things to install

  • Arduino IDE (or I actually prefer to directly install Teensyduino since I use the Teensy boards all the time).
  • PlatfomIO I teach a lot using the Arduino IDE so my development environments are usually configured more for teaching than actually for my own work. This means really large font sizes and trying to stick with the most basice setup so I don’t confuse students. I have used PlatformIO a little bit but I decided to try setting it up now properly for Fab Academy as my main IDE for working with microcontrollers.

Some handy tools to install using Homebrew

  • brew update updates Homebrew, a good idea to do this before installing new things.
  • brew upgrade this upgrades all the packages you have to the latest versions.
  • brew install tree for visualizing the structure of projects directly in the terminal
  • brew install ffmpeg for video compression
  • brew install imagemagick for image compression
  • brew install asciinemafor recording terminal sessions