📘 Beginner Setup Guide

QEMU, C/C++, VS Code & Homebrew on macOS

🎓 Format: Step-by-step documentation for students

📑 Quick Navigation

✅Requirements

Before you start, make sure you have the following:

🍎 macOS (Intel or Apple Silicon)
🔐 Admin Access to your computer
📡 Stable Internet connection
⌨️ Terminal Access ready to use

🔍Check Your System

🔎 Identify Your macOS Version & CPU Type

Open your Terminal and run this command:

uname -m
💡 What this command does:
  • Shows your macOS version
  • Shows your CPU type (arm64 or x86_64)

🔎 Check If C is Already Installed

Run these commands to check:

gcc --version
clang --version
✨ If you see version details: Great! Your C compiler is installed. You can skip to the Homebrew installation section.
⚠️ If you see "command not found": Follow the Install Xcode Tools section below.

❌ Common Issues

❌ Error: "command not found"
➡️ Solution: Your Terminal may not be opened correctly. Try opening a new Terminal window and try again.

🛠️Install Xcode Tools (C/C++ Compiler)

This installs the C/C++ compiler and build tools you need.

xcode-select --install
📝 What this does:
  • Installs GCC/Clang compilers
  • Installs essential build tools
⏳ Important: Wait until the installation finishes completely. This may take a few minutes.

✔️ Verify Installation

After installation completes, run:

gcc --version
clang --version
✨ If you see version details: Xcode Tools installed successfully! 🎉

❌ Common Errors & Solutions

Solution: Run this command:

sudo xcode-select --reset

Then try the installation again.

Solution: Simply run the command again:

xcode-select --install

Sometimes it takes a moment for the popup to appear.

🍺Install Homebrew

Homebrew is a package manager that makes installing software on macOS easy!

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
💡 Tip: Copy the entire command above and paste it into your Terminal, then press Enter.

📍 Add Homebrew to PATH (Important!)

After installation, you need to add Homebrew to your system PATH. Choose the command based on your Mac type:

🔧 For Apple Silicon (M1/M2/M3):

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

🔧 For Intel Mac:

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

✔️ Verify Homebrew Installation

brew --version
✨ If you see a version number: Homebrew is ready to use! 🎉

❌ Common Errors & Solutions

Problem: Your PATH is not set correctly.

Solution: Re-run the PATH setup command for your Mac type (see above).

Solution: Run this command to fix permissions:

sudo chown -R $(whoami) /usr/local

💻Install Visual Studio Code

VS Code is a powerful code editor perfect for writing C/C++ programs.

brew install --cask visual-studio-code

🚀 Launch VS Code

After installation, you can open VS Code from Terminal:

code
💡 Tip: This command opens VS Code in your current directory.

❌ If "code" command is not found:

Follow these steps:

  1. Open VS Code manually from your Applications folder
  2. Press Cmd + Shift + P
  3. Type: Shell Command
  4. Select: Install 'code' command in PATH

❌ Common Error: "App cannot be opened"

If you see a security warning:

  1. Go to System Settings
  2. Navigate to Security & Privacy
  3. Click Allow for Visual Studio Code

🧩 Install Essential Extensions

Now you need to install two important extensions for C/C++ development:

  1. Open VS Code
  2. Click the Extensions icon in the left sidebar (looks like 4 squares)
  3. Search for and install:
    • Prettier - Code formatter (makes your code look nice)
    • C/C++ - Official extension (white and purple icon)
✨ Once installed: You're ready to write and format C/C++ code! 🎉

✏️Create Test C Program (Optional)

Let's create a simple "Hello, World!" program to test everything works:

📁 Create a Project Folder

mkdir ~/c_projects
cd ~/c_projects
touch hello.c

✍️ Edit hello.c

Open the file in VS Code and add this code:

#include <stdio.h>

int main() {
    printf("Hello, World!\\n");
    return 0;
}

🔨 Compile & Run

gcc hello.c -o hello
./hello
✨ Expected output:
Hello, World!
🎉 Congratulations! Your C compiler is working perfectly!

🖥️Install QEMU

QEMU is a virtual machine emulator that lets you run Linux on your Mac.

brew install qemu

✔️ Verify QEMU Installation

qemu-system-x86_64 --version
qemu-system-aarch64 --version
✨ If you see version numbers: QEMU is installed! 🎉

❌ Common Errors & Solutions

Don't worry! This is normal and can be safely ignored. QEMU will still work fine.

This is normal on macOS! macOS doesn't support KVM (Kernel Virtual Machine). QEMU will use HVF (Hypervisor Framework) instead, which is actually better on Apple Silicon Macs.

⚙️Setting Up QEMU (Linux VM)

