Frequently asked questions

ask("Why should I use tuist?")

When Xcode projects and teams grow, the maintenance becomes cumbersome, and developers spend quite a lot of time fighting issues. Some example of those issues are compilation failing because frameworks are not found, the linker complaining because the framework we are linking against is incompatible. tuist helps you overcome most of those issues by abstracting you away from certain knowledge that Xcode expects your developers to have. With tuist, your developers can be focused on building the app, rather than setting up the environment and project properly to get Xcode happy about it.

ask("What if tuist is not supported in the future?")

Not supporting tuist in the future is as likely as Facebook not supporting React. Many things can happen and we can’t make sure tuist exists forever. For that reason, we have designed tuist API in such way that your projects depend weakly on it. Your team is responsible for defining how the project should look, and tuist takes that input, and generates an Xcode project that follows standard conventions. In case of tuist not being maintained anymore, the generated project is a valid and standard project, which you can include in the git repository.

ask("How does tuist overlap with spm?")

Swift Package Manager (spm) is the official tool from Apple for managing Swift packages. Although spm and tuist have a similar design, their goal is different. The Swift Package Manager aims to facilitate the definition and usage of Swift packages, while tuist facilitates the definition of projects (e.g. iOS apps projects) and the interactions with them. Developers continue to ask Apple for some integration with existing Xcode projects so you might expect some overlapping in the future.

ask("Can I use it with Fastlane?")

Definitively. Although tuist provides CLI commands such as a build and test, you can use Fastlane’s gym and scan actions, or your own automation logic. You can work with the project that tuist generates as if it was a project generated by Xcode, nothing changes.

ask("Why are the manifests in Swift?")

First and foremost, because the manifest files like Project.swift or Workspace.swift can be edited with Xcode, which helps the developers validate the syntax using the Swift type system. It also prevents developers from tweaking tuist in any way. This might change in the future, and there’ll be support for hooks where developers will have the flexibility to define custom actions.

ask("Can my targets depend on external dependencies?")

They can, but there’s no dependency management built in tuist. Depending on how your project manages external dependencies, the integration process changes:

  • Carthage: Since it generates precompiled framework, you can set your target up to depend on that framework. tuist will set up the build settings and build phases for you.
  • CocoaPods: The project manifest model doesn’t support adding a CocoaPods dependency but you can call pod install after the project has been generated with tuist. We have plans to improve this having support for it from the manifest.
  • Swift Package Manager: Unfortunately, there’s no support for integrating your projects with spm dependencies. We are waiting for Apple to do some work on that area to add the integration into tuist.

ask("Should I check the Xcode projects into source control?")

Whether or not you check in your projects is up to you, as workflows vary from project to project. We recommend that you keep the projects under source control, and don’t add it to your .gitignore. But ultimately this decision is up to you:

Benefits of checking in the projects

  • After cloning the repo, the project can immediately build and run, even without having Tuist installed on the machine.
  • The projects are guaranteed to be identical to those in the original installation after cloning the repo.

Benefits of ignoring the projects

  • There won’t be any conflicts to deal with when performing source control operations, such as merging branches with different Pod versions.

ask("Why aren't all Xcode project features available?")

That’s on purpose. We could have exposed things like schemes, or the link frameworks build phase. However, we’d be offering an alternative syntax for defining Xcode projects, and that’s not the goal of Tuist. We aim to provide a simple, convenient and scalable interface that abstracts from the implementation details. Whether you need to create a scheme to test a target, or add a copy frameworks build phase to embed your transitive dependencies. That’s something you shouldn’t have to worry about.

This approach might sound restrictive at first, but it allows us to have more control over the generated project, validate your input and generate an output that we feel confident about. We’d feel bad if we give you a project that doesn’t compile and you need to spend time figuring out what’s wrong.

If you’d like a more granular approach you can check out a tool like XcodeGen.

ask("I love this project, how can I contribute?")

You are welcome to contribute. Contributors bring fresh ideas and new points of view to the project. Here are some examples of contributions:

  • Open an issue: It can be an idea, a bug that you have found. Don’t hesitate to do so. For instance, you can easily do it from tuist by running tuist create-issue. It’ll open the browser with the issue form to fill it out.
  • Open a PR: If you’d like to get your hands dirty, pick an issue and work on it. Issues for beginners are labelled on GitHub and can be a good starting point to get familiar with the project. After your first contribution gets merged you’ll become part of the contributors team.
  • Write content: If you like writing, you can also help writing blog posts or documentation for this website.

Got improvements? Help improve this document via sending PRs.