diff --git a/README.md b/README.md index 4b6dc23..66143e6 100644 --- a/README.md +++ b/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) + ## 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) diff --git a/doc/BUILD.bazel b/doc/BUILD.bazel index a0f118d..25c77c2 100644 --- a/doc/BUILD.bazel +++ b/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 diff --git a/doc/README.md b/doc/README.md index 9784a8a..fa2ae60 100644 --- a/doc/README.md +++ b/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) diff --git a/doc/providers_overview.md b/doc/providers_overview.md deleted file mode 100755 index 253e351..0000000 --- a/doc/providers_overview.md +++ /dev/null @@ -1,29 +0,0 @@ - -# Providers - -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. - -On this page: - - * [SwiftFormatInfo](#SwiftFormatInfo) - - - - -## SwiftFormatInfo - -
-SwiftFormatInfo(format_map)
-
- -Information about the files that were formatted. - -**FIELDS** - - -| Name | Description | -| :------------- | :------------- | -| format_map | A dict where the key is the original source File and the value is the formatted File. | - - diff --git a/doc/repository_rules_overview.md b/doc/repository_rules_overview.md new file mode 100755 index 0000000..b3ade65 --- /dev/null +++ b/doc/repository_rules_overview.md @@ -0,0 +1,32 @@ + +# 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) + + + + +## swiftformat_load_package + +
+swiftformat_load_package(version)
+
+ +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 | +| :------------- | :------------- | :------------- | +| version | Optional. A valid semver string for SwiftFormat. | None | + + diff --git a/examples/simple/WORKSPACE b/examples/simple/WORKSPACE index 4370482..9640eb2 100644 --- a/examples/simple/WORKSPACE +++ b/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") diff --git a/swiftformat/BUILD.bazel b/swiftformat/BUILD.bazel index 277375e..8939989 100644 --- a/swiftformat/BUILD.bazel +++ b/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", diff --git a/swiftformat/deps.bzl b/swiftformat/deps.bzl index 772f7ce..91aaa72 100644 --- a/swiftformat/deps.bzl +++ b/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( diff --git a/swiftformat/internal/BUILD.bazel b/swiftformat/internal/BUILD.bazel index ac651c8..5cc1cdc 100644 --- a/swiftformat/internal/BUILD.bazel +++ b/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", ], diff --git a/swiftformat/internal/providers.bzl b/swiftformat/internal/providers.bzl deleted file mode 100644 index b2b6c83..0000000 --- a/swiftformat/internal/providers.bzl +++ /dev/null @@ -1,9 +0,0 @@ -SwiftFormatInfo = provider( - doc = "Information about the files that were formatted.", - fields = { - "format_map": """\ -A `dict` where the key is the original source `File` and the value is the \ -formatted `File`.\ -""", - }, -) diff --git a/swiftformat/load_package.bzl b/swiftformat/load_package.bzl index c355fd2..c1fa359 100644 --- a/swiftformat/load_package.bzl +++ b/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)"], ) diff --git a/swiftformat/swiftformat.bzl b/swiftformat/swiftformat.bzl index ae26ccc..35d9f32 100644 --- a/swiftformat/swiftformat.bzl +++ b/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