Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.
mise exec tuist@latest -- tuist generate against a reproduction project.Ask the user for:
tuist generate)Project.swift and content (or relevant excerpts)Tuist.swifttuist version)The answer to "when" determines the verification strategy:
tuist generate.xcodebuild build after generation.Before investigating the source code, confirm the issue is not already fixed in the latest release.
REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"
Create minimal Tuist.swift, Project.swift, and source files that reproduce the user's scenario. Keep it as small as possible while still triggering the issue.
mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"
If the issue involves dependencies, install them first:
mise exec tuist@latest -- tuist install --path "$REPRO_DIR"
Clone the repository and build the tuist executable and ProjectDescription library from source to test against the latest code on main.
TUIST_SRC=$(mktemp -d)
git clone --depth 1 https://github.com/tuist/tuist.git "$TUIST_SRC"
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
The built binary will be at .build/debug/tuist. Use it to test the reproduction project:
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
Tell the user the fix is already on main, and it hasn't been released, tell them it'll be in the nest release and point them to the relevant commit if you can identify it.
Continue to Step 4.
Investigate the Tuist source code to understand why the issue occurs.
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
cd "$REPRO_DIR" && cd ..
zip -r reproduction.zip "$(basename "$REPRO_DIR")" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*'
Tell the user what is wrong and how to fix it. Common misconfigurations:
tuist install before tuist generate when using external dependencies-ObjC linker flag for Objective-C dependenciessources and resources globs together with buildableFoldersProvide the corrected manifest snippet so the user can apply the fix directly.
If you cannot determine whether it is a bug or misconfiguration, recommend the user:
Provide a summary of what you investigated and what you ruled out, so the user does not have to repeat the triage.
When testing a fix, always verify the full cycle:
# Build the patched tuist
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry
# Install dependencies if needed
"$TUIST_SRC/.build/debug/tuist" install --path "$REPRO_DIR"
# Generate the project
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
# Build the generated project
xcodebuild build \
-workspace "$REPRO_DIR"/*.xcworkspace \
-scheme <scheme> \
-destination "platform=iOS Simulator,name=iPhone 16 Pro"
When the user reports a runtime issue (crash on launch, missing resources at runtime, wrong bundle structure, or unexpected behavior), you must go beyond building and actually launch the app on a simulator.
# Boot a simulator
xcrun simctl boot "iPhone 16 Pro" 2>/dev/null || true
# Build for the simulator
xcodebuild build \
-workspace "$REPRO_DIR"/*.xcworkspace \
-scheme <scheme> \
-destination "platform=iOS Simulator,name=iPhone 16 Pro" \
-derivedDataPath "$REPRO_DIR/DerivedData"
# Install the app
xcrun simctl install booted "$REPRO_DIR/DerivedData/Build/Products/Debug-iphonesimulator/<AppName>.app"
# Launch and monitor — this will print crash info if the app terminates abnormally
xcrun simctl launch --console-pty booted <bundle-identifier>
The --console-pty flag streams the app's stdout/stderr so you can observe logs and crash output directly. Watch for:
-ObjC linker flag missing)If the app crashes without useful console output, pull the crash log:
# List recent crash logs for the app
find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -newer "$REPRO_DIR" -print
Read the crash log to identify the crashing thread and the faulting symbol.