feat: introduce swift_update_packages macro (#144)

- Add `swift_update_packages_to_latest` flag to Gazelle extension. When enabled, it runs `swift package update` instead of `swift package resolve` during `update-repos`. - Introduce `swift_update_packages` macro to define variants of the `gazelle` declaration for `update-repos`. One performs the resolve and the other the update. Closes #137.
cgrindel · Jan 12, 2023 · a2a53f4 · a2a53f4
1 parent 41a0d21
commit a2a53f4
Show file tree

Hide file tree

Showing 25 changed files with 194 additions and 152 deletions.
diff --git a/README.md b/README.md
@@ -179,6 +179,7 @@ Add the following to the `BUILD.bazel` file at the root of your workspace.
 
 ```python
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 # Ignore the `.build` folder that is created by running Swift package manager 
 # commands. The Swift Gazelle plugin executes some Swift package manager 
@@ -201,18 +202,18 @@ gazelle_binary(
     ],
 )
 
-# This target should be run whenever the list of external dependencies is 
-# updated in the `Package.swift`. Running this target will populate the 
-# `swift_deps.bzl` with `swift_package` declarations for all of the direct and 
-# transitive Swift packages that your project uses.
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+# This macro defines two targets: `swift_update_pkgs` and 
+# `swift_update_pkgs_to_latest`. 
+#
+# The `swift_update_pkgs` target should be run whenever the list of external 
+# dependencies is updated in the `Package.swift`. Running this target will 
+# populate the `swift_deps.bzl` with `swift_package` declarations for all of 
+# the direct and transitive Swift packages that your project uses.
+# 
+# The `swift_update_pkgs_to_latest` target should be run when you want to 
+# update your Swift dependencies to their latest eligible version.
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 
@@ -229,7 +230,7 @@ gazelle(
 Resolve the external dependencies for your project by running the following:
 
 ```sh
-$ bazel run //:swift_update_repos
+$ bazel run //:swift_update_pkgs
 ```
 
 ### 5. Create or update Bazel build files for your project.
@@ -255,7 +256,7 @@ generated for you.
 
 - The `Package.resolved` file specifies that exact versions of the dependencies that were
   identified. If you do not keep the `Package.resolved` file, the dependencies written to the
-  `swift_deps.bzl` could change when you execute `//:swift_update_repos`.
+  `swift_deps.bzl` could change when you execute `//:swift_update_pkgs`.
 - The `swift_deps.bzl` contains the Bazel repository rule declarations that load your external
   dependencies for the Bazel build.
 - The `module_index.json` maps module names to targets that provide a module with that name. This
@@ -269,14 +270,14 @@ 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.
-- When you add or remove an external dependency, run `bazel run //:swift_update_repos`. This
+- When you add or remove an external dependency, run `bazel run //:swift_update_pkgs`. This
   will resolve the changes to your transitive dependencies and regenerate your `Package.resolved`
   and `module_index.json`.
 - If things do not appear to be working properly, run the following in this order:
-  - `bazel run //:swift_update_repos`
+  - `bazel run //:swift_update_pkgs`
   - `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., `//:swift_update_repos`, `//:update_build_files`, formatting utilities) 
+  maintenance targets (e.g., `//:swift_update_pkgs`, `//: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. 
 

diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -1,7 +1,6 @@
 load(
     "@cgrindel_bazel_starlib//bazeldoc:defs.bzl",
     "doc_for_provs",
-    "write_header",
     doc_providers = "providers",
 )
 load("@cgrindel_bazel_starlib//bzlformat:defs.bzl", "bzlformat_pkg")
@@ -14,10 +13,14 @@ markdown_pkg(name = "markdown")
 # MARK: - Documentation Declarations
 
 _DOC_WITH_SYMBOLS = {
-    "repository_rules": [
-        "local_swift_package",
-        "swift_package",
-    ],
+    # GH143: Enable once bazel-gazelle deps are fixed.
+    # "macros": [
+    #     "swift_update_packages",
+    # ],
+    # "repository_rules": [
+    #     "local_swift_package",
+    #     "swift_package",
+    # ],
 }
 
 _ALL_DOC_PROVIDERS = [
@@ -35,17 +38,32 @@ _ALL_DOC_PROVIDERS = [
 
 # MARK: - Headers
 
-write_header(
-    name = "repository_rules_overview_header",
-    header_content = [
-        "# Repository Rules",
-        "",
-        """
-The rules described below are used to build Swift packages and make their 
-products and targets available as Bazel targets.
-""",
-    ],
-    symbols = _DOC_WITH_SYMBOLS["repository_rules"],
-)
+# GH143: Enable once bazel-gazelle deps are fixed.
+# write_header(
+#     name = "repository_rules_overview_header",
+#     header_content = [
+#         "# Repository Rules",
+#         "",
+#         """
+# The rules described below are used to build Swift packages and make their
+# products and targets available as Bazel targets.
+# """,
+#     ],
+#     symbols = _DOC_WITH_SYMBOLS["repository_rules"],
+# )
+
+# GH143: Enable once bazel-gazelle deps are fixed.
+# write_header(
+#     name = "macros_overview_header",
+#     header_content = [
+#         "# Macros",
+#         "",
+#         """
+# The macros described below are used to define Gazelle targets to aid in the \
+# generation and maintenance of Swift package dependencies.
+# """,
+#     ],
+#     symbols = _DOC_WITH_SYMBOLS["macros"],
+# )
 
 doc_for_provs(doc_provs = _ALL_DOC_PROVIDERS)
diff --git a/docs/faq.md b/docs/faq.md
@@ -10,7 +10,7 @@
 * [Does this replace rules\_spm ?](https://github.com/cgrindel/rules_spm/)
 * [Can I migrate from rules\_spm to swift\_bazel ?](https://github.com/cgrindel/rules_spm/)
 * [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)
-* [After running //:swift\_update\_repos , I see a \.build directory\. What is it? Do I need it?](#after-running-swift_update_repos-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?](#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)
 <!-- MARKDOWN TOC: END -->
 
@@ -67,9 +67,9 @@ on the roadmap.
 
 Yes. Just omit the `//:update_build_files` target that is mentioned in the [quickstart].
 
-## After running `//:swift_update_repos`, 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?
 
-The `//:swift_update_repos` target runs the Gazelle plugin in `update-repos` mode. This mode
+The `//:swift_update_pkgs` target runs the Gazelle plugin in `update-repos` mode. This mode
 resolves the external dependencies listed in your `Package.swift` by running Swift package manager
 commands.  These commands result in a `.build` directory being created. The directory is a side
 effect of running the Swift package manager commands. It can be ignored and should not be checked

diff --git a/examples/interesting_deps/BUILD.bazel b/examples/interesting_deps/BUILD.bazel
@@ -2,11 +2,12 @@ load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@build_bazel_rules_swift//swift:swift.bzl", "swift_binary")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -29,14 +30,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/interesting_deps/set_up_clean_test b/examples/interesting_deps/set_up_clean_test
@@ -22,11 +22,12 @@ load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@build_bazel_rules_swift//swift:swift.bzl", "swift_binary")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -49,14 +50,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/ios_sim/BUILD.bazel b/examples/ios_sim/BUILD.bazel
@@ -1,11 +1,12 @@
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -28,14 +29,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/ios_sim/set_up_clean_test b/examples/ios_sim/set_up_clean_test
@@ -24,11 +24,12 @@ cat > "${script_dir}/BUILD.bazel"  <<-EOF
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -51,14 +52,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/objc_code/BUILD.bazel b/examples/objc_code/BUILD.bazel
@@ -2,11 +2,12 @@ load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@build_bazel_rules_swift//swift:swift.bzl", "swift_binary")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -29,14 +30,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/objc_code/set_up_clean_test b/examples/objc_code/set_up_clean_test
@@ -24,11 +24,12 @@ cat > "${script_dir}/BUILD.bazel"  <<-EOF
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -51,14 +52,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/pkg_manifest_minimal/BUILD.bazel b/examples/pkg_manifest_minimal/BUILD.bazel
@@ -1,11 +1,12 @@
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@cgrindel_bazel_starlib//bzltidy:defs.bzl", "tidy")
+load("@cgrindel_swift_bazel//swiftpkg:defs.bzl", "swift_update_packages")
 
 tidy(
     name = "tidy",
     targets = [
-        ":swift_update_repos",
+        ":swift_update_pkgs",
         ":update_build_files",
     ],
 )
@@ -28,14 +29,8 @@ gazelle(
     gazelle = ":gazelle_bin",
 )
 
-gazelle(
-    name = "swift_update_repos",
-    args = [
-        "-from_file=Package.swift",
-        "-to_macro=swift_deps.bzl%swift_dependencies",
-        "-prune",
-    ],
-    command = "update-repos",
+swift_update_packages(
+    name = "swift_update_pkgs",
     gazelle = ":gazelle_bin",
 )
 

diff --git a/examples/pkg_manifest_minimal/Package.resolved b/examples/pkg_manifest_minimal/Package.resolved
@@ -23,8 +23,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/nicklockwood/SwiftFormat",
       "state" : {
-        "revision" : "da637c398c5d08896521b737f2868ddc2e7996ae",
-        "version" : "0.50.6"
+        "revision" : "34cd9dd87b78048ce0d623a9153f9bf260ad6590",
+        "version" : "0.50.7"
       }
     }
   ],