Skip to main content Link Search Menu Expand Document (external link)
ITP 380

Theme: auto

Setup for Mac

This is the setup guide for Mac. If you’re using a PC, go to here instead!

System Requirements

In general, any Mac made within the last four years will be perfectly fine for this course. The code works natively on both older Intel Macs and the newer M1 Macs.

However, you do need to be running macOS 11 or higher (eg. you need one of these: 11 “Big Sur”, 12 “Monterey”, or 13 “Ventura”). If you have a version older than 11, you will need to first update your macOS version through the App Store.

Using Alternate IDEs

We recommend using Visual Studio Code, and it’s the only Mac IDE we officially support in the class. While other IDEs (such as Xcode or CLion) may work, we won’t be able to help if you have issues with it.

Homebrew and CMake

In this class, we use the CMake build system, which requires some setup on the command line before you can start working in Visual Studio Code.

If you have an M1 Mac and previously setup your Terminal to run in Rosetta (Intel compatibility mode) for another class, make sure for this class you instead use a native instance of Terminal. If you run your Terminal through Rosetta, Homebrew will think you have an Intel processor and won’t install the native M1 tools that you’ll want for this class. You can confirm your Terminal on an M1 is native if you run uname -m and the output says arm64.

  1. Open up a Terminal.

  2. Make sure you have the Xcode command-line tools installed (you need these even though we’re using Visual Studio Code) by typing:

    xcode-select --install

    You’ll either get a message that the tools are already installed or, if not, it will install the tools.

  3. Next, install Homebrew: https://brew.sh/

  4. If you have an M1 Mac, Homebrew will tell you that you have to add /opt/homebrew/bin to your PATH for it to work properly. Type the exact instructions it specifies.

  5. Next, run the following command to install CMake and Ninja through Homebrew:

    brew install cmake ninja

    Note: If you have previously installed Homebrew and CMake, you may need to brew upgrade cmake to make sure you have the latest version.

(Supplemental) Git/GitHub Basics

Most students have used Git and GitHub prior to this course. If you are familiar enough with GitHub, you can skip this video. However, if you’ve never used Git and GitHub before, this video covers the basics:

Git and GitHub

We use Git and GitHub for all the labs. The TAs will only grade lab submissions on GitHub!

Here are the steps to getting setup on GitHub:

  1. If you do not have a GitHub account, first you should create one (https://github.com/)
  2. Next, you need to accept the GitHub classroom assignment: https://classroom.github.com/a/mGIbcJnm
  3. Select your USC email from the list. If you do not see your email address listed, that’s okay, just “skip” this step for now.
  4. Once you accept the assignment, GitHub will create a repository for you with a URL like this: https://github.com/itp380-20243/labs-YourUsername. It should automatically redirect you to your repository page once created.
  5. Now you will need a Git client that will allow you to clone the code to your local computer, and then later push your changes to the GitHub server. Here are some choices (you only need to pick one):
    • If you’re new to Git, and you want a simple UI, you can use GitHub Desktop: https://desktop.github.com/
    • If you like command line interfaces, you can use the Git on Terminal, as it’s installed by default. (Note: If you use a command-line interface, to use https to clone/push to GitHub, you should setup Git Credential Manager to simplify the authentication process.)
    • You can clone, commit, and sync (which does a push) directly inside Visual Studio Code, if you prefer.

Cloning Your Repo

The “clone” of a repo is the local copy of the code that’s on GitHub. You generally work in the clone and then can upload any changes to GitHub.

Because macOS protects certain folders, it’s recommended to clone your repository to your user’s home folder (or ~ if you’re doing it from terminal). If you clone to Desktop or Documents, every time you try to run your game you will get an annoying popup asking for permission to access the folders.

  1. Now on the webpage for your GitHub repo, click the green “Clone or download” button: Clone button in GitHub

    • If you’ve installed GitHub Desktop, you can click the “Open in Desktop” button and it should automatically open the program and ask where you want to clone your repository.

    • If you’re using the command line, this should just be:

       git clone https://github.com/itp380-20243/labs-YourUserName.git

    • Otherwise, you need to copy the URL in this dropdown and use it to clone in your preferred program.

    • (If you previously setup SSH for GitHub, you can use that instead, though in my experience that ends up being more finnicky than using HTTPS).

  2. Now you should have your starting repository files on your local computer.

Visual Studio Code Setup

Visual Studio Code is the most popular C++ IDE for Mac, so it is recommended for most students. If you really want to use something else, it is possible to do so, but we may not be able to provide support if you encounter issues.

  1. Download and install Visual Studio Code (steps 1-4 here). If you’ve previously installed Visual Studio Code on your Mac, you should launch it and make sure it’s up-to-date.
  2. Inside Visual Studio Code, you’ll need to install some extensions for it to work properly with CMake and C++. Go to View>Extensions and search for and install all of the following: Extensions to install
  3. You will need to quit and reopen Visual Studio Code after installing these extensions.

Visual Studio Code Settings

While the default settings for Visual Studio Code and its extensions are fine, we do want to make one change to the CMake extension so that it shows shortcuts on the status bar at the bottom of the window. To change this:

  1. Go to Code>Settings…>Settings (or press ⌘ ,): Getting to the settings menu
  2. In the settings menu search bar, type “cmake status” and set this “Status Bar Visibility” option to either “compact” or “visible”: Status Bar Visibility setting

Working in Visual Studio Code

  1. After relaunching Visual Studio Code, you’ll want to open the root folder for your repo. To do this, go to File>Open Folder… and browse to your labs-YourUserName folder on your computer to open it.

  2. Visual Studio Code will automatically detect that this is a CMake project and should select the proper Clang compiler by default.

    Alternatively, Visual Studio Code may show you a dropdown like this: Select kit

    You should select the newest version of Clang listed in the dropdown (13.1.6 in this example).

    You will know it is correct if you look at the bottom toolbar:

    Bottom toolbar in VS Code

    If the bottom toolbar does not say Clang (and instead says GCC), click on the compiler name to bring up the dropdown and select Clang from there as GCC DOES NOT work properly.

  3. Next, on the bottom toolbar find where it says [all] and click on it to change the target to [Lab01]. Visual Studio Code may automatically show [Lab01] to the right of the play button, if shows a different lab, change it to [Lab01]. Otherwise, it will ask you once you press the bug button in step 5:

    Lab01 selected

  4. Next, click the Build button on the toolbar to compile your code.

  5. Finally, to run the game, click the bug button on the toolbar that’s to the left of the play button: Play button If [Lab01] isn’t already selected, you’ll see a dropdown asking for which lab you want to launch.

Clicking the play button does not allow you to debug your code. For example, breakpoints will not work and if your program crashes, you won’t get any helpful information about the crash. Make sure you always run with the bug button and NOT with the play button!

Using GitHub

From here, you will want to test pushing and viewing your build results on GitHub, which is outlined on the page here.