Allow a client to select the release/version for SwiftFormat

README.md

@@ -6,6 +6,16 @@ This repository contains Bazel rules and macros that will format Swift source fi
 [nicklockwood/SwiftFormat](https://github.com/nicklockwood/SwiftFormat), test that the formatted
 files exist in the workspace directory, and copy the formatted files to the workspace directory.
 
+## Table of Contents
+
+* [Quickstart](#quickstart)
+  * [1\. Configure your workspace to use rules\_swiftformat](#1-configure-your-workspace-to-use-rules_swiftformat)
+  * [2\. Update the BUILD\.bazel at the root of your workspace](#2-update-the-buildbazel-at-the-root-of-your-workspace)
+  * [3\. Add swiftformat\_pkg to every Bazel package with Swift source files](#3-add-swiftformat_pkg-to-every-bazel-package-with-swift-source-files)
+  * [4\. Format, Update, and Test](#4-format-update-and-test)
+* [Specifying the Version of SwiftFormat](#specifying-the-version-of-swiftformat)
+* [Learn More](#learn-more)
+
 <a id="#quickstart"></a>
 ## Quickstart
 
@@ -131,6 +141,23 @@ $ bazel run //:update_all
 $ bazel test //...
 ```
 
+## Specifying the Version of SwiftFormat
+
+By default, `rules_swiftformat` will load the [latest release of
+SwiftFormat](https://github.com/nicklockwood/SwiftFormat/releases). This works well for most cases.
+However, if you would like to specify the SwiftFormat release, you can do so by passing the version
+to the [`swiftformat_load_package`](/doc/repository_rules_overview.md#swiftformat_load_package) function in your `WORKSPACE`.
+
+```python
+load("@cgrindel_rules_swiftformat//swiftformat:load_package.bzl", "swiftformat_load_package")
+
+swiftformat_load_package(version = "0.49.1")
+```
+
+One reason you may want to do so is to ensure that everyone working on your project is using the
+same version of SwiftFormat. Without the version specification, Bazel will cache whichever version
+was the latest when the project was run for the first time after the cache was cleared.
+
 ## Learn More
 
 - [How It Works](/doc/how_it_works.md)

doc/BUILD.bazel

@@ -9,15 +9,6 @@ load(
 
 # MARK: - Documentation Providers
 
-_PROVIDERS_DOC_PROVIDER = doc_providers.create(
-    name = "providers_overview",
-    stardoc_input = "//swiftformat:swiftformat.bzl",
-    symbols = [
-        "SwiftFormatInfo",
-    ],
-    deps = ["//swiftformat"],
-)
-
 _RULES_AND_MACROS_DOC_PROVIDER = doc_providers.create(
     name = "rules_and_macros_overview",
     stardoc_input = "//swiftformat:swiftformat.bzl",
@@ -31,6 +22,15 @@ _RULES_AND_MACROS_DOC_PROVIDER = doc_providers.create(
     deps = ["//swiftformat"],
 )
 
+_REPOSITORY_RULES_DOC_PROVIDER = doc_providers.create(
+    name = "repository_rules_overview",
+    stardoc_input = "//swiftformat:load_package.bzl",
+    symbols = [
+        "swiftformat_load_package",
+    ],
+    deps = ["//swiftformat:load_package"],
+)
+
 _API_SRCS = [
     "src_utils",
 ]
@@ -47,7 +47,7 @@ _API_DOC_PROVIDERS = [
 
 _ALL_DOC_PROVIDERS = [
     _RULES_AND_MACROS_DOC_PROVIDER,
-    _PROVIDERS_DOC_PROVIDER,
+    _REPOSITORY_RULES_DOC_PROVIDER,
     doc_providers.create(
         name = "api",
         is_stardoc = False,
@@ -59,25 +59,25 @@ _ALL_DOC_PROVIDERS = [
 # MARK: - Headers
 
 write_header(
-    name = _PROVIDERS_DOC_PROVIDER.header_label,
+    name = _RULES_AND_MACROS_DOC_PROVIDER.header_label,
     header_content = [
-        "# Providers",
+        "# Rules and Macros",
         "",
-        "The providers described below are used by [the rules](/doc/rules_and_macros_overview.md) to",
-        "pass along information about the source files and the formatted files.",
+        "The rules and macros described below are used to format, test and ",
+        "copy Swift source files.",
     ],
-    symbols = _PROVIDERS_DOC_PROVIDER.symbols,
+    symbols = _RULES_AND_MACROS_DOC_PROVIDER.symbols,
 )
 
 write_header(
-    name = _RULES_AND_MACROS_DOC_PROVIDER.header_label,
+    name = _REPOSITORY_RULES_DOC_PROVIDER.header_label,
     header_content = [
-        "# Rules and Macros",
+        "# Repository Rules and Macros",
         "",
-        "The rules and macros described below are used to format, test and ",
-        "copy Swift source files.",
+        "The rules and macros described below are used to configure and download ",
+        "dependencies for rules_swiftformat.",
     ],
-    symbols = _RULES_AND_MACROS_DOC_PROVIDER.symbols,
+    symbols = _REPOSITORY_RULES_DOC_PROVIDER.symbols,
 )
 
 # Write the API headers

doc/README.md

@@ -13,5 +13,5 @@
 ## Reference Documentation
 
 - [Rules and Macros](/doc/rules_and_macros_overview.md)
-- [Providers](/doc/providers_overview.md)
+- [Repository Rules and Macros](/doc/repository_rules_overview.md)
 - [APIs](/doc/api.md)

doc/repository_rules_overview.md

@@ -0,0 +1,32 @@
+<!-- Generated with Stardoc, Do Not Edit! -->
+# Repository Rules and Macros
+
+The rules and macros described below are used to configure and download 
+dependencies for rules_swiftformat.
+
+On this page:
+
+  * [swiftformat_load_package](#swiftformat_load_package)
+
+
+<a id="#swiftformat_load_package"></a>
+
+## swiftformat_load_package
+
+<pre>
+swiftformat_load_package(<a href="#swiftformat_load_package-version">version</a>)
+</pre>
+
+Loads SwiftFormat using Swift Package Manager via `rules_spm`.
+
+If a version is not specified, Swift Package Manager will be configured to     load the latest release.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="swiftformat_load_package-version"></a>version |  Optional. A valid semver <code>string</code> for SwiftFormat.   |  <code>None</code> |
+
+

examples/simple/WORKSPACE

@@ -39,4 +39,4 @@ swift_rules_extra_dependencies()
 
 load("@cgrindel_rules_swiftformat//swiftformat:load_package.bzl", "swiftformat_load_package")
 
-swiftformat_load_package()
+swiftformat_load_package(version = "0.49.1")

swiftformat/BUILD.bazel

@@ -9,6 +9,11 @@ bzlformat_pkg(
     update_visibility = ["//:__subpackages__"],
 )
 
+bzl_library(
+    name = "bazel_tools_repo_utils",
+    srcs = ["@bazel_tools//tools/build_defs/repo:utils.bzl"],
+)
+
 bzl_library(
     name = "deps",
     srcs = ["deps.bzl"],
@@ -17,13 +22,16 @@ bzl_library(
 bzl_library(
     name = "load_package",
     srcs = ["load_package.bzl"],
+    deps = [
+        ":bazel_tools_repo_utils",
+        "@cgrindel_rules_spm//spm:defs",
+    ],
 )
 
 bzl_library(
     name = "swiftformat",
     srcs = ["swiftformat.bzl"],
     deps = [
-        "//swiftformat/internal:providers",
         "//swiftformat/internal:src_utils",
         "//swiftformat/internal:swiftformat_binary",
         "//swiftformat/internal:swiftformat_format",

swiftformat/deps.bzl

@@ -13,22 +13,23 @@ def swiftformat_rules_dependencies():
         sha256 = "c6966ec828da198c5d9adbaa94c05e3a1c7f21bd012a0b29ba8ddbccb2c93b0d",
     )
 
-    maybe(
-        http_archive,
+    http_archive(
         name = "cgrindel_bazel_starlib",
-        sha256 = "238c05abf31447b93bd15b616c7413c4c719ee7b5e81c1489ca20f02ce628489",
-        strip_prefix = "bazel-starlib-0.2.0",
+        sha256 = "5b36e7f11bf0c1d52480f1b022430611b402b5424979f280f13c52550de76584",
+        strip_prefix = "bazel-starlib-0.3.0",
         urls = [
-            "http://github.com/cgrindel/bazel-starlib/archive/v0.2.0.tar.gz",
+            "http://github.com/cgrindel/bazel-starlib/archive/v0.3.0.tar.gz",
         ],
     )
 
     maybe(
         http_archive,
         name = "cgrindel_rules_spm",
-        sha256 = "fab28a41793744f3944ad2606cdd9c0f8e2f4861dd29fb1d61aa4263c7a1400a",
-        strip_prefix = "rules_spm-0.6.0",
-        urls = ["https://github.com/cgrindel/rules_spm/archive/v0.6.0.tar.gz"],
+        sha256 = "cbe5d5dccdc8d5aa300e1538c4214f44a1266895d9817e8279a9335bcbee2f1e",
+        strip_prefix = "rules_spm-0.7.0",
+        urls = [
+            "http://github.com/cgrindel/rules_spm/archive/v0.7.0.tar.gz",
+        ],
     )
 
     maybe(

swiftformat/internal/BUILD.bazel

@@ -9,11 +9,6 @@ bzlformat_pkg(
     update_visibility = ["//:__subpackages__"],
 )
 
-bzl_library(
-    name = "providers",
-    srcs = ["providers.bzl"],
-)
-
 bzl_library(
     name = "src_utils",
     srcs = ["src_utils.bzl"],
@@ -23,7 +18,6 @@ bzl_library(
     name = "swiftformat_format",
     srcs = ["swiftformat_format.bzl"],
     deps = [
-        ":providers",
         "@bazel_skylib//lib:paths",
         "@cgrindel_bazel_starlib//updatesrc:defs",
     ],

swiftformat/load_package.bzl

@@ -1,16 +1,31 @@
 load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
-load("@cgrindel_rules_spm//spm:spm.bzl", "spm_pkg", "spm_repositories")
+load("@cgrindel_rules_spm//spm:defs.bzl", "spm_pkg", "spm_repositories")
+
+def swiftformat_load_package(version = None):
+    """Loads SwiftFormat using Swift Package Manager via `rules_spm`.
+
+    If a version is not specified, Swift Package Manager will be configured to \
+    load the latest release.
+
+    Args:
+        version: Optional. A valid semver `string` for SwiftFormat.
+    """
+    spm_pkg_args = {
+        "url": "https://github.com/nicklockwood/SwiftFormat.git",
+        "products": ["swiftformat"],
+    }
+    if version == None:
+        # Load the latest 0.x.x version of SwiftFormat.
+        spm_pkg_args["from_version"] = "0.0.0"
+    else:
+        # Load the specified version of SwiftFormat
+        spm_pkg_args["exact_version"] = version
 
-def swiftformat_load_package():
     maybe(
         spm_repositories,
         name = "swiftformat_repos",
         dependencies = [
-            spm_pkg(
-                "https://github.com/nicklockwood/SwiftFormat.git",
-                from_version = "0.0.0",
-                products = ["swiftformat"],
-            ),
+            spm_pkg(**spm_pkg_args),
         ],
         platforms = [".macOS(.v10_12)"],
     )

swiftformat/swiftformat.bzl

@@ -6,10 +6,6 @@ load(
     "//swiftformat/internal:swiftformat_format.bzl",
     _swiftformat_format = "swiftformat_format",
 )
-load(
-    "//swiftformat/internal:providers.bzl",
-    _SwiftFormatInfo = "SwiftFormatInfo",
-)
 load(
     "//swiftformat/internal:swiftformat_library.bzl",
     _swiftformat_library = "swiftformat_library",
@@ -36,8 +32,5 @@ swiftformat_test = _swiftformat_test
 # Rules
 swiftformat_format = _swiftformat_format
 
-# Providers
-SwiftFormatInfo = _SwiftFormatInfo
-
 # APIs
 src_utils = _src_utils