Updating some of the site pages to account for Bazel and Tulsi changes.
PiperOrigin-RevId: 191945625
diff --git a/site/docs/gettingstarted.md b/site/docs/gettingstarted.md
index 2ebe667..a99861a 100644
--- a/site/docs/gettingstarted.md
+++ b/site/docs/gettingstarted.md
@@ -6,13 +6,12 @@
# How does it work?
Tulsi uses information in Bazel `BUILD` files in order to generate Xcode
-projects. The primary difference between Tulsi-generated projects and those
-created by the native Bazel "xcodeprojgen" is that Tulsi projects use Bazel to
-compile and sign binaries, rather than Xcode's native infrastructure. This means
-that the binary you use during development will be exactly the same as the one
-you make via a commandline build. In addition, Tulsi projects can operate on a
-subset of the source files in your project. For large projects this can mean a
-significant reduction in the amount of time Xcode spends indexing files.
+projects. Tulsi projects use Bazel to compile and sign binaries, rather than
+Xcode's native infrastructure. This means that the binary you use during
+development will be exactly the same as the one you make via a command line
+build. In addition, Tulsi projects can operate on a subset of the source files
+in your project. For large projects this can mean a significant reduction in the
+amount of time Xcode spends indexing files.
Tulsi's reliance on Bazel also has some interesting side effects. For instance,
Tulsi-generated projects do not include Info.plist files directly as they are
@@ -24,42 +23,42 @@
# How do I build and install Tulsi?
-Instructions can be found in the project's [README](https://github.com/bazelbuild/tulsi#building-and-installing)
+Instructions can be found in the project's
+[README](https://github.com/bazelbuild/tulsi#building-and-installing)
# What Bazel flags are used when building?
__Note__: this list is limited to "interesting" flags and is not necessarily
perfectly up to date. The current set of flags can be seen in the
-[`bazel_build.py` script](https://bazel.googlesource.com/tulsi/+/master/src/TulsiGenerator/Scripts/bazel_build.py)
+[`bazel_build.py`
+script](https://bazel.googlesource.com/tulsi/+/master/src/TulsiGenerator/Scripts/bazel_build.py)
and their operation can be retrieved from Bazel's help.
Flags used for all build modes:
-* `--config=ios_$(arch)` - sets up predefined Bazel options for the architecture
- exposed by Xcode.
-* `--ios_minimum_os` - passed through from the Tulsi
- `IPHONEOS_DEPLOYMENT_TARGET` option.
-* `--xcode_version` - passes the version of Xcode that invokes the compilation
- script.
+* `--config=$(platform)_$(arch)` - sets up predefined Bazel options for the
+ architecture exposed by Xcode.
+* `--xcode_version` - passes the version of Xcode that invokes the compilation
+ script.
Mode dependent flags:
-* `--compilation_mode` - set to `dbg`, `opt`, or `fastbuild` depending on the
- Xcode build mode (Debug, Release, or Fastbuild).
+* `--compilation_mode` - set to `dbg`, `opt`, or `fastbuild` depending on the
+ Xcode build mode (Debug, Release, or Fastbuild).
Debug mode flags:
-* `--copt` flags:
- * `-fdebug-compilation-dir` - instructs the compiler to use the specified
- path when generating debug symbols. This allows Xcode to find source files
- when debugging Bazel-generated binaries.
-* `--objccopt` flags:
- * `-fdebug-compilation-dir` - as above.
-* `--apple_generate_dsym` - generates dSYM bundles.
+* `--copt` flags:
+ * `-fdebug-compilation-dir` - instructs the compiler to use the specified
+ path when generating debug symbols. This allows Xcode to find source
+ files when debugging Bazel-generated binaries.
+* `--objccopt` flags:
+ * `-fdebug-compilation-dir` - as above.
+* `--apple_generate_dsym` - generates dSYM bundles.
Release mode flags:
-* `--apple_generate_dsym` - generates dSYM bundles.
+* `--apple_generate_dsym` - generates dSYM bundles.
# How do I use it?
@@ -67,74 +66,71 @@
### 1. Create a new Tulsi project
- Tulsi leverages a project bundle which captures the set of Bazel packages in
- your project and provides a convenient location to store shared generator
- configuration files. Generator configuration files ("gen configs") capture a
- set of Bazel targets to build, sources to expose in Xcode, and associated
- options and are translated directly into Xcode projects by Tulsi.
+Tulsi leverages a project bundle which captures the set of Bazel packages in
+your project and provides a convenient location to store shared generator
+configuration files. Generator configuration files ("gen configs") capture a set
+of Bazel targets to build, sources to expose in Xcode, and associated options
+and are translated directly into Xcode projects by Tulsi.
- The first step is to create a Tulsi project by launching the Tulsi app.
+The first step is to create a Tulsi project by launching the Tulsi app.
- 
+
- Give your project a name and select the location of your Bazel WORKSPACE
- file, then click "Next".
+Give your project a name and select the location of your Bazel WORKSPACE file,
+then click "Next".
- 
+
- At this point you should see the "Packages" tab for your project. This is
- where you'll add any BUILD files in your project as well as set the path to
- the Bazel binary that will be used both to generate an Xcode project and to
- compile.
+At this point you should see the "Packages" tab for your project. This is where
+you'll add any BUILD files in your project as well as set the path to the Bazel
+binary that will be used both to generate an Xcode project and to compile.
- 
+
### 2. Add BUILD files
- Click on the "+" button to add your BUILD file. Repeat this step if you have
- more than one BUILD file containing targets you wish to build directly. For
- example, you might have one BUILD file with your `ios_application` and
- another containing `ios_test` rules.
+Click on the "+" button to add your BUILD file. Repeat this step if you have
+more than one BUILD file containing targets you wish to build directly. For
+example, you might have one BUILD file with your `ios_application` and another
+containing `ios_unit_test` rules.
- 
+
### 3. Set default options if applicable
- Tulsi allows you to set various options that are used by the generated Xcode
- project. Probably the most interesting are the "'build' options", which are
- used directly by Bazel during compilation.
- Tulsi options may be set in two places, at the project level (via the
- "Default options" tab) and on a per-gen config basis. The values set in the
- "Default options" tab will be used when creating new Tulsi gen configs and
- are most useful for options that will be the same for every developer working
- on your project.
+Tulsi allows you to set various options that are used by the generated Xcode
+project. Probably the most interesting are the "'build' options", which are used
+directly by Bazel during compilation. Tulsi options may be set in two places, at
+the project level (via the "Default options" tab) and on a per-gen config basis.
+The values set in the "Default options" tab will be used when creating new Tulsi
+gen configs and are most useful for options that will be the same for every
+developer working on your project.
- 
+
### 4. Create project generator configs
- The final step in setting up your project is to create one or more generator
- configurations. A larger project might have several gen configs, perhaps one
- with sources for the UI layer, another with an important supporting library,
- etc... Gen configs allow you to tailor the set of sources indexed by Xcode to
- your preference without needing to include every source file in order to
- compile.
+The final step in setting up your project is to create one or more generator
+configurations. A larger project might have several gen configs, perhaps one
+with sources for the UI layer, another with an important supporting library,
+etc... Gen configs allow you to tailor the set of sources indexed by Xcode to
+your preference without needing to include every source file in order to
+compile.
- 
+
- Clicking the "+" button will allow you to add new generator configs. Double
- clicking on an existing config will allow you to edit it, and the "-" button
- can be used to permanently delete previously created configs.
+Clicking the "+" button will allow you to add new generator configs. Double
+clicking on an existing config will allow you to edit it, and the "-" button can
+be used to permanently delete previously created configs.
- Note that if you haven't already saved the project, you'll be asked to do so
- the first time you add a config. You can save the project pretty much
- wherever you like, but you'll get the most benefit out of checking it into
- your source tree so it may be shared by other developers on your team. The
- project bundle is entirely shareable apart from the `tulsiconf-user` files,
- which contain settings that are likely to be user specific (such as absolute
- paths).
+Note that if you haven't already saved the project, you'll be asked to do so the
+first time you add a config. You can save the project pretty much wherever you
+like, but you'll get the most benefit out of checking it into your source tree
+so it may be shared by other developers on your team. The project bundle is
+entirely shareable apart from the `tulsiconf-user` files, which contain settings
+that are likely to be user specific (such as absolute paths).
- 
+
## The Tulsi generator configuration editor
@@ -142,64 +138,63 @@
### 1. Select build targets
- The first page of the config editor shows the full list of targets contained
- in the BUILD files associated with the project.
+The first page of the config editor shows the full list of targets contained in
+the BUILD files associated with the project.
- 
+
- Select one or more targets that you want to build in Xcode. For a typical
- project, like the PrenotCalculator demo, you'll choose your `ios_application`
- and maybe associated `ios_test` targets.
+Select one or more targets that you want to build in Xcode. For a typical
+project, like the PrenotCalculator demo, you'll choose your `ios_application`
+and maybe associated `ios_unit_test` targets.
- 
+
### 2. Set options
- If you need to set any options for your config, this is the place. The option
- editor will be prepopulated with the values set in the "Default options" tab
- in the project, but you may modify or add anything you'd like here.
+If you need to set any options for your config, this is the place. The option
+editor will be prepopulated with the values set in the "Default options" tab in
+the project, but you may modify or add anything you'd like here.
- Options may be set both at a project-level (affecting all build targets)...
+Options may be set both at a project-level (affecting all build targets)...
- 
+
- ... and a per-target level, affecting only one selected build target.
- 
+... and a per-target level, affecting only one selected build target.
+
- To edit an option's value, click on the cell. Values may also be double
- clicked in order to pop a larger editor.
- 
- 
+To edit an option's value, click on the cell. Values may also be double clicked
+in order to pop a larger editor.
+
+
### 3. Select source targets
- The wizard will then show the dependencies of the build targets you've
- selected that contain source files. This allows you to select a working set
- from your full source tree that best matches the portion of the project that
- you're likely to edit.
- There is also a "recursive" option, which will include the selected folder
- and any folder inside of it (even folders that are created after the config).
- PrenotCalculator is a small enough project that it makes sense to select all
- of the source targets.
+The wizard will then show the dependencies of the build targets you've selected
+that contain source files. This allows you to select a working set from your
+full source tree that best matches the portion of the project that you're likely
+to edit. There is also a "recursive" option, which will include the selected
+folder and any folder inside of it (even folders that are created after the
+config). PrenotCalculator is a small enough project that it makes sense to
+select all of the source targets.
- 
+
### 4. Set the config's name if necessary
- If this is a new generator config, you'll be asked to provide a name before
- saving. This name is used only to differentiate configs and does not have a
- direct effect on the generated Xcode project.
+If this is a new generator config, you'll be asked to provide a name before
+saving. This name is used only to differentiate configs and does not have a
+direct effect on the generated Xcode project.
- 
+
- For instance, if the "PrenotCalculator" project had two configs named
- "Small config" and "Full config", both would generate an Xcode bundle named
- PrenotCalculator.xcodeproj.
+For instance, if the "PrenotCalculator" project had two configs named "Small
+config" and "Full config", both would generate an Xcode bundle named
+PrenotCalculator.xcodeproj.
## Generating Xcode projects
- Once your project is set up, you'll want to generate an Xcode project from one
- of your configs. This is done by navigating to the "Configs" tab...
+Once your project is set up, you'll want to generate an Xcode project from one
+of your configs. This is done by navigating to the "Configs" tab...
@@ -239,7 +234,8 @@
# Generating Xcode projects from the command-line
Tulsi can also create Xcode projects from generator configs without launching
-the Tulsi UI. There is a [helper script](https://bazel.googlesource.com/tulsi/+/master/src/tools/generate_xcodeproj.sh)
+the Tulsi UI. There is a [helper
+script](https://bazel.googlesource.com/tulsi/+/master/src/tools/generate_xcodeproj.sh)
to seek out and apply command line parameters to the Tulsi app binary.
Running this script with no arguments will print information on usage.
diff --git a/site/docs/walkthrough.md b/site/docs/walkthrough.md
index 48215f7..6613da5 100644
--- a/site/docs/walkthrough.md
+++ b/site/docs/walkthrough.md
@@ -5,31 +5,31 @@
# 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
+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
-1. A UI team, responsible for the application's user interface
+1. An infrastructure team, working on the computer vision portion of the app
+1. A UI team, responsible for the application's user interface
The team just finished switching over to build their app with
[Bazel](https://bazel.build) and have an `ios_application` rule called
-`//albahaca:Application` under the `albahaca` folder, an `objc_binary` rule
-called `AppBinary` in the `albahaca/App` folder and an `objc_library` named
+`//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](/docs/gettingstarted.html) documentation and, since she's
-decided to use the command-line to generate Xcode projects, knows that she
-has to accomplish four steps:
+Xcode for development. She has read the [getting
+started](/docs/gettingstarted.html) 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
-1. Creating Tulsi generator configs
-1. Writing up a helper script that her team may use to generate Xcode projects
-1. Checking everything into source control
+1. Creating a Tulsi project
+1. Creating Tulsi generator configs
+1. Writing up a helper script that her team may use to generate Xcode projects
+1. Checking everything into source control
# Creating a Tulsi project
@@ -51,12 +51,12 @@
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
-1. Another for her UI team that omits the computer vision sources to reduce the
- amount of time Xcode spends indexing files
-1. A final one for her infrastructure team that leaves out the UI sources for
- the same reason
+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
+1. Another for her UI team that omits the computer vision sources to reduce the
+ amount of time Xcode spends indexing files
+1. 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.
@@ -86,8 +86,8 @@
simple wrapper for the
[generate_xcodeproj.sh](https://github.com/bazelbuild/tulsi/blob/master/src/tools/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.
+`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
