Environment setup

Scenario. You are 30 minutes from writing your first line of Swift. This chapter installs every tool you need for the entire book — Xcode, Homebrew, Git, mdBook (so you can read this book offline and search it instantly), Fastlane, and your Apple ID. We do it once, properly, and never have to think about it again.

Total time: 30–60 minutes, mostly waiting for downloads.

Step 1 — Install Xcode

Xcode is Apple’s IDE. It includes the Swift compiler, the iOS/macOS SDKs, the simulator, Interface Builder, the debugger, and the build system.

  1. Open the App Store app on your Mac.

  2. Search for Xcode. Install. (~12 GB; expect 20–60 minutes.)

  3. Once installed, open Xcode at least once. Accept the license. Let it finish installing additional components.

  4. Open Terminal (Cmd+Space → “Terminal”).

  5. Run:

    xcode-select --install

    This installs the Command Line Tools (a smaller, separate package that includes git, clang, make, swift, etc.). If it says they are already installed, you are good.

  6. Verify:

    xcodebuild -version
swift --version
git --version

    You should see Xcode 16.x, Swift 6.x, and Git 2.x.

[!TIP] Best practice. Do not use App Store auto-updates for Xcode for the rest of your iOS career. Manage Xcode versions deliberately with xcodes (we install it in Step 4). Auto-updating Xcode in the middle of a project is how teams lose a day.

[!WARNING] Gotcha. If xcodebuild -version fails with xcode-select: error: tool 'xcodebuild' requires Xcode, run:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Step 2 — Install Homebrew

Homebrew is the de-facto package manager for macOS. We will use it for every non-Apple tool.

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

After installation, follow the on-screen instructions to add Homebrew to your shell PATH. On Apple Silicon Macs, that usually means running the two echo ... >> ~/.zprofile lines the installer prints.

Verify:

brew --version

Step 3 — Install the book toolchain

brew install mdbook gh
  • mdbook — the static site generator this book is built with. Lets you build and read this book locally with full search.
  • gh — the GitHub CLI. Used in later phases for CI workflows and PR automation.

Verify:

mdbook --version
gh --version

Step 4 — Install xcodes (Xcode version manager)

You will install multiple Xcode versions over the course of your career. xcodes makes this painless.

brew install xcodesorg/made/xcodes

Verify:

xcodes installed

It should list at least the Xcode you installed in Step 1. We will use xcodes in depth in Phase 2.

Step 5 — Install Fastlane

Fastlane automates code signing, screenshots, App Store uploads, and TestFlight. You will need it from Phase 10 onward — but installing it now avoids a side-quest later.

brew install fastlane

Verify:

fastlane --version

[!NOTE] Context. Fastlane has two install paths: Homebrew (above) and RubyGems (gem install fastlane). Homebrew is simpler and isolates Fastlane’s Ruby from your system Ruby. Use it unless your team standardizes on Bundler-managed Ruby.

Step 6 — Configure Git

If you have not used Git before on this Mac:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase true

Generate an SSH key for GitHub (we will use this in Phase 10’s CI setup):

ssh-keygen -t ed25519 -C "you@example.com"
# Press Enter to accept default file location and an empty passphrase, or set a passphrase.
cat ~/.ssh/id_ed25519.pub | pbcopy

The public key is now in your clipboard. Add it at github.com/settings/keys → New SSH key.

Authenticate the GitHub CLI:

gh auth login

Choose GitHub.com → SSH → use the key you just added.

Step 7 — Clone (or fork) this book

mkdir -p ~/src
cd ~/src
gh repo clone <your-username>/swift-ios-macos-engineer
# OR, if you are reading the published version, fork it first then clone your fork.
cd swift-ios-macos-engineer

Build and serve the book locally:

mdbook serve book --open

Your browser should open at http://localhost:3000 showing this book. Edits to any Markdown file in book/src/ will live-reload.

[!TIP] Best practice. Keep mdbook serve running in a Terminal tab while you read. When you make notes (and you will), edit the Markdown directly — your notes become permanent part of your local copy.

Step 8 — Sign in to your Apple ID in Xcode

This step is free and does not require a paid developer account. It lets you run apps on your own physical device for 7-day signed builds.

  1. Open Xcode.
  2. Xcode → Settings → Accounts → + (bottom left) → Apple ID.
  3. Sign in with your Apple ID. Use a personal one for learning; do not use a work one yet.
  4. Once added, you will see your “Personal Team” listed.

That is enough for Phases 0–9. The paid Apple Developer Program ($99/year) is required only for:

  • App Store distribution
  • TestFlight
  • Push notifications on physical devices
  • Certain entitlements (CloudKit, HealthKit, etc.) on physical devices

We will set that up at the start of Phase 10.

Step 9 — Verify the full stack

Run this one-shot sanity check:

echo "=== System ===" \
  && sw_vers \
  && echo "\n=== Xcode ===" \
  && xcodebuild -version \
  && echo "\n=== Swift ===" \
  && swift --version \
  && echo "\n=== Git ===" \
  && git --version \
  && echo "\n=== Homebrew ===" \
  && brew --version | head -1 \
  && echo "\n=== mdBook ===" \
  && mdbook --version \
  && echo "\n=== xcodes ===" \
  && xcodes --version \
  && echo "\n=== Fastlane ===" \
  && fastlane --version | head -1 \
  && echo "\n=== gh ===" \
  && gh --version | head -1 \
  && echo "\n✅ Environment ready."

If every line prints a version and the last line is ✅ Environment ready., you are done.

Troubleshooting

Xcode took 60+ minutes to download. Normal on slow connections. The App Store will resume if you close it.

xcode-select --install says “Can’t install the software because it is not currently available from the Software Update server.” Means Command Line Tools are already installed. Continue.

brew install fails with “permission denied”. Do not sudo. Instead, fix Homebrew permissions per the message — usually sudo chown -R $(whoami) $(brew --prefix)/*.

mdbook serve says “port 3000 already in use”. Another instance is running. Either find it (lsof -i :3000) and kill it, or run on a different port: mdbook serve book --port 4000 --open.

Xcode Simulator does not open. Open it manually once via Xcode → Open Developer Tool → Simulator — the first launch finalizes setup.

Lab Preview

The last chapter of Phase 0, Staying current with Apple, is a 10-minute read on how to keep your knowledge sharp once the book is done. After that, you are into Phase 1 and writing real Swift.