diff options
| -rw-r--r-- | site/docs/migrate-cocoapods.md | 40 | ||||
| -rw-r--r-- | site/docs/migrate-xcode.md | 61 |
2 files changed, 77 insertions, 24 deletions
diff --git a/site/docs/migrate-cocoapods.md b/site/docs/migrate-cocoapods.md new file mode 100644 index 0000000000..0d2679958d --- /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 6af2c0e01a..792bfe5e31 100644 --- a/site/docs/migrate-xcode.md +++ b/site/docs/migrate-xcode.md @@ -16,13 +16,14 @@ converting an Xcode project to a Bazel project. - [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 @@ To build or test an Xcode project with Bazel, do the following: 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 @@ file. **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 @@ In the target, specify the following at the minimum: 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 @@ simulator, also specify the `ios_application` target name as the value of the `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 @@ At this point, it is a good idea to test the build: `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 @@ Tips for granularizing the project: * 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 @@ For example: 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 |