Skip to content

canvas-toolchain-setup.html

Setting Up Your C++ Toolchain on macOS

Install Homebrew, then GCC 15, then set up debugging in VS Code with LLDB. Work through the steps in order. Open the Terminal app (Applications → Utilities → Terminal, or find it with Spotlight) and type each command, pressing Return after each one. You need an administrator account and an internet connection.

Step 1: Install Homebrew

Homebrew is the package manager you will use to install the compiler. Run this single command:

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

You will be asked for your Mac login password (the screen stays blank as you type, which is normal) and to press Return to continue. The installer may ask to install the Xcode Command Line Tools. Let it. This takes several minutes.

Step 2: Add Homebrew to your PATH

Find out which Mac you have:

uname -m

If it prints arm64, you have an Apple Silicon Mac (M1/M2/M3/M4). If it prints x86_64, you have an older Intel Mac.

On Apple Silicon, run these two commands:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

On Intel, Homebrew is usually already on your PATH. If the brew command is not found after reopening Terminal, run:

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

Confirm it works:

brew --version

Step 3: Install GCC 15

Install the compiler:

brew install gcc@15

Important: On macOS, the plain commands gcc and g++ are not the GNU compiler; they point to Apple's Clang. To use the compiler you just installed, call it by its versioned name: gcc-15 for C and g++-15 for C++.

Verify the install (it should report a version starting with 15):

g++-15 --version

To compile and run a program:

g++-15 -std=c++23 -Wall -g hello.cpp -o hello
./hello

Step 4: Set Up Debugging in VS Code with LLDB

macOS already ships with LLDB, a debugger that works natively on every Mac with no extra setup. To debug from inside VS Code, do not use the Microsoft C/C++ extension's built-in debugger; on macOS it can freeze and consume large amounts of memory. Use the CodeLLDB extension instead, which bundles its own LLDB and works on both Apple Silicon and Intel.

In VS Code, install two extensions from the Extensions panel:

In your project folder, create a folder named .vscode containing the two files below.

File .vscode/tasks.json (compiles your code with debug symbols):

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-debug",
      "type": "shell",
      "command": "g++-15",
      "args": [
        "-std=c++23", "-Wall", "-g",
        "${file}",
        "-o", "${fileDirname}/${fileBasenameNoExtension}"
      ],
      "group": { "kind": "build", "isDefault": true }
    }
  ]
}

File .vscode/launch.json (builds, then launches the debugger):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug (lldb)",
      "type": "lldb",
      "request": "launch",
      "program": "${fileDirname}/${fileBasenameNoExtension}",
      "args": [],
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "build-debug"
    }
  ]
}

Open a .cpp file, click in the left margin to set a breakpoint, and press F5. VS Code will compile your file with g++-15 -g and then launch it under LLDB, stopping at your breakpoint.