Quick Start

Rhys edited this page May 21, 2017 · 4 revisions

struct works by taking a spec file written in JSON or YAML, and turning them into Xcode projects. This quick guide will help you create your first spec file and run it with struct.

Migrate or start from scratch

struct has built in support for migrating existing Xcode projects to a spec file. This will get you a decent way through migrating an Xcode project to struct. Please read the caveats for more information about what's supported and what isn't.

You can also choose to begin structuring your project from scratch with a brand new spec file.

Creating a brand new spec file

To start with, let's create a directory to contain our source code and the spec file:

$ mkdir my-project && cd my-project

A spec file always has the name project.yml or project.json depending on which file format you choose. For this quick start, we'll be using the YAML file format.

Go ahead and create a new file named project.yml, and we'll add the bare minimum to create a working spec file:

---
version: 1.1.0
configurations:
  debug:
  release:

All done! 🎉 Now let's generate our Xcode project:

$ struct generate

A brand new file will now be present in your project directory, project.xcodeproj. Go ahead and open this in Xcode.

You'll notice there's nothing in the project yet. Let's start adding targets!

Update your project.yml so it now looks like this:

---
version: 1.1.0
configurations:
  debug:
    profiles:
  release:
    profiles:
targets:
  MyApp:
    type: ":application"
    platform: ios
    sources: src

We'll also need to create a directory for our source code, so let's go ahead and do that too:

$ mkdir src

Now let's generate the project again:

$ struct generate

Open up the project, you'll notice we now have a brand new target 'MyApp'. Awesome!

Obviously targets aren't that useful without any source code. Try adding some swift files to your my-project/src directory, then run the generate action again.

This is the main workflow for working with struct. The spec file format is incredibly versatile, and has in-depth documentation. Make sure to check it out!

struct comes packed with a lot of actions that streamline your development workflow. You can see all the actions struct can perform by running struct --help.

Migrating an existing project

In a terminal, run the migrate command. This command takes two arguments, the location of your existing Xcode project file, and the new directory where your new spec file and source code will be located.

The migrate command will copy any source files it finds that are used by your project to this directory, and save the spec file to this directory.

$ struct migrate -p /path/to/my/project.xcodeproj

That's it! 🎉 Open up your spec file and see the results

Since the migration process doesn't cover every bit of functionality in an Xcode project, it's best you read the caveats for more information about what would need manual migration after migrating an Xcode project.