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
.gitignore as well.
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
To start with Tuist, let’s create a Hello World project
➜ mkdir hello ➜ cd hello
We can bootstrap a tuist project by running
➜ 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
Tuist uses some manifest file such as
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
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.
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.