using-tuist-generated-projects

What this skill does

# Using Tuist Generated Projects

## Quick Start

```bash
# Generate workspace without opening Xcode
tuist generate --no-open

# Build a scheme with xcodebuild
xcodebuild build -workspace App.xcworkspace -scheme App

# Run tests with xcodebuild
xcodebuild test -workspace App.xcworkspace -scheme AppTests -only-testing AppTests/MyTestCase
```

## Project definition

### Prefer buildable folders

Use `buildableFolders` instead of `sources` and `resources` globs. Buildable folders stay synchronized with the file system, so adding or removing files does not require regeneration.

```swift
let target = Target(
  name: "App",
  buildableFolders: [
    "App/Sources",
    "App/Resources",
  ]
)
```

### Tag targets for focus

Use target tags to group areas of the project, for example:

- `tag:team:*`
- `tag:feature:*`
- `tag:layer:*`

These tags make it easier to scope generation and testing later.

Example target metadata with tags:

```swift
let target = Target(
  name: "PaymentsUI",
  metadata: .metadata(tags: [
    "tag:team:commerce",
    "tag:feature:payments",
    "tag:layer:ui",
  ])
)
```

When working on a focused area, generate only what you need:

```bash
tuist generate tag:feature:payments
tuist generate PaymentsUI PaymentsTests
```

### Align build configurations

Keep build configurations aligned between the project and external dependencies. Use `PackageSettings(settings: .settings(configurations: []))` to mirror project configurations; mismatches emit warnings.

## Workflows

### Generate intentionally

- Use `tuist generate --no-open` in automation and scripts to avoid launching Xcode.
- Regenerate when any manifest changes (or the dependency graph changes).
- If generation fails due to missing products, run `tuist install` to resolve dependencies and retry.

### Build with xcodebuild

Use `xcodebuild build` against the generated workspace and scheme.

```bash
xcodebuild build \
  -workspace App.xcworkspace \
  -scheme App \
  -destination "generic/platform=iOS Simulator"
```

### Test with xcodebuild

Use `xcodebuild test` for running tests locally. Prefer it over `tuist test` because `tuist test` regenerates the project on each invocation, which slows down iteration.

To optimize test run time:

- **Use `--only-testing`** to run only the specific test suite or test case you are working on, instead of the full target.
- **Pick the scheme with the fewest compilation targets** that still includes the test target you need. This minimizes build time before tests run.

```bash
# Run a specific test suite
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite

# Run a single test case
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite/testMyFunction
```

## Guidelines

- Keep `buildableFolders` paths aligned to the target's real file system layout.
- Avoid overlapping `buildableFolders` with `sources` or `resources` globs in the same target.
- Open Xcode manually when needed after running `tuist generate --no-open`.

## Troubleshooting

**Static side effects warnings:** adjust product types deliberately. Use `Target.product` for local targets and `PackageSettings(productTypes:)` for external products. Making everything dynamic with `.framework` can compile and run, but it may hurt launch time. Prefer static products (static frameworks or libraries) when possible and when they do not introduce side effects.

**Objective-C dependency crashes:** add `-ObjC` or `-force_load` via `OTHER_LDFLAGS` on consuming targets as needed. Reference: `https://tuist.dev/en/docs/guides/features/projects/dependencies#objectivec-dependencies`.