Xcodegen — First Steps🚶‍♀️

It’s Monday morning, a sunny and wonderful day. You wake up with all your energy and happiness, turn on your computer, make yourself a nice ☕️, and decide to update your code with the latest features that your team has included in the main branch of the project before continuing with your work. And suddenly 😱… you read the message you don’t want to see in Git… conflicts in the file MyProject.xcodeproj.

And the drama begins! It looks like it will be a challenging day in the office.

Today, we want to discuss one of those tools that have been available for some time but still remain relatively unknown. These tools are specifically designed to solve problems like the ones we are facing and make our lives easier. Let’s talk about xcodegen.

What is xcodegen?

It’s a command-line tool with a straightforward purpose in mind: to simplify the usage, definition, and properties of our Xcode projects, thereby avoiding git conflicts and dealing with a non-human-readable file like the xcodeproj. If you have experience with Android, you can relate the idea to how the project is updated and autogenerated every time a file is created, deleted, or its location is changed.

However, that’s not its only utility — there are many more! Let’s continue reading.

How xcodegen works?

xcodegen is a yaml based command-line interpreter that includes all the necessary features or definitions needed and makes them available in the generated xcodeproj file. Here are some examples of configurations that we could use:

• Folder specification (where the code will be read from)
• Folder destination specification (where the code will be placed)
• Third-party dependencies (native frameworks, custom frameworks, use of Swift Package Manager also known as SPM or Carthage …)
• Targets (libraries, tests, plugins, …)
• Built Variants (debug, staging, production …)
• Project properties customization (version code, Swift version, …)
• … and much more!

Let’s see an example!

For a better understanding of how xcodegen works let’s build an easy example. The expected result cover the following features:

• Our project will be based in SwiftUI only.
• All project dependencies will be include using Swift Package Manager (Alamofire, Lottie and Factory).
• The project will have one target that we will call Core. This Core includes images, colors, some dummy classes and a linked targets for unit testings purposes.
• The project will have one application target with some dependencies including Core.

With this specification in mind, let’s build our yaml file. Inside this yaml we will explain how each key works, step-by-step.

Note: You could find the xcodegen command line installation guide in this link.

When our specification is finish, open a terminal, navigate where your yaml file is located and write:

$> xcodegen

to build let xcodegen create its magic. The following commands are available for generating too:

$> xcodegen generate

$> xcodegen -s project.yml

If everything is correct, this command will build an xcodeproj file that you can open, as shown in this picture:

Example autogenerated xcodeproj file using xcodegen

As we defined in the yaml file, we have:

• An app folder with the defined resources.
• A core folder with its code and the unit tests.

Likewise, the targets:

• ILoveXcodegenApp, Core and Core_Tests.

are generated too:

Autogenerated targets

With this, we could open our .gitignore file and write this:

# Xcode
*.xcodeproj

And you will become a very (very) happy developer! 😊

and … that’s all in this first steps article with xcodegen! 🎉 Good work!

Remember that this is only the begining. There are more possibilities:

• Changing the folder structure, both in the origin and the generation, can be easily achieved by adjusting the YAML specifications.
• Moving files inside the project won’t alter any tracked project file, only the file itself.
• You can add properties to a plist, create xconfig files, edit configurations, and perform various other actions, all within the yaml.
• Managing third-party dependencies between SPM and Carthage becomes incredibly easy.

and much more!

What are the advantages?

The advantages of using xcodegen are numerous:

1. Eliminates git conflicts in project files: Since the project settings are managed through the YAML file, conflicts in project files become a thing of the past.
2. Legible project file updates: All edits and updates to the project file are now clear and organized within the YAML file, making it easier to understand and maintain.
3. Reusable project templates: You can create templates for your projects and reuse them whenever needed, streamlining project setup and reducing repetitive tasks.
4. Efficient for multi-application projects: For multi-application projects sharing the same codebase but with slight variations (e.g., different localizables or icons), xcodegen is a great option. Adding a new application is as simple as using your application template in the YAML and customizing it with specific icons, colors, or localizations.
5. Simplifies startup template projects: Creating startup templates for your organization becomes a breeze, even if you don’t use xcodegen. The generated project can be saved in git and easily distributed across teams.
6. Seamless integration with package managers: xcodegen offers excellent support for Swift Package Manager and Carthage. Additionally, it’s easy to integrate with other tools like CocoaPods, SwiftLint, and SwiftGen using scripting.

Overall, xcodegen greatly enhances project management, collaboration, and automation, making it a powerful and efficient tool for iOS developers.

… and what disadvantages?

While xcodegen offers several advantages, it’s essential to consider some potential disadvantages:

1. Its another third-party dependency: xcodegen is an external tool that you need to include in your project. Relying on an external tool means you depend on its maintenance, updates, and compatibility with future Xcode versions.
2. Learning curve: Getting started with xcodegen can be a bit challenging, as it requires understanding its YAML configuration and how it interacts with Xcode projects. Developers may need some basic training to use it effectively.
3. Documentation challenges: The documentation for xcodegen can be extensive, but it might lack advanced examples, leading to potential roadblocks when facing specific issues. It’s advisable to work on demo projects first before using it extensively in complex projects.

Despite these disadvantages, many developers find xcodegen to be a valuable and time-saving tool for managing Xcode projects effectively. Careful consideration of its pros and cons can help you determine if it’s the right fit for your specific project requirements.

We also hope this basic guide has been helpful to you, particularly if you were not familiar with the tool. We trust that it has sparked your curiosity to start experimenting with and possibly integrating xcodegen into your projects.

Happy coding! 🎉

Bibliography

• Documentation and official guides in github xcodegen.
• Tuist (similar tool based on swift and not in yaml).
• Github fully example developed in this article.
• ¡Puedes seguir este artículo en castellano aquí!