Walkthrough

Background

This brief walkthrough explores setting up a new Tulsi project for a team building a hypothetical app called Albahaca which uses computer vision to identify garden herbs.

The app team is roughly divided into two groups:

1. An infrastructure team, working on the computer vision portion of the app
2. A UI team, responsible for the application's user interface

The team just finished switching over to build their app with Bazel and have an ios_application rule called //albahaca:Application under the albahaca folder, an objc_library rule called AppLibrary in the albahaca/App folder and an objc_library named Vision in the albahaca/Vision folder.

Kay, the team's tech lead, is about to use Tulsi to allow her teammates to use Xcode for development. She has read the getting started documentation and, since she's decided to use the command-line to generate Xcode projects, knows that she has to accomplish four steps:

1. Creating a Tulsi project
2. Creating Tulsi generator configs
3. Writing up a helper script that her team may use to generate Xcode projects
4. Checking everything into source control

Creating a Tulsi project

Kay starts off by running Tulsi.app and clicking the "Create new project..." button. In the resulting popup, she enters Albahaca as her project name and selects the location of her WORKSPACE file.

She then adds the albahaca/BUILD file to the Tulsi project using the "+" button.

Kay's team uses a bazelrc file to set up their common build options, so she switches to the "Shared options" segment and adds --bazelrc=albahaca/bazelrc to the "'build startup options".

Finally, she is ready to add configs for her team, so she switches to the "Configs" segment.

Creating Tulsi generator configs

Kay has decided to create three configs for her team.

1. One that includes all of the sources and targets and can be used to build and debug issues that cut across the UI and infrastructure layers
2. Another for her UI team that omits the computer vision sources to reduce the amount of time Xcode spends indexing files
3. A final one for her infrastructure team that leaves out the UI sources for the same reason

She starts off by clicking the "+" button on the "Configs" segment, saving her Tulsi project as Albahaca in the albahaca directory when asked.

For her first config, Kay selects her ios_application, Albahaca and clicks "Next." She doesn't need to set any special build options, so she skips the options screen and goes to the source selection step. Since she wants to include all sources, she checks the "Recursive" box for the albahaca directory and clicks the "Save" button. Kay wants this to be the default config for command-line builds, so she names it Albahaca in order to match the name of her Tulsi project.

Next up she creates the config for her UI team. Kay follows the same steps as for the complete config but, instead of including the albahaca folder recursively, she expands it and checks the "Recursive" box for the App folder. This excludes the Vision sources and will create a smaller, more focused Xcode project that will index faster than the full Albahaca config. This time she saves her config as App.

Finally, she sets up the config for her infrastructure team in the same way, using the Vision folder and saving the config as Vision.

Generating xcodeproj bundles from the command-line

Kay knows that the team could use the Tulsi UI to generate their project, but her team is more comfortable with something scriptable. She decides to write a simple wrapper for the generate_xcodeproj.sh script in the Tulsi tools folder. She knows that the team has the generate_xcodeproj.sh script in their shared /tools/Tulsi mount and Bazel in /tools/Bazel so it'll be safe to refer to them there.

#!/bin/bash -eu

readonly config=${1:-Albahaca}
readonly tulsi_script="/tools/Tulsi/generate_xcodeproj.sh"

if [[ ! -d "Albahaca.tulsiproj" ]]; then
  echo "$0 must be run from the albahaca directory"
  exit 1
fi

exec "${tulsi_script}" --bazel /tools/Bazel/bazel \
    --genconfig "Albahaca.tulsiproj:${config}"

Checking files into git

Kay's team are git users, so she starts off by creating a .gitignore file for her project.

# Tulsi user-specific data.
*.tulsiconf-user

# Xcode user data.
xcuserdata
# Alternatively, if all Xcode projects in this repository are going to be Tulsi-
# generated, the entire xcodeproj bundle may be ignored by uncommenting the
# following line.
# *.xcodeproj

# Tulsi-related Bazel symlinks (which are generally self-cleaned).
tulsigen-*

She then adds the Albahaca.tulsiproj bundle and her generate_project.sh script to git and submits it.

git add generate_xcodeproj.sh Albahaca.tulsiproj
git commit -am "Adds Tulsi project for Albahaca."

At this point, Kay has finished setting everything up and emails her team to let them know that they can use generate_project.sh to leverage Xcode going forward.