diff options
-rw-r--r-- | site/docs/tutorial/android-app.md | 4 | ||||
-rw-r--r-- | site/docs/tutorial/backend-server.md | 7 | ||||
-rw-r--r-- | site/docs/tutorial/environment.md | 63 | ||||
-rw-r--r-- | site/docs/tutorial/ios-app.md | 179 |
4 files changed, 126 insertions, 127 deletions
diff --git a/site/docs/tutorial/android-app.md b/site/docs/tutorial/android-app.md index f31736b9f9..cdab41e4c0 100644 --- a/site/docs/tutorial/android-app.md +++ b/site/docs/tutorial/android-app.md @@ -276,7 +276,9 @@ command. This command uses the Android Debug Bridge (`adb`) to communicate with the device. You must set up your device to use `adb` following the instructions in [Android Debug Bridge](http://developer.android.com/tools/help/adb.html) before -deployment. +deployment. You can also choose to install the app on the Android emulator +included in Android Studio. Make sure the emulator is running before executing +the command below. Enter the following: diff --git a/site/docs/tutorial/backend-server.md b/site/docs/tutorial/backend-server.md index 00c61ac43d..9ebbffad7d 100644 --- a/site/docs/tutorial/backend-server.md +++ b/site/docs/tutorial/backend-server.md @@ -82,7 +82,8 @@ appengine_repositories() AppEngine rules from a GitHub archive. We could also have used [`git_repository`](/docs/be/workspace.html#git_repository) to fetch the rules directly from the Git repository. -Then the next two lines use the `appengine_repositories` function defined in + +The next two lines use the `appengine_repositories` function defined in these rules to download the libraries and SDK needed to build AppEngine applications. @@ -162,13 +163,13 @@ Make sure that your current working directory is inside your Bazel workspace: cd $WORKSPACE ``` -Now, enter the following to build the sample app: +Now, enter the following to build the server: ```bash bazel build //backend:backend ``` -Bazel now launches and builds the sample app. During the build process, its +Bazel now launches and builds the server files. During the build process, its output will appear similar to the following: ```bash diff --git a/site/docs/tutorial/environment.md b/site/docs/tutorial/environment.md index 68548dfdfc..20a48701eb 100644 --- a/site/docs/tutorial/environment.md +++ b/site/docs/tutorial/environment.md @@ -10,8 +10,8 @@ The first step in this tutorial is to set up your environment. Here, you'll do the following: * Install Bazel -* Install Android Studio and the Android SDK -* Install Xcode (macOS (OS X) only) +* Install Android Studio +* Install Xcode (macOS only) * Get the sample project from the GitHub repo ## Install Bazel @@ -19,47 +19,26 @@ Here, you'll do the following: Follow the [installation instructions](/docs/install.md) to install Bazel and its dependencies. -## Install the Android SDK tools - -Do the following: - -1. Download and install the - [Android SDK Tools](https://developer.android.com/sdk/index.html#Other). - -2. Run the Android SDK Manager and install the following packages: - - <table class="table table-condensed table-striped"> - <thead> - <tr> - <td>Package</td> - <td>SDK directory</td> - </tr> - </thead> - <tbody> - <tr> - <td>Android SDK Platform Tools</td> - <td><code>platform-tools</code></td> - </tr> - <tr> - <td>Android SDK Build Tools</td> - <td><code>build-tools</code></td> - </tr> - <tr> - <td>Android SDK Platform</td> - <td><code>platform</code></td> - </tr> - </tbody> - </table> - - The SDK Manager is an executable named `android` located in the `tools` - directory. - -## Install Xcode (OS X only) - -If you are following the steps in this tutorial on Mac OS X, download and +## Install Android Studio + +Download and install Android Studio as described in [Install Android Studio](https://developer.android.com/sdk/index.html). + +The installer does not automatically set the `ANDROID_HOME` variable. +Set it to the location of the Android SDK, which defaults to `$HOME/Android/Sdk/` +. + +For example: + +`export ANDROID_HOME=$HOME/Android/Sdk/` + +For convenience, add the above statement to your `~/.bashrc` file. + +## Install Xcode (macOS only) + +If you are following the steps in this tutorial on macOS, download and install [Xcode](https://developer.apple.com/xcode/downloads/). The Xcode -download contains the iOS libraries, Objective-C compiler other tools -required by Bazel to build the iOS app. +download contains the iOS libraries, the Objective-C compiler, and other tools +required by Bazel to build iOS apps. ## Get the sample project diff --git a/site/docs/tutorial/ios-app.md b/site/docs/tutorial/ios-app.md index abf49d27c4..ce17c2b9c9 100644 --- a/site/docs/tutorial/ios-app.md +++ b/site/docs/tutorial/ios-app.md @@ -6,8 +6,11 @@ title: Tutorial - Build an iOS App # Tutorial - Build an iOS App Like the [Android app](android-app.md) you built in the previous step, the iOS -app is a simple mobile app that communicates with the -[backend server](backend-server.md). +app is a simple mobile app that communicates with the [backend server](backend-server.md). + +If you're following the steps in this tutorial on macOS, you can go ahead +and build the sample iOS app as described below. If you are on Linux, skip ahead +to the [next step](backend-server.md). Here, you'll do the following: @@ -19,12 +22,19 @@ Here, you'll do the following: * Build the app for a device * Install the app on a device -Note that, unlike with the Android app, you don't have to modify your -`WORKSPACE` file to add iOS-specific external dependencies. +## Update the WORKSPACE file -If you're following the steps in this tutorial on macOS (OS X), you can go ahead -and build the sample iOS app as described below. If you are on Linux, skip ahead -to the [next step](backend-server.md). +To build applications for Apple devices, Bazel needs to pull the latest +[Apple build rules](https://github.com/bazelbuild/rules_apple) from its GitHub +repository. To enable this, add the following to your `WORKSPACE` file: + +``` +git_repository( + name = "build_bazel_rules_apple", + remote = "https://github.com/bazelbuild/rules_apple.git", + tag = "0.0.1", +) +``` ## Review the source files @@ -41,18 +51,28 @@ At a command-line prompt, open your new `BUILD` file for editing: vi $WORKSPACE/ios-app/BUILD ``` +## Add the rule load statement + +To build iOS targets, Bazel needs to load build rules from its GitHub repository +whenever the build runs. To make these rules available to your project, add the +following load statement to the beginning of your `BUILD` file: + +``` +load("@build_bazel_rules_apple//apple:ios.bzl", "ios_application") +``` + ## Add an objc_library rule Bazel provides several build rules that you can use to build an app for the iOS platform. For this tutorial, you'll first use the [`objc_library`](/docs/be/objective-c.html#objc_library) rule to tell Bazel -how to build an -[static library](https://developer.apple.com/library/ios/technotes/iOSStaticLibraries/Introduction.html) -from the app source code and Xib files. Then you'll use the -`objc_binary` rule to tell it how to bundle the iOS application. (Note that -this is a minimal use case of the Objective-C rules in Bazel. For example, you -have to use the `ios_application` rule to build multi-architecture iOS -apps.) +how to build a static library from the app source code and Xib files. Then +you'll use the [`ios_application`](https://github.com/bazelbuild/rules_apple) +rule to tell it how to build the application binary and the `.ipa` bundle. + +**NOTE:** This tutorial presents a minimal use case of the Objective-C rules in +Bazel. For example, you have to use the `ios_application` rule to build +multi-architecture iOS apps. Add the following to your `BUILD` file: @@ -60,8 +80,9 @@ Add the following to your `BUILD` file: objc_library( name = "UrlGetClasses", srcs = [ - "UrlGet/AppDelegate.m", - "UrlGet/UrlGetViewController.m", + "UrlGet/AppDelegate.m", + "UrlGet/UrlGetViewController.m", + "UrlGet/main.m", ], hdrs = glob(["UrlGet/*.h"]), xibs = ["UrlGet/UrlGetViewController.xib"], @@ -70,44 +91,30 @@ objc_library( Note the name of the rule, `UrlGetClasses`. -## Add an objc_binary rule - -The [`objc_binary`](/docs/be/objective-c.html#objc_binary) rule creates a -binary to be bundled in the application. - -Add the following to your `BUILD` file: - -```python -objc_binary( - name = "ios-app-binary", - srcs = [ - "UrlGet/main.m", - ], - deps = [ - ":UrlGetClasses", - ], -) - -``` -Note how the `deps` attribute references the output of the -`UrlGetClasses` rule you added to the `BUILD` file above. - ## Add an ios_application rule -The [`ios_application`](/docs/be/objective-c.html#ios_application) rule -creates the bundled `.ipa` archive file for the application and also generates -an Xcode project file. +The [`ios_application`](/docs/be/objective-c.html#ios_application) rule builds +the application binary and creates the `.ipa` bundle file. Add the following to your `BUILD` file: ```python ios_application( name = "ios-app", - binary = ":ios-app-binary", - infoplist = "UrlGet/UrlGet-Info.plist", + bundle_id = "Google.UrlGet", + families = [ + "iphone", + "ipad", + ], + infoplists = [":UrlGet/UrlGet-Info.plist"], + visibility = ["//visibility:public"], + deps = [":UrlGetClasses"], ) ``` +Note how the `deps` attribute references the output of the `UrlGetClasses` rule +you added to the `BUILD` file above. + Now, save and close the file. You can compare your `BUILD` file to the [completed example](https://github.com/bazelbuild/examples/blob/master/tutorial/ios-app/BUILD) in the `master` branch of the GitHub repo. @@ -126,17 +133,18 @@ Now, enter the following to build the sample app: bazel build //ios-app:ios-app ``` -Bazel now launches and builds the sample app. During the build process, its +Bazel launches and builds the sample app. During the build process, its output will appear similar to the following: ```bash INFO: Found 1 target... Target //ios-app:ios-app up-to-date: bazel-bin/ios-app/ios-app.ipa - bazel-bin/ios-app/ios-app.xcodeproj/project.pbxproj -INFO: Elapsed time: 3.765s, Critical Path: 3.44s +INFO: Elapsed time: 0.565s, Critical Path: 0.44s ``` + + ## Find the build outputs The `.ipa` file and other outputs are located in the @@ -144,60 +152,69 @@ The `.ipa` file and other outputs are located in the ## Run/Debug the app on the simulator -You can now run the app from Xcode using the iOS Simulator. To run the app, -open the project directory `$WORKSPACE/bazel-bin/ios-app/ios-app.xcodeproj` in -Xcode, choose an iOS Simulator as the runtime scheme and then click the **Run** -button. +You can now run the app from Xcode using the iOS Simulator. First, [generate an Xcode project using Tulsi](http://tulsi.bazel.io/). +Then, open the project in Xcode, choose an iOS Simulator as the runtime scheme, +and click **Run**. -**Note:** If you change anything about the project file set in Xcode (for -example, if you add or remove a file, or add or change a dependency), you must -rebuild the app using Bazel and then re-open the project. +**Note:** If you modify any project files in Xcode (for example, if you add or +remove a file, or add or change a dependency), you must rebuild the app using +Bazel, re-generate the Xcode project in Tulsi, and then re-open the project in +Xcode. ## Build the app for a device -You need to set up bazel so that it can find the appropriate provisioning -profile for the device you want to build for. To set up the "default" -provisioning profile for all bazel builds: +To build your app so that it installs and launches on an iOS device, Bazel needs +the appropriate provisioning profile for that device model. Do the following: + +1. Go to your [Apple Developer Account](https://developer.apple.com/account) and + download the appropriate provisioning profile for your device. See + [Apple's documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html) + for more information. + +2. Move your profile into `$WORKSPACE`. - 1. Go to [Apple Profiles](https://developer.apple.com/account/ios/profile/profileList.action) - and download the appropriate provisioning profile for your device. - If this is confusing, please refer to [Apple's documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/MaintainingProfiles/MaintainingProfiles.html). - 1. Move your profile into `$WORKSPACE/tools/objc`. - 1. Optional - You may want to add your profile to your `.gitignore`. - 1. Edit `$WORKSPACE/tools/objc/BUILD` and add: +3. (Optional) Add your profile to your `.gitignore` file. - ```python - filegroup( - name = "default_provisioning_profile", - srcs = ["<NAME OF YOUR PROFILE>.mobileprovision"], - ) - ``` +4. Add the following line to the `ios_application` target in your `BUILD` file: -Now you should be able to build the app for your device: + ```python + provisioning_profile = "<your_profile_name>.mobileprovision", + ``` + + **NOTE:** Ensure the profile is correct so that the app can be installed on + a device. + +Now build the app for your device: ```bash bazel build //ios-app:ios-app --ios_multi_cpus=armv7,arm64 ``` -This will build the app "fat". If you would prefer just to build for -your specific device architecture you can designate a single architecture. +This builds the app as a fat binary. To build for a specific device +architecture, designate it in the build options. -If you would like to select a specific Xcode version you can do so -with the `--xcode_version=7.2` option. If for some reason you need to specify -a specific SDK version you can use the `--ios_sdk_version=9.2` option, but the -`--xcode_version` should be sufficient in most circumstances. +To build for a specific Xcode version, use the `--xcode_version` option. To +build for a specific SDK version, use the `--ios_sdk_version` option. The +`--xcode_version` option is sufficient in most scenarios. -If you would like to specify a minimum version of iOS to run against, you can -do so with the `--ios_minimum_os=7.0` option. +To specify a minimum required iOS version, add the `minimum_os_version` +parameter to the `ios_application` build rule in your `BUILD` file. + +You can also use [Tulsi](http://tulsi.bazel.io/docs/gettingstarted.html) to +build your app using a GUI rather than the command line. ## Install the app on a device The easiest way to install the app on the device is to launch Xcode and use the -`Windows > Devices` command. Select your plugged in device from the list on the -left, and then add the app by clicking on the "plus" sign under installed apps -and selecting the `.ipa` that you built. +`Windows > Devices` command. Select your plugged-in device from the list on the +left, then add the app by clicking on the "plus" sign under installed apps and +selecting the `.ipa` that you built. + +If your app fails to install on your device, ensure that you are specifying the +correct provisioning profile in your `BUILD` file (step 4 in the previous +section). -If your app does not launch, please make sure that your device was on your +If your app fails to launch, make sure that your device is part of your provisioning profile. The `View Device Logs` button on the `Devices` screen in Xcode may provide other information as to what has gone wrong. |