What is Tuist?

Bootstrap, maintain, and interact with Xcode projects at any scale

Tuist is a command line tool (CLI) that aims to facilitate the generation, maintenance, and interaction with Xcode projects.

The most popular practical use-case is to replace Xcode workspace/project files (.xcworkspace/.xcproject) as the source of truth for your Xcode projects.

.xcworkspace/.xcproject files are supposed to be managed by Xcode since it’s hard to manipulate them manually given that their internal structures are very complicated.

Tuist abstracts those .xcworkspace/.xcproject files by using Swift files to define project structures, and then Tuist CLI will generate .xcworkspace/.xcproject files based on the definitions in the Swift files.

The goal of Tuist is to expose the whole internal structure of a Xcode’s project to developers so that they can manage, manipulate, and do cool things with the knowledge without messing around with Xcode’s project files.

At the end of the day, by using tuist, we can add .xcodeproject and .xcworkspace into .gitignore as well.

Installation

The official way to install Tuist is using the following the official Get started tutorial:

➜ ~ curl -Ls https://install.tuist.io | bash
==> Downloading tuistenv...
==> Unzipping tuistenv...
==> Installing tuistenv...
Password:
==> tuistenv installed. Try running 'tuist'
==> Check out the documentation at https://docs.tuist.io/

We can also download the Tuist binary directly from Github releases. This is suitable for installing Tuist on CI such as Github Action, since the standard way to install Tuist above requires users to enter the root password.

curl -versbose -L -o ./tuist.zip https://github.com/tuist/tuist/releases/download/2.7.2/tuist.zip
unzip ./tuist.zip -d .tuist-bin

HelloWorld Project

To start with Tuist, let’s create a Hello World project

➜ mkdir hello
➜ cd hello

Bootstrap tuist

We can bootstrap a tuist project by running tuist init:

➜ hello tuist init
Project generated at path /Users/binhan.tran/Desktop/Temp/hello.
➜ hello tree .
.
├── Project.swift
├── Targets
│  ├── Hello
│  │  ├── Resources
│  │  │  └── LaunchScreen.storyboard
│  │  ├── Sources
│  │  │  └── AppDelegate.swift
│  │  └── Tests
│  │  └── AppTests.swift
│  ├── HelloKit
│  │  ├── Sources
│  │  │  └── HelloKit.swift
│  │  └── Tests
│  │  └── HelloKitTests.swift
│  └── HelloUI
│  ├── Sources
│  │  └── HelloUI.swift
│  └── Tests
│  └── HelloUITests.swift
└── Tuist
 ├── Config.swift
 └── ProjectDescriptionHelpers
 └── Project+Templates.swift

Edit manifests

Tuist uses some manifest file such as Project.swift, Workspace.swift and rely on file system folder structures to define the project.

Tuist makes it very convenient to edit the manifest files by generating a special project environment for these manifest files, so that we can verify if our changes are valid, by checking if the project is compilable.

You can generate such a manifest project by running tuist edit from the root folder.

➜ hello tuist edit
Generating workspace Manifests.xcworkspace
Generating project Manifests
Opening Xcode to edit the project. Press CTRL + C once you are done editing

Regenerate project files

Whenever you finish any editing to the manifest files, you can easily recreate the xcworkspace/xcodeproj files by running tuist generate command

➜ hello tuist generate
Generating workspace Hello.xcworkspace
Generating project Hello
Project generated.
Total time taken: 3.193s
➜ hello 

A convenient command tuist generate -O wil generate new project files and open the generated in Xcode directly.

Conclusion

It happens very often to many iOS developers working in a big team that they have to deal with merge conflicts with the Xcode project/workspace files, which are not easy to fix.

Many tools such as XcodeGen, Tuist, xcake or struct try to fix this problem by defining structure in some configuration files and use them as the source of truth for the project’s structure. CLI tools will generate the coressponding xcworkspace/xcodeproj files that can be consumed by Xcode to manage project. All changes of projects will be done in the configuration files instead of Xcode’s project files.

Tuist has advantages in comparison to other tools since the configuration files are in Swift, which makes it easier for Swift devleoper to manage. With extensive toolings, Tuist can verify the correctness of the configuration files, as well as do some verification for the dependencies.

We will explore some advanced features of Tuist in the next articles.