docs: remove/adjust references to Swift gazelle plugin (#1540)

Adjust the documentation now that the [Swift gazelle
plugin](https://github.com/cgrindel/swift_gazelle_plugin) has its own
repository.

Related to #924.

Author: cgrindel

README.md

@@ -1,11 +1,11 @@
-# Gazelle Plugin for Swift and Swift Package Rules for Bazel
+# Swift Package Manager Rules for Bazel
 
 [![Build](https://github.com/cgrindel/rules_swift_package_manager/actions/workflows/ci.yml/badge.svg?event=schedule)](https://github.com/cgrindel/rules_swift_package_manager/actions/workflows/ci.yml)
 
-This repository contains a [Gazelle plugin] and Bazel repository rules that can be used to download,
-build, and consume Swift packages. The rules in this repository build the external Swift packages
-using [rules_swift] and native C/C++ rulesets making the Swift package products and targets
-available as Bazel targets.
+This repository contains a Bazel ruleset that can be used to download, build, and consume Swift
+packages. The rules in this repository build the external Swift packages using [rules_swift],
+[rules_apple] and native C/C++ rulesets making the Swift package products and targets available as
+Bazel targets.
 
 This repository is designed to fully replace [rules_spm] and provide utilities to ease Swift
 development inside a Bazel workspace.
@@ -25,11 +25,9 @@ development inside a Bazel workspace.
   * [3. Create a minimal `Package.swift` file.](#3-create-a-minimal-packageswift-file)
   * [4. Run `swift package update`](#4-run-swift-package-update)
   * [5. Run `bazel mod tidy`.](#5-run-bazel-mod-tidy)
-  * [6. Add Gazelle targets to `BUILD.bazel` at the root of your workspace.](#6-add-gazelle-targets-to-buildbazel-at-the-root-of-your-workspace)
-  * [7. Create or update Bazel build files for your project.](#7-create-or-update-bazel-build-files-for-your-project)
-  * [8. Build and test your project.](#8-build-and-test-your-project)
-  * [9. Check in `Package.swift`, `Package.resolved`, and `MODULE.bazel`.](#9-check-in-packageswift-packageresolved-and-modulebazel)
-  * [10. Start coding](#10-start-coding)
+  * [6. Build and test your project.](#6-build-and-test-your-project)
+  * [7. Check in `Package.swift`, `Package.resolved`, and `MODULE.bazel`.](#7-check-in-packageswift-packageresolved-and-modulebazel)
+  * [8. Start coding](#8-start-coding)
 * [Using a Swift package registry](#using-a-swift-package-registry)
 * [Tips and Tricks](#tips-and-tricks)
 <!-- MARKDOWN TOC: END -->
@@ -55,8 +53,8 @@ Don't forget that `rules_swift` [expects the use of
 `clang`](https://github.com/bazelbuild/rules_swift#3-additional-configuration-linux-only). Hence,
 you will need to specify `CC=clang` before running Bazel.
 
-Finally, help [rules_swift] and [rules_swift_package_manager] find the Swift toolchain by ensuring that a `PATH`
-that includes the Swift binary is available in the Bazel actions.
+Finally, help [rules_swift] and [rules_swift_package_manager] find the Swift toolchain by ensuring
+that a `PATH` that includes the Swift binary is available in the Bazel actions.
 
 ```sh
 cat >>local.bazelrc <<EOF
@@ -89,9 +87,11 @@ common --enable_bzlmod
 Add a dependency on `rules_swift_package_manager`.
 
 <!-- BEGIN MODULE SNIPPET -->
+
 ```python
 bazel_dep(name = "rules_swift_package_manager", version = "0.47.2")
 ```
+
 <!-- END MODULE SNIPPET -->
 
 In addition, add the following to load the external dependencies described in your `Package.swift`
@@ -173,7 +173,7 @@ swift_deps.from_package(
 
 #### (Optional) Enable `swift_deps_info` generation for the Gazelle plugin
 
-If you will be using the Gazelle plugin for Swift, you will need to enable the generation of
+If you will be using the [Gazelle plugin for Swift], you will need to enable the generation of
 the `swift_deps_info` repository by enabling `declare_swift_deps_info`.
 
 ```bazel
@@ -184,8 +184,6 @@ swift_deps.from_package(
 )
 ```
 
-You will also need to add a dependency on [Gazelle](https://registry.bazel.build/modules/gazelle).
-
 ### 3. Create a minimal `Package.swift` file.
 
 Create a minimal `Package.swift` file that only contains the external dependencies that are directly
@@ -209,8 +207,8 @@ let package = Package(
 The name of the package can be whatever you like. It is required for the manifest, but it is not
 used by [rules_swift_package_manager]. If your project is published and consumed as a Swift package,
 feel free to populate the rest of the manifest so that your package works properly by Swift package
-manager. Just note that the Swift Gazelle plugin does not use the manifest to generate Bazel build
-files, at this time.
+manager. Just note that the [Swift Gazelle plugin] does not use the manifest to generate Bazel build
+files.
 
 ### 4. Run `swift package update`
 
@@ -221,71 +219,23 @@ This will invoke Swift Package Manager and resolve all dependencies resulting in
 
 This will update your `MODULE.bazel` with the correct `use_repo` declaration.
 
-### 6. Add Gazelle targets to `BUILD.bazel` at the root of your workspace.
-
-Add the following to the `BUILD.bazel` file at the root of your workspace.
-
-```bzl
-load("@gazelle//:def.bzl", "gazelle", "gazelle_binary")
-
-# Ignore the `.build` folder that is created by running Swift package manager
-# commands. Be sure to configure your source control to ignore it, as well.
-# (i.e., add it to your `.gitignore`).
-# NOTE: Swift package manager is not used to build any of the external packages.
-# gazelle:exclude .build
-
-# This declaration builds a Gazelle binary that incorporates all of the Gazelle
-# plugins for the languages that you use in your workspace. In this example, we
-# are only listing the Gazelle plugin for Swift from rules_swift_package_manager.
-gazelle_binary(
-    name = "gazelle_bin",
-    languages = [
-        "@rules_swift_package_manager//gazelle",
-    ],
-)
-
-# This target updates the Bazel build files for your project. Run this target
-# whenever you add or remove source files from your project. The
-# `swift_deps_info` repository is generated by `rules_swift_package_manager`. It
-# creates a target, `@swift_deps_info//:swift_deps_index`, that generates a JSON
-# file which maps Swift module names to their respective Bazel target.
-gazelle(
-    name = "update_build_files",
-    data = [
-        "@swift_deps_info//:swift_deps_index",
-    ],
-    extra_args = [
-        "-swift_dependency_index=$(location @swift_deps_info//:swift_deps_index)",
-    ],
-    gazelle = ":gazelle_bin",
-)
-```
-
-### 7. Create or update Bazel build files for your project.
-
-Generate/update the Bazel build files for your project by running the following:
-
-```sh
-bazel run //:update_build_files
-```
-
-### 8. Build and test your project.
+### 6. Build and test your project.
 
 Build and test your project.
 
 ```sh
 bazel test //...
 ```
 
-### 9. Check in `Package.swift`, `Package.resolved`, and `MODULE.bazel`.
+### 7. Check in `Package.swift`, `Package.resolved`, and `MODULE.bazel`.
 
 - The `Package.swift` file is used by `rules_swift_package_manager` to generate information about
   your project's dependencies.
 - The `Package.resolved` file specifies that exact versions of the downloaded dependencies that were
   identified.
 - The `MODULE.bazel` contains the declarations for your external dependencies.
 
-### 10. Start coding
+### 8. Start coding
 
 You are ready to start coding.
 
@@ -297,14 +247,6 @@ See [our document on using a Swift package registry](/docs/swift_package_registr
 
 The following are a few tips to consider as you work with your repository:
 
-- When you add or remove source files, run `bazel run //:update_build_files`. This will
-  create/update the Bazel build files in your project. It is designed to be fast and unobtrusive.
-- If things do not appear to be working properly, run the following:
-  - `bazel run //:update_build_files`
-- Do yourself a favor and create a Bazel target (e.g., `//:tidy`) that runs your repository
-  maintenance targets (e.g., `//:update_build_files`, formatting utilities)
-  in the proper order. If you are looking for an easy way to set this up, check out the
-  [`//:tidy` declaration in this repository](BUILD.bazel) and the documentation for the [tidy] macro.
 - Are you trying to use a Swift package and it just won't build under Bazel? If you can figure out
   how to fix it, you can patch the Swift package. Check out [our document on patching Swift packages].
 
@@ -317,6 +259,8 @@ The following are a few tips to consider as you work with your repository:
 [CI GitHub workflow]: .github/workflows/ci.yml
 [Gazelle plugin]: https://github.com/bazelbuild/bazel-gazelle/blob/master/extend.md
 [Gazelle]: https://github.com/bazelbuild/bazel-gazelle
+[Gazelle plugin for Swift]: https://github.com/cgrindel/swift_gazelle_plugin
+[Swift Gazelle plugin]: https://github.com/cgrindel/swift_gazelle_plugin
 [examples]: examples/
 [rules_apple]: https://github.com/bazelbuild/rules_apple
 [rules_spm]: https://github.com/cgrindel/rules_spm

docs/design/BUILD.bazel

@@ -3,55 +3,15 @@
 ## Table of Contents
 
 <!-- MARKDOWN TOC: BEGIN -->
-* [Why use Gazelle and Go?](#why-use-gazelle-and-go)
-* [Why split the implementation between Go and Starlark?](#why-split-the-implementation-between-go-and-starlark)
-  * [How does the Gazelle plugin for Go handle this?](#how-does-the-gazelle-plugin-for-go-handle-this)
-* [Is the same build file generation logic used for the Go/Gazelle and Starlark implementations?](#is-the-same-build-file-generation-logic-used-for-the-gogazelle-and-starlark-implementations)
-* [Does this replace rules_spm?](#does-this-replace-rules_spm)
-* [Can I migrate from rules_spm to `rules_swift_package_manager`?](#can-i-migrate-from-rules_spm-to-rules_swift_package_manager)
-* [Can I just manage my external Swift packages and not generate Bazel build files for my project?](#can-i-just-manage-my-external-swift-packages-and-not-generate-bazel-build-files-for-my-project)
+* [Does this replace [rules_spm]?](#does-this-replace-rules_spm)
+* [Where is the Swift gazelle plugin?](#where-is-the-swift-gazelle-plugin)
 * [After running `//:swift_update_pkgs`, I see a `.build` directory. What is it? Do I need it?](#after-running-swift_update_pkgs-i-see-a-build-directory-what-is-it-do-i-need-it)
-* [Does the Gazelle plugin run Swift package manager with every execution?](#does-the-gazelle-plugin-run-swift-package-manager-with-every-execution)
 * [Can I store the Swift dependency files in a sub-package (i.e., not in the root of the workspace)?](#can-i-store-the-swift-dependency-files-in-a-sub-package-ie-not-in-the-root-of-the-workspace)
-  * [Why does this happen?](#why-does-this-happen)
 * [How do I handle the error `Unable to resolve byName reference XXX in @swiftpkg_yyy.`?](#how-do-i-handle-the-error-unable-to-resolve-byname-reference-xxx-in-swiftpkg_yyy)
   * [How do I fix this issue?](#how-do-i-fix-this-issue)
   * [What is the cause of the error? Why can't `rules_swift_package_manager` handle this situation?](#what-is-the-cause-of-the-error-why-cant-rules_swift_package_manager-handle-this-situation)
   <!-- MARKDOWN TOC: END -->
 
-## Why use Gazelle and Go?
-
-The [Gazelle framework] provides lots of great features for generating Bazel build and Starlark
-files. Right now, the best way to leverage the framework is to write the plugin in Go.
-
-In addition, adoption of the Gazelle ecosystem has started to take off. There are [lots of useful
-plugins for other languages](https://github.com/bazelbuild/bazel-gazelle#supported-languages).
-Letting Gazelle generate and maintain Bazel build files is a real game changer for developer
-productivity.
-
-## Why split the implementation between Go and Starlark?
-
-As mentioned previously, the easiest way to implement a Gazelle plugin is to write it in Go. This
-works great for generating build files in the primary workspace. However, there is a chicken-and-egg
-problem when it comes time to generate build files in a repository rule. The repository rule needs
-to generate files during the [loading phase]. The Go toolchain and the Gazelle framework defined in
-the workspace are not available to the repository rule during this phase. So, one needs to either
-perform some gymnastics to build the Gazelle plugin (see below) or use a language/runtime that is
-guaranteed to be available during the loading phase. Since Starlark is available during the loading
-phase, the build file generation logic for the repository rules is implemented in Starlark.
-
-### How does the Gazelle plugin for Go handle this?
-
-In short, they assume that if you are using the Gazelle plugin for Go, then you must have a Go
-toolchain installed on the host system. In essence, they shell out and run Go from the system.
-
-## Is the same build file generation logic used for the Go/Gazelle and Starlark implementations?
-
-No. The Gazelle plugin inspects the Swift source files and the directory structure to determine the
-placement and content of the Bazel build files. The repository rules leverage information about the
-Swift packages (e.g., dump and describe JSON). However, both implementations use the
-`module_index.json` to resolve module references to Bazel targets for the external dependencies.
-
 ## Does this replace [rules_spm]?
 
 Yes. There are some [limitations with the rules_spm
@@ -63,14 +23,9 @@ features and improvements:
 - Build the external dependencies with [rules_swift].
 - Pin the exact versions for the direct and transitive dependencies.
 
-## Can I migrate from [rules_spm] to `rules_swift_package_manager`?
-
-Absolutely. A [migration guide from rules_spm](https://github.com/cgrindel/rules_swift_package_manager/issues/99) is
-on the roadmap.
+## Where is the Swift gazelle plugin?
 
-## Can I just manage my external Swift packages and not generate Bazel build files for my project?
-
-Yes. Just omit the `//:update_build_files` target that is mentioned in the [quickstart].
+It has moved to https://github.com/cgrindel/swift_gazelle_plugin.
 
 ## After running `//:swift_update_pkgs`, I see a `.build` directory. What is it? Do I need it?
 
@@ -80,28 +35,11 @@ commands. These commands result in a `.build` directory being created. The direc
 effect of running the Swift package manager commands. It can be ignored and should not be checked
 into source control. It is not used by the Gazelle plugin or the Starlark repository rules.
 
-## Does the Gazelle plugin run Swift package manager with every execution?
-
-No. The Gazelle plugin only executes the Swift package manager when run in `update-repos` mode. This
-mode only needs to be run when modifying your external dependencies (e.g., add/remove a dependency,
-update the version selection for a dependency). The `update` mode for the Gazelle plugin generates
-Bazel build files for your project. It uses information written to the `swift_deps_index.json` and
-the source files that exist in your project to generate the Bazel build files.
-
 ## Can I store the Swift dependency files in a sub-package (i.e., not in the root of the workspace)?
 
 Yes. The [vapor example] demonstrates storing the Swift dependency files in a sub-package called
 `swift`.
 
-### Why does this happen?
-
-This can happen with some Swift packages (e.g. `firebase-ios-sdk`). [rules_xcodeproj removes the
-`sandboxed` spawn
-strategy](https://github.com/MobileNativeFoundation/rules_xcodeproj/blob/6c186331c82f3cbc82e2e7fdfacb4873e409e094/xcodeproj/internal/templates/xcodeproj.bazelrc#L66-L68)
-in their default build configuration due to slow performance of the MacOS sandbox. The above bazelrc
-stanza adds it back. [An issue](https://github.com/cgrindel/rules_swift_package_manager/issues/712)
-exists tracking the work to allow these Swift packages to be built using the `local` spawn strategy.
-
 ## How do I handle the error `Unable to resolve byName reference XXX in @swiftpkg_yyy.`?
 
 tl;dr A transitive dependency uses a by-name product reference format that was deprecated in Swift
@@ -170,13 +108,8 @@ the new architecture:
 - As a result, `byName` lookups can only be resolved to the targets/products in the current package
   and to products in Swift packages where the identity exactly matches the product name.
 
-[--strategy_regexp]: https://bazel.build/reference/command-line-reference#flag--strategy_regexp
-[Gazelle framework]: https://github.com/bazelbuild/bazel-gazelle/blob/master/extend.md
 [Patch the Swift package]: /docs/patch_swift_package.md
-[loading phase]: https://bazel.build/run/build#loading
 [patch this file]: /docs/patch_swift_package.md
 [pusher-websocket-swift Package.swift]: https://github.com/pusher/pusher-websocket-swift/blob/886341f9dad453c9822f2525136ee2006a6c3c9e/Package.swift
-[quickstart]: https://github.com/cgrindel/rules_swift_package_manager/blob/main/README.md#quickstart
-[rules_spm]: https://github.com/cgrindel/rules_spm/
 [rules_swift]: https://github.com/bazelbuild/rules_swift
 [vapor example]: /examples/vapor_example