Skip to content

Commit 94bcc4f

Browse files
cgrindelcgrindel
authored
docs: update documentation (#93)
- Document settings for Linux users. - Document how to specify the SwiftFormat version. - Document how to generate the declaration for a SwiftFormat version. Closes #88.
1 parent 48302fa commit 94bcc4f

File tree

5 files changed

+128
-26
lines changed

5 files changed

+128
-26
lines changed

‎README.md

Lines changed: 90 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ files exist in the workspace directory, and copy the formatted files to the work
1313
* [2\. Update the BUILD\.bazel at the root of your workspace](#2-update-the-buildbazel-at-the-root-of-your-workspace)
1414
* [3\. Add swiftformat\_pkg to every Bazel package with Swift source files](#3-add-swiftformat_pkg-to-every-bazel-package-with-swift-source-files)
1515
* [4\. Format, Update, and Test](#4-format-update-and-test)
16-
* [Specifying the Version of SwiftFormat](#specifying-the-version-of-swiftformat)
16+
* [Specifying the SwiftFormat Version](#specifying-the-swiftformat-version)
17+
* [Special Instructions for Linux Users](#special-instructions-for-linux-users)
1718
* [Learn More](#learn-more)
1819

1920
<a id="#quickstart"></a>
@@ -40,15 +41,11 @@ http_archive(
4041
)
4142
load(
4243
"//swiftformat:deps.bzl",
43-
"swiftformat_register_toolchains",
4444
"swiftformat_rules_dependencies",
4545
)
4646

4747
swiftformat_rules_dependencies()
4848

49-
# Specify the version of SwiftFormat that you want to use
50-
swiftformat_register_toolchains(version = "0.51.10")
51-
5249
# Configure the dependencies for rules_swiftformat
5350

5451
load(
@@ -71,6 +68,13 @@ load(
7168
)
7269

7370
swift_rules_extra_dependencies()
71+
72+
load(
73+
"@cgrindel_rules_swiftformat//swiftformat:defs.bzl",
74+
"swiftformat_register_prebuilt_toolchains",
75+
)
76+
77+
swiftformat_register_prebuilt_toolchains()
7478
```
7579
<!-- END WORKSPACE SNIPPET -->
7680

@@ -114,9 +118,7 @@ load(
114118
"swiftformat_pkg",
115119
)
116120

117-
swiftformat_pkg(
118-
name = "swiftformat",
119-
)
121+
swiftformat_pkg(name = "swiftformat")
120122
```
121123

122124
The [`swiftformat_pkg`](/doc/rules_and_macros_overview.md#swiftformat_pkg) macro defines targets for
@@ -136,22 +138,93 @@ $ bazel run //:update_all
136138
$ bazel test //...
137139
```
138140

139-
## Specifying the Version of SwiftFormat
141+
## Specifying the SwiftFormat Version
140142

141-
By default, `rules_swiftformat` will load the [latest release of
143+
By default, `rules_swiftformat` will load a [recent release of
142144
SwiftFormat](https://github.com/nicklockwood/SwiftFormat/releases). This works well for most cases.
143-
However, if you would like to specify the SwiftFormat release, you can do so by passing the version
144-
to the [`swiftformat_load_package`](/doc/repository_rules_overview.md#swiftformat_load_package) function in your `WORKSPACE`.
145+
However, if you would like to specify the SwiftFormat release, you can do so by specifying the
146+
assets to download when calling [`swiftformat_register_prebuilt_toolchains`](/doc/repository_rules_overview.md#swiftformat_register_prebuilt_toolchains) function in your `WORKSPACE`.
145147

146148
```python
147-
load("@cgrindel_rules_swiftformat//swiftformat:load_package.bzl", "swiftformat_load_package")
149+
swiftformat_register_prebuilt_toolchains(
150+
assets = [
151+
prebuilt_assets.create_swiftformat(
152+
version = "0.51.11",
153+
os = "macos",
154+
cpu = "x86_64",
155+
file = "swiftformat",
156+
sha256 = "e565ebf6c54ee8e1ac83e4974edae34e002f86eda358a5838c0171f32f00ab20",
157+
),
158+
# Other declarations...
159+
],
160+
)
161+
```
162+
163+
To make this easier, this repository includes a tool called `generate_assets_declaration`. Executing
164+
this tool will generate the appropriate declaration to download and configure the desired version of
165+
SwiftFormat.
166+
167+
```sh
168+
# Specify the desired SwiftFormat version
169+
$ bazel run //tools:generate_assets_declaration -- "0.51.11"
170+
load(
171+
"@cgrindel_rules_swiftformat//swiftformat:defs.bzl",
172+
"swiftformat_register_prebuilt_toolchains",
173+
"prebuilt_assets",
174+
)
175+
176+
swiftformat_register_prebuilt_toolchains(
177+
assets = [
178+
prebuilt_assets.create_swiftformat(
179+
version = "0.51.11",
180+
os = "macos",
181+
cpu = "x86_64",
182+
file = "swiftformat",
183+
sha256 = "e565ebf6c54ee8e1ac83e4974edae34e002f86eda358a5838c0171f32f00ab20",
184+
),
185+
prebuilt_assets.create_swiftformat(
186+
version = "0.51.11",
187+
os = "macos",
188+
cpu = "arm64",
189+
file = "swiftformat",
190+
sha256 = "e565ebf6c54ee8e1ac83e4974edae34e002f86eda358a5838c0171f32f00ab20",
191+
),
192+
prebuilt_assets.create_swiftformat(
193+
version = "0.51.11",
194+
os = "linux",
195+
cpu = "x86_64",
196+
file = "swiftformat_linux",
197+
sha256 = "a49b79d97c234ccb5bcd2064ffec868e93e2eabf2d5de79974ca3802d8e389ec",
198+
),
199+
],
200+
)
201+
```
202+
203+
## Special Instructions for Linux Users
204+
205+
By default, this ruleset downloads prebuilt binaries from
206+
[nicklockwood/SwiftFormat](https://github.com/nicklockwood/SwiftFormat). The Linux binaries provided
207+
by this website dynamically load certain shared libraries (e.g. Foundation). On Linux, Swift
208+
finds these libraries by searching the directories specified by the `LD_LIBRARY_PATH` envronment
209+
variable. Be sure to update this environment variable with the path to the shard libraries provided
210+
by the Swift SDK.
211+
212+
For instance, on Ubuntu, one might install Swift to `$HOME/swift-5.7.2-RELEASE-ubuntu22.04`. The
213+
shared library directory for this installation is
214+
`$HOME/swift-5.7.2-RELEASE-ubuntu22.04/usr/lib/swift/linux`.
215+
216+
In addition to setting the `LD_LIBRARY_PATH` environment variable, you must tell Bazel to provide
217+
this value to its actions. This is done by using the `--action_env` flag. Update the `.bazelrc` file
218+
for your project to include the following:
148219

149-
swiftformat_load_package(version = "0.49.1")
150220
```
221+
# Need to expose the PATH so that the Swift toolchain can be found
222+
build --action_env=PATH
151223
152-
One reason you may want to do so is to ensure that everyone working on your project is using the
153-
same version of SwiftFormat. Without the version specification, Bazel will cache whichever version
154-
was the latest when the project was run for the first time after the cache was cleared.
224+
# Need to expose the LD_LIBRARY_PATH so that the Swift dynamic loaded
225+
# so files can be found
226+
build --action_env=LD_LIBRARY_PATH
227+
```
155228

156229
## Learn More
157230

‎doc/BUILD.bazel

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ _RULES_AND_MACROS_DOC_PROVIDER = doc_providers.create(
1717
"swiftformat_format",
1818
"swiftformat_library",
1919
"swiftformat_pkg",
20+
"swiftformat_register_prebuilt_toolchains",
2021
"swiftformat_test",
2122
],
2223
deps = ["//swiftformat"],

‎doc/rules_and_macros_overview.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ On this page:
1010
* [swiftformat_format](#swiftformat_format)
1111
* [swiftformat_library](#swiftformat_library)
1212
* [swiftformat_pkg](#swiftformat_pkg)
13+
* [swiftformat_register_prebuilt_toolchains](#swiftformat_register_prebuilt_toolchains)
1314
* [swiftformat_test](#swiftformat_test)
1415

1516

@@ -110,6 +111,26 @@ NOTE: Any labels detected in the `srcs` will be ignored.
110111
| <a id="swiftformat_pkg-config"></a>config | Optional. The swiftformat YAML configuration file. | <code>None</code> |
111112

112113

114+
<a id="swiftformat_register_prebuilt_toolchains"></a>
115+
116+
## swiftformat_register_prebuilt_toolchains
117+
118+
<pre>
119+
swiftformat_register_prebuilt_toolchains(<a href="#swiftformat_register_prebuilt_toolchains-name">name</a>, <a href="#swiftformat_register_prebuilt_toolchains-assets">assets</a>, <a href="#swiftformat_register_prebuilt_toolchains-register_toolchains">register_toolchains</a>)
120+
</pre>
121+
122+
Register and configure the toolchains to download pre-built SwiftFormat binaries.
123+
124+
**PARAMETERS**
125+
126+
127+
| Name | Description | Default Value |
128+
| :------------- | :------------- | :------------- |
129+
| <a id="swiftformat_register_prebuilt_toolchains-name"></a>name | Optional. The name for the toolchains repository as a <code>string</code>. | <code>"swiftformat_prebuilt_toolchains"</code> |
130+
| <a id="swiftformat_register_prebuilt_toolchains-assets"></a>assets | Optional. A <code>list</code> of tools to register. If not specified, it uses a recent version of SwiftFormat. | <code>None</code> |
131+
| <a id="swiftformat_register_prebuilt_toolchains-register_toolchains"></a>register_toolchains | Optional. A <code>bool</code> that determines whether this function should call <code>register_toolchains()</code>. | <code>True</code> |
132+
133+
113134
<a id="swiftformat_test"></a>
114135

115136
## swiftformat_test

‎release/workspace_snippet.tmpl

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,11 @@ ${http_archive_statement}
44

55
load(
66
"@cgrindel_rules_swiftformat//swiftformat:deps.bzl",
7-
"swiftformat_register_toolchains",
87
"swiftformat_rules_dependencies",
98
)
109

1110
swiftformat_rules_dependencies()
1211

13-
# Specify the version of SwiftFormat that you want to use
14-
swiftformat_register_toolchains(version = "0.51.10")
15-
1612
# Configure the dependencies for rules_swiftformat
1713

1814
load(
@@ -35,3 +31,10 @@ load(
3531
)
3632

3733
swift_rules_extra_dependencies()
34+
35+
load(
36+
"@cgrindel_rules_swiftformat//swiftformat:defs.bzl",
37+
"swiftformat_register_prebuilt_toolchains",
38+
)
39+
40+
swiftformat_register_prebuilt_toolchains()

‎swiftformat/toolchains/toolchain.bzl

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,16 +103,20 @@ _swiftformat_toolchain_setup = repository_rule(
103103

104104
def swiftformat_register_prebuilt_toolchains(
105105
name = "swiftformat_prebuilt_toolchains",
106-
assets = DEFAULT_ASSETS,
106+
assets = None,
107107
register_toolchains = True):
108-
"""Register the toolchains for SwiftFormat.
108+
"""Register and configure the toolchains to download pre-built SwiftFormat \
109+
binaries.
109110
110111
Args:
111-
name: The name for the toolchains repository as a `string`.
112-
assets: A `list` of tools to register.
112+
name: Optional. The name for the toolchains repository as a `string`.
113+
assets: Optional. A `list` of tools to register. If not specified, it
114+
uses a recent version of SwiftFormat.
113115
register_toolchains: Optional. A `bool` that determines whether this
114-
function should call `register_toolchains()`
116+
function should call `register_toolchains()`.
115117
"""
118+
if assets == None:
119+
assets = DEFAULT_ASSETS
116120
toolchain_labels = []
117121
for asset in assets:
118122
toolchain_label = "@{repo}//:{name}".format(

0 commit comments

Comments
 (0)