macOS Setup Guide¶

This guide explains how to set up frontend development of the Visual Tangible Artifacts (VTA) Giraf app on macOS using an iPad simulator.

Prerequisites¶

Make sure your system meets the following requirements:

Operating System: macOS 10.15 (Catalina) or newer
Intel or Apple Silicon chips are supported
⚠️ macOS 10.14 (Mojave) and earlier are not supported — Flutter requires macOS 10.15+
Free Disk Space: ~25-30 GB may be needed for frontend development setup
Xcode: ~15 GB
Flutter SDK: ~1.5 GB
Dependencies and simulators: ~10-15 GB
Apple ID: Required for Xcode and iOS simulator downloads

Required Software Installation¶

1. Install Homebrew (Package Manager)¶

If you don't have Homebrew installed:

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

After installation, add Homebrew to your PATH (follow the instructions shown after installation).

2. Install Git¶

brew install git

Verify installation:

git --version

3. Install Xcode¶

Open the App Store
Search for Xcode and install it (this will take a while - ~15 GB download)
Open Xcode and accept the license agreements
Install additional components when prompted

Alternatively, install via command line:

xcode-select --install

4. Install Flutter SDK¶

Option A: Using Homebrew¶

brew install flutter

Option B: Manual Installation (Recommended)¶

Download Flutter from: https://docs.flutter.dev/get-started/install/macos/mobile-ios
Extract to desired location (e.g., ~/development/flutter)
Add Flutter to your PATH in ~/.zshrc or ~/.bash_profile:

export PATH="$PATH:$HOME/development/flutter/bin"

Reload your terminal or run:

source ~/.zshrc

5. Install CocoaPods¶

CocoaPods is required for iOS dependencies:

sudo gem install cocoapods

If you encounter Ruby version issues:

brew install ruby
gem install cocoapods

Setup Steps¶

Step 1: Clone the Repository¶

Open Terminal and navigate to your desired directory:

git clone https://github.com/aau-giraf/visual-tangible-artefacts.git
cd visual-tangible-artefacts

Step 2: Verify Flutter Installation¶

Run Flutter doctor to check for any issues:

flutter doctor

Step 3: Set Up iOS Simulator¶

3.1 Check Available iOS Runtimes¶

xcrun simctl list runtimes | grep iOS

This will show available iOS versions, e.g.:

iOS 17.5 (17.5 - 21F79) - com.apple.CoreSimulator.SimRuntime.iOS-17-5
iOS 18.1 (18.1 - 22B83) - com.apple.CoreSimulator.SimRuntime.iOS-18-1

3.2 Create iPad Simulator¶

Use the latest iOS runtime from step 3.1:

xcrun simctl create "VTA iPad Pro" "com.apple.CoreSimulator.SimDeviceType.iPad-Pro-13-inch-M4" "com.apple.CoreSimulator.SimRuntime.iOS-18-1"

This command returns a device UUID, e.g.: A1B2C3D4-E5F6-7890-ABCD-EF1234567890

3.3 Verify Simulator Creation¶

xcrun simctl list devices | grep "VTA iPad Pro"

Step 4: Set Up Flutter Project¶

Navigate to the Flutter app directory:

cd Frontend/vta_app

Get Flutter dependencies:

flutter pub get

For iOS-specific setup:

cd ios
pod install
cd ..

Step 5: Install .NET 8.0 SDK¶

Option A: Install using Homebrew¶

brew install dotnet@8

Option B: Manual Installation¶

Download the .NET 8.0 SDK installer from https://dotnet.microsoft.com/en-us/download/dotnet/8.0
Run the installer and follow the prompts to complete the installation.

Running the Flutter App¶

Start the iPad simulator:

xcrun simctl boot "VTA iPad Pro"

Open Simulator app:

open -a Simulator

From Frontend/vta_app, run the Flutter app:

flutter run

Troubleshooting¶

Common Issues¶

Flutter Doctor Issues¶

Xcode not found: Ensure Xcode is installed and run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
CocoaPods not installed: Run sudo gem install cocoapods
iOS toolchain issues: Open Xcode and accept the license agreements, or run sudo xcodebuild -license accept

iOS Simulator Issues¶

Simulator not starting: Try xcrun simctl erase all to reset simulators
App not installing: Clean Flutter build with flutter clean && flutter pub get

Build Issues¶

iOS build failures: Try cd ios && pod install && cd .. from the Flutter app directory
Certificate issues: Ensure you're signed into Xcode with an Apple ID

Last update: October 27, 2025