🔍 Check Your Mac Type

First, determine if you have Apple Silicon or Intel:

uname -a
📝 What to look for:
  • If you see arm64 → You have Apple Silicon (M1/M2/M3)
  • Otherwise → You have an Intel Mac

📥 Download Ubuntu VM Image

Choose the download link based on your Mac type:

Click this link to download:

https://bham-my.sharepoint.com/personal/e_ritter_bham_ac_uk/_layouts/15/guestaccess.aspx?share=IQDChBPtZAjQRq6qrRZ4jHY9AVlZLe5TuHMfy-36VqJ8heg&e=13QF9O

Click this link to download:

https://bham-my.sharepoint.com/personal/e_ritter_bham_ac_uk/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fe%5Fritter%5Fbham%5Fac%5Fuk%2FDocuments%2FShared%2FOS%5FSP%2F2025%5F26%2Fubuntu24%2E04%2Eqcow2%2Ezip&parent=%2Fpersonal%2Fe%5Fritter%5Fbham%5Fac%5Fuk%2FDocuments%2FShared%2FOS%5FSP%2F2025%5F26&ga=1

📂 Organize Your Files

Navigate to your Downloads folder and organize the files:

cd ~/Downloads
mkdir vm-image
# Move the downloaded file to the vm-image folder
mv ubuntu24.04-arm64.qcow2 vm-image
cd vm-image
ls
💡 Expected result: You should see a .qcow2 file (the disk image)

📥 Download Startup Scripts

Download the startup file from this link:

https://bham-my.sharepoint.com/personal/e_ritter_bham_ac_uk/_layouts/15/onedrive.aspx?id=%2Fpersonal%2Fe%5Fritter%5Fbham%5Fac%5Fuk%2FDocuments%2FShared%2FOS%5FSP%2F2025%5F26%2Fubuntu24%2E04%2Darm64%2Eqcow2%2Ezip&parent=%2Fpersonal%2Fe%5Fritter%5Fbham%5Fac%5Fuk%2FDocuments%2FShared%2FOS%5FSP%2F2025%5F26&ga=1

📦 Extract Startup Scripts

Extract the startup scripts into your vm-image folder:

cd ~/Downloads/vm-image
unzip ~/Downloads/startupVM.zip
ls
💡 You should see files like:
  • sysprog-start-linux
  • sysprog-start-mac
  • sysprog-start-mac-arm64
  • ubuntu24.04-arm64.qcow2
  • ...and more

🔐 Make Scripts Executable (Important!)

Before running the scripts, give them permission:

chmod +x sysprog-start-*

🚀 Start the Virtual Machine

Choose the command based on your operating system:

./sysprog-start-linux
./sysprog-start-mac-arm64
./sysprog-start-mac

⏳ Wait for the VM to Boot

After running the startup script:

  1. A new QEMU window will open 🖥️
  2. Ubuntu will start booting
  3. This takes 1–2 minutes the first time
  4. When ready, you'll see a login prompt

🔑 Login to the VM

Use these credentials:

Username: bham
Password: bham

✔️ Test That It Works

After logging in, run these commands:

ls
cd helloWorldExample
make
./helloWorld
✨ Expected output:
Hello World
The value of i is 0

🌐 Optional: Connect via SSH

Instead of using the VM window, you can access it from your laptop's terminal:

ssh bham@10.187.0.2

Password: bham

💡 Benefit: You can now work inside the VM directly from your terminal!

📤 Copy Files Between Laptop & VM

📥 From Laptop → VM:

scp myfile.c bham@10.187.0.2:/home/bham/

📤 From VM → Laptop:

scp bham@10.187.0.2:/home/bham/output.txt .

⚠️Common Problems & Fixes

Solution: Make sure your startup scripts are executable:

chmod +x sysprog-start-*

Problem: You might be in the wrong directory.

Solution: Check your current location:

ls

You must see the sysprog-start-* files in your directory.

Problem: QEMU might not be installed.

Solution: Install QEMU for your system:

brew install qemu

Problem: macOS doesn't support KVM (Kernel Virtual Machine).

Solution: Use HVF (Hypervisor Framework) instead:

qemu-system-x86_64 -accel hvf -m 4G
💡 Tip: HVF is actually faster on Apple Silicon Macs!

Solution: Set the compiler path in VS Code:

  1. Press Cmd + Shift + P
  2. Type: C/C++: Edit Configurations
  3. Set the compilerPath to your GCC or Clang location

🎉 You're All Set!

Congratulations! 🎊 You've successfully set up your development environment with QEMU, C/C++, VS Code, and Homebrew on macOS. You're now ready to start programming and running Linux virtual machines!

Happy coding! 💻✨