Create a CocoaPods to Bazel dependencies conversion guide.
This guide will be labeled as "Experimental" and linked under the new "Experimental" section (unknown commit) with an appropriate disclaimer.
PiperOrigin-RevId: 173279988
diff --git a/site/docs/migrate-cocoapods.md b/site/docs/migrate-cocoapods.md
new file mode 100644
index 0000000..0d26799
--- /dev/null
+++ b/site/docs/migrate-cocoapods.md
@@ -0,0 +1,40 @@
+---
+layout: documentation
+title: Converting CocoaPods dependencies
+---
+
+# Converting CocoaPods dependencies
+
+This document provides high-level guidelines for converting [CocoaPods](https://www.cocoapods.org/)
+dependencies to Bazel packages that are compatible with [Tulsi](http://http://tulsi.bazel.build/).
+CocoaPods is a third-party dependency management system for macOS and iOS
+development.
+
+## Analyze your CocoaPods dependencies
+
+If you're using CocoaPods, you need to:
+
+1. Examine the `Podfile` files to determine the hierarchy of the `Podspecs`.
+
+2. Take note of the version numbers in the corresponding `Podfile.lock` files
+ to ensure that you are pulling the correct `Podspecs`.
+
+3. Document the dependency tree, including the hierarchy of the `Podspecs`,
+ resource URLs, filenames, and version numbers.
+
+## Converting a Podspec to a Bazel package
+
+To convert a Podspec dependency to a Bazel package, do the following:
+
+1. Download each Podspec and decompress it into its own directory within the
+ Bazel workspace. All Podspecs must reside within the same Bazel workspace for
+ Tulsi to be aware of them for inclusion in the Xcode project.
+
+2. Within the Podspec directory, create a `BUILD` file that specifies the
+ library target(s) referencing the source and header files on which your
+ project depends.
+
+3. Based on your project's dependency tree, add the Podspec target(s) as
+ dependencies to the appropriate targets in the project's `BUILD` file(s).
+
+4. In the project's `BUILD` files, configure package visibility as desired.
diff --git a/site/docs/migrate-xcode.md b/site/docs/migrate-xcode.md
index 6af2c0e..792bfe5 100644
--- a/site/docs/migrate-xcode.md
+++ b/site/docs/migrate-xcode.md
@@ -16,13 +16,14 @@
- [Analyze project dependencies](#analyze-project-dependencies)
- [Build or test an Xcode project with Bazel](#build-or-test-an-xcode-project-with-bazel)
- [Step 1: Create the `WORKSPACE` file](#step-1-create-the-workspace-file)
- - [Step 2: Create a `BUILD` file:](#step-2-create-a-build-file)
- - [Step 2a: Add the application target](#step-2a-add-the-application-target)
- - [Step 2b: (Optional) Add the test target(s)](#step-2b-optional-add-the-test-target-s)
- - [Step 2c: Add the library target(s)](#step-2c-add-the-library-target-s)
- - [Step 3: (Optional) Granularize the build](#step-3-optional-granularize-the-build)
- - [Step 4: Run the build](#step-4-run-the-build)
- - [Step 5: Generate the Xcode project with Tulsi](#step-5-generate-the-xcode-project-with-tulsi)
+ - [Step 2: (Experimental) Integrate CocoaPod dependencies](#step-2-experimental-integrate-pocoapods-dependencies)
+ - [Step 3: Create a `BUILD` file:](#step-3-create-a-build-file)
+ - [Step 3a: Add the application target](#step-3a-add-the-application-target)
+ - [Step 3b: (Optional) Add the test target(s)](#step-3b-optional-add-the-test-target-s)
+ - [Step 3c: Add the library target(s)](#step-3c-add-the-library-target-s)
+ - [Step 4: (Optional) Granularize the build](#step-4-optional-granularize-the-build)
+ - [Step 5: Run the build](#step-5-run-the-build)
+ - [Step 6: Generate the Xcode project with Tulsi](#step-6-generate-the-xcode-project-with-tulsi)
## Differences between Xcode and Bazel
@@ -87,19 +88,21 @@
1. [Create the `WORKSPACE` file](#step-1-create-the-workspace-file)
-2. [Create a `BUILD` file:](#step-2-create-a-build-file)
+2. [(Experimental) Integrate CocoaPods dependencies](#step-2-experimental-integrate-cocoapods-dependencies)
- a. [Add the application target](#step-2a-add-the-application-target)
+3. [Create a `BUILD` file:](#step-3-create-a-build-file)
- b. [(Optional) Add the test target(s)](#step-2b-optional-add-the-test-target-s)
+ a. [Add the application target](#step-3a-add-the-application-target)
- c. [Add the library target(s)](#step-2c-add-the-library-target-s)
+ b. [(Optional) Add the test target(s)](#step-3b-optional-add-the-test-target-s)
-3. [(Optional) Granularize the build](#step-3-optional-granularize-the-build)
+ c. [Add the library target(s)](#step-3c-add-the-library-target-s)
-4. [Run the build](#step-4-run-the-build)
+4. [(Optional) Granularize the build](#step-4-optional-granularize-the-build)
-5. [Generate the Xcode project with Tulsi](#step-5-generate-the-xcode-project-with-tulsi)
+5. [Run the build](#step-5-run-the-build)
+
+6. [Generate the Xcode project with Tulsi](#step-6-generate-the-xcode-project-with-tulsi)
### Step 1: Create the `WORKSPACE` file
@@ -112,21 +115,31 @@
**Note:** Place the project source code within the directory tree containing the
`WORKSPACE` file.
-### Step 2: Create a `BUILD` file
+### Step 2: (Experimental) Integrate CocoaPods dependendcies
+
+To integrate CocoaPods dependencies into the Bazel workspace, you must convert
+them into Bazel packages as described in [Converting CocoaPods dependencies](migrate-cocoapods.md).
+
+**Note:** CocoaPods conversion is a manual process with many variables.CocoaPods
+integration with Bazel has not been fully verified and is not officially
+supported.
+
+
+### Step 3: Create a `BUILD` file
Once you have defined the workspace and external dependencies, you need to
create a `BUILD` file that tells Bazel how the project is structured. Create
the `BUILD` file at the root of the Bazel workspace and configure it to do an
initial build of the project as follows:
-* [Step 2a: Add the application target](#step-2a-add-the-application-target)
-* [Step 2b: (Optional) Add the test target(s)](#step-2b-optional-add-the-test-target-s)
-* [Step 2c: Add the library target(s)](#step-2c-add-the-library-target-s)
+* [Step 3a: Add the application target](#step-3a-add-the-application-target)
+* [Step 3b: (Optional) Add the test target(s)](#step-3b-optional-add-the-test-target-s)
+* [Step 3c: Add the library target(s)](#step-3c-add-the-library-target-s)
**Tip:** To learn more about packages and other Bazel concepts, see
[Bazel Terminology](https://docs.bazel.build/versions/master/build-ref.html).
-#### Step 2a: Add the application target
+#### Step 3a: Add the application target
Add a [`macos_application`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-macos.md#macos_application)
or an [`ios_application`](https://docs.bazel.build/versions/master/be/objective-c.html#ios_application)
@@ -148,7 +161,7 @@
application supports. This ensures Bazel builds the application with the
correct API levels.
-#### Step 2b: (Optional) Add the test target(s)
+#### Step 3b: (Optional) Add the test target(s)
Bazel's [Apple build rules](https://github.com/bazelbuild/rules_apple) support
running library-based unit tests on iOS and macOS, as well as application-based
@@ -178,7 +191,7 @@
`test_host` attribute.
-#### Step 2c: Add the library target(s)
+#### Step 3c: Add the library target(s)
Add an [`objc_library`](https://docs.bazel.build/versions/master/be/objective-c.html#objc_library)
target for each Objective C library and a [`swift_library`](https://github.com/bazelbuild/rules_apple/blob/master/doc/rules-swift.md)
@@ -206,7 +219,7 @@
`bazel build //:<application_target>`
-### Step 3: (Optional) Granularize the build
+### Step 4: (Optional) Granularize the build
If the project is large, or as it grows, consider chunking it into multiple
Bazel packages. This increased granularity provides:
@@ -240,7 +253,7 @@
* Build the project after each major change to the `BUILD` files and fix
build errors as you encounter them.
-### Step 4: Run the build
+### Step 5: Run the build
Run the fully migrated build to ensure it completes with no errors or warnings.
Run every application and test target individually to more easily find sources
@@ -252,7 +265,7 @@
bazel build //:my-target
```
-### Step 5: Generate the Xcode project with Tulsi
+### Step 6: Generate the Xcode project with Tulsi
When building with Bazel, the `WORKSPACE` and `BUILD` files become the source
of truth about the build. To make Xcode aware of this, you must generate a
