@zio.dev/zio-sbt 0.4.0-alpha.1 → 0.4.0-alpha.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/index.md +163 -13
- package/package.json +1 -1
package/index.md
CHANGED
|
@@ -3,7 +3,7 @@ id: index
|
|
|
3
3
|
title: "ZIO SBT"
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
_ZIO SBT_
|
|
6
|
+
_ZIO SBT_ contains multiple sbt plugins that are useful for ZIO projects. It provides high-level SBT utilities that simplify the development of ZIO applications.
|
|
7
7
|
|
|
8
8
|
[](https://github.com/zio/zio/wiki/Project-Stages)  [](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-sbt-website_2.12/) [](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-sbt-website_2.12/) [](https://javadoc.io/doc/dev.zio/zio-sbt-docs_2.12) [](https://github.com/zio/zio-sbt)
|
|
9
9
|
|
|
@@ -12,15 +12,69 @@ _ZIO SBT_ is an sbt plugin for ZIO projects. It provides high-level SBT utilitie
|
|
|
12
12
|
Add the following lines to your `plugin.sbt` file:
|
|
13
13
|
|
|
14
14
|
```scala
|
|
15
|
-
addSbtPlugin("dev.zio" % "zio-sbt-
|
|
15
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ecosystem" % "0.4.0-alpha.12")
|
|
16
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.4.0-alpha.12")
|
|
17
|
+
addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.4.0-alpha.12")
|
|
16
18
|
```
|
|
17
19
|
|
|
18
|
-
Then you can enable
|
|
20
|
+
Then you can enable them by using the following code in your `build.sbt` file:
|
|
19
21
|
|
|
20
22
|
```scala
|
|
21
|
-
enablePlugins(
|
|
23
|
+
enablePlugins(
|
|
24
|
+
ZioSbtWebsitePlugin,
|
|
25
|
+
ZioSbtEcosystemPlugin,
|
|
26
|
+
ZioSbtCiPlugin
|
|
27
|
+
)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## ZIO SBT Ecosystem
|
|
31
|
+
|
|
32
|
+
ZIO SBT Ecosystem plugin is an sbt plugin that provides a set of sbt settings and tasks that are very common and useful for configuring and managing ZIO projects. It is designed help developers to quickly set up a new ZIO project with a minimal amount of effort.
|
|
33
|
+
|
|
34
|
+
This pluging provides the following settings with default values:
|
|
35
|
+
|
|
36
|
+
- scala211
|
|
37
|
+
- scala212
|
|
38
|
+
- scala213
|
|
39
|
+
- scala3
|
|
40
|
+
|
|
41
|
+
The default values are the latest stable versions of Scala 2.11, 2.12, 2.13, and Scala 3. All of these settings are of type `String` and can be overridden by the user.
|
|
42
|
+
|
|
43
|
+
By having these settings, then we can use them in other sbt settings. For example, we can use them to define the `crossScalaVersions` setting:
|
|
44
|
+
|
|
45
|
+
```scala
|
|
46
|
+
crossScalaVersions := Seq(scala211.value, scala212.value, scala213.value, scala3.value)
|
|
22
47
|
```
|
|
23
48
|
|
|
49
|
+
There are also some other settings that are useful for configuring the projects:
|
|
50
|
+
|
|
51
|
+
- `stdSettings`— a set of standard settings which are common for every ZIO project, which includes configuring:
|
|
52
|
+
- silencer plugin
|
|
53
|
+
- kind projector plugin
|
|
54
|
+
- cross project plugin
|
|
55
|
+
- scalafix plugin
|
|
56
|
+
- java target platform
|
|
57
|
+
- `enableZIO`- a set of ZIO related settings such as enabling zio streams and ZIO test framework.
|
|
58
|
+
- `jsSettings`, `nativeSettings`- common platform specific settings for Scala.js and Scala Native.
|
|
59
|
+
|
|
60
|
+
It also provides some helper methods that are useful for configuring a compiler option for a specific Scala version:
|
|
61
|
+
|
|
62
|
+
- `optionsOn`
|
|
63
|
+
- `optionsOnExcept`
|
|
64
|
+
- `optionsOnOrElse`
|
|
65
|
+
- `addOptionsOn`
|
|
66
|
+
- `addOptionsOnOrElse`
|
|
67
|
+
- `addOptionsOnExcept`
|
|
68
|
+
|
|
69
|
+
And the same for adding a dependency for a specific Scala version:
|
|
70
|
+
|
|
71
|
+
- `dependenciesOn`
|
|
72
|
+
- `dependenciesOnExcept`
|
|
73
|
+
- `dependenciesOnOrElse`
|
|
74
|
+
- `addDependenciesOn`
|
|
75
|
+
- `addDependenciesOnExcept`
|
|
76
|
+
- `addDependenciesOnOrElse`
|
|
77
|
+
|
|
24
78
|
## ZIO SBT Website
|
|
25
79
|
|
|
26
80
|
ZIO SBT Website is an SBT plugin that has the following tasks:
|
|
@@ -29,7 +83,6 @@ ZIO SBT Website is an SBT plugin that has the following tasks:
|
|
|
29
83
|
- `sbt installWebsite`— creates a website for the project inside the `website` directory.
|
|
30
84
|
- `sbt previewWebsite`— runs a local webserver that serves documentation locally on http://localhost:3000. By changing the documentation inside the `docs` directory, the website will be reloaded with new content.
|
|
31
85
|
- `sbt publishToNpm`— publishes documentation inside the `docs` directory to the npm registry.
|
|
32
|
-
- `sbt generateGithubWorkflow`— generates GitHub workflow which publishes documentation for each library release.
|
|
33
86
|
- `sbt generateReadme`— generate README.md file from `docs/index.md` and sbt setting keys.
|
|
34
87
|
|
|
35
88
|
## ZIO SBT CI Plugin
|
|
@@ -45,7 +98,7 @@ ZIO SBT CI plugin generates a default GitHub workflow that includes common CI ta
|
|
|
45
98
|
To use ZIO SBT CI plugin, add the following lines to your `plugins.sbt` file:
|
|
46
99
|
|
|
47
100
|
```scala
|
|
48
|
-
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.4.0-alpha.
|
|
101
|
+
addSbtPlugin("dev.zio" % "zio-sbt-ci" % "0.4.0-alpha.12")
|
|
49
102
|
|
|
50
103
|
resolvers ++= Resolver.sonatypeOssRepos("public")
|
|
51
104
|
```
|
|
@@ -62,21 +115,73 @@ Now you can generate a Github workflow by running the following command:
|
|
|
62
115
|
sbt ciGenerateGithubWorkflow
|
|
63
116
|
```
|
|
64
117
|
|
|
65
|
-
|
|
118
|
+
This will generate a GitHub workflow file inside the `.github/workflows` directory, named `ci.yml`. The workflow file contains following default Jobs:
|
|
119
|
+
|
|
120
|
+
- Build
|
|
121
|
+
- Lint
|
|
122
|
+
- Test
|
|
123
|
+
- Update Readme
|
|
124
|
+
|
|
125
|
+
> **Note:**
|
|
126
|
+
>
|
|
127
|
+
> To use this plugin, we also need to install [ZIO Assistant](https://github.com/apps/zio-assistant) bot.
|
|
128
|
+
|
|
129
|
+
## Testing Strategies
|
|
130
|
+
|
|
131
|
+
### Default Testing Strategy
|
|
132
|
+
|
|
133
|
+
The default testing strategy for ZIO SBT CI plugin is to run `sbt +test` on java 8, 11 and 17. So this will generate the following job:
|
|
134
|
+
|
|
135
|
+
```yaml
|
|
136
|
+
test:
|
|
137
|
+
name: Test
|
|
138
|
+
runs-on: ubuntu-latest
|
|
139
|
+
continue-on-error: false
|
|
140
|
+
strategy:
|
|
141
|
+
fail-fast: false
|
|
142
|
+
matrix:
|
|
143
|
+
java:
|
|
144
|
+
- '8'
|
|
145
|
+
- '11'
|
|
146
|
+
- '17'
|
|
147
|
+
steps:
|
|
148
|
+
- name: Install libuv
|
|
149
|
+
run: sudo apt-get update && sudo apt-get install -y libuv1-dev
|
|
150
|
+
- name: Setup Scala
|
|
151
|
+
uses: actions/setup-java@v3.10.0
|
|
152
|
+
with:
|
|
153
|
+
distribution: temurin
|
|
154
|
+
java-version: ${{ matrix.java }}
|
|
155
|
+
check-latest: true
|
|
156
|
+
- name: Cache Dependencies
|
|
157
|
+
uses: coursier/cache-action@v6
|
|
158
|
+
- name: Git Checkout
|
|
159
|
+
uses: actions/checkout@v3.3.0
|
|
160
|
+
with:
|
|
161
|
+
fetch-depth: '0'
|
|
162
|
+
- name: Test
|
|
163
|
+
run: sbt +test
|
|
164
|
+
```
|
|
66
165
|
|
|
67
|
-
|
|
166
|
+
The `sbt +test` command will run the `test` task for all submodules in the project against all Scala versions defined in the `crossScalaVersions` setting.
|
|
167
|
+
|
|
168
|
+
### Concurrent Testing Strategy
|
|
68
169
|
|
|
69
|
-
|
|
170
|
+
In some cases, we may have multiple submodules in our project and we want to test them concurrently using GitHub Actions matrix strategy.
|
|
70
171
|
|
|
71
|
-
|
|
172
|
+
The `ciTargetScalaVersions` setting key is used to define a mapping of project names to the Scala versions that should be used for testing phase of continuous integration (CI).
|
|
173
|
+
|
|
174
|
+
For example, suppose we have a project with the name "submoduleA" and we want to test it against Scala `2.11.12` and `2.12.18`, and for the "submoduleB" we want to test it against Scala `2.12.18` and `2.13.11` and `3.3.0`, We can define the `ciTargetScalaVersions` setting as follows:
|
|
72
175
|
|
|
73
176
|
```scala
|
|
74
177
|
ThisBuild / ciTargetScalaVersions := Map(
|
|
75
|
-
"submoduleA" -> Seq("2.11.12", "2.12.
|
|
76
|
-
"submoduleB" -> Seq("2.12.
|
|
178
|
+
"submoduleA" -> Seq("2.11.12", "2.12.18"),
|
|
179
|
+
"submoduleB" -> Seq("2.12.18", "2.13.11", "3.3.0")
|
|
77
180
|
)
|
|
78
181
|
```
|
|
79
182
|
|
|
183
|
+
In the example provided, `ciTargetScalaVersions` is defined at the `ThisBuild` level, meaning that the setting will apply to all projects within the build. The setting defines a Map where the key is the name of the current project, obtained by calling the `id` method on the `thisProject` setting, and the value is a sequence of Scala versions obtained from the `crossScalaVersions` of each submodule setting.
|
|
184
|
+
|
|
80
185
|
To simplify this process, we can populate the versions using each submodule's crossScalaVersions setting as follows:
|
|
81
186
|
|
|
82
187
|
```scala
|
|
@@ -84,4 +189,49 @@ ThisBuild / ciTargetScalaVersions := Map(
|
|
|
84
189
|
(submoduleA / thisProject).value.id -> (submoduleA / crossScalaVersions).value,
|
|
85
190
|
(submoduleB / thisProject).value.id -> (submoduleB / crossScalaVersions).value
|
|
86
191
|
)
|
|
87
|
-
```
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The above code can be simplified further by using `targetScalaVersionsFor` helper method, it takes a list of submodules and returns a Map of project names to their `crossScalaVersions`:
|
|
195
|
+
|
|
196
|
+
```scala
|
|
197
|
+
ThisBuild / ciTargetScalaVersions := targetScalaVersionsFor(submoduleA, submoduleB).value
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
This will generate the following job:
|
|
201
|
+
|
|
202
|
+
```yaml
|
|
203
|
+
test:
|
|
204
|
+
name: Test
|
|
205
|
+
runs-on: ubuntu-latest
|
|
206
|
+
continue-on-error: false
|
|
207
|
+
strategy:
|
|
208
|
+
fail-fast: false
|
|
209
|
+
matrix:
|
|
210
|
+
java:
|
|
211
|
+
- '8'
|
|
212
|
+
- '11'
|
|
213
|
+
- '17'
|
|
214
|
+
scala-project:
|
|
215
|
+
- ++2.11.12 submoduleA
|
|
216
|
+
- ++2.12.18 submoduleA
|
|
217
|
+
- ++2.12.18 submoduleB
|
|
218
|
+
- ++2.13.11 submoduleB
|
|
219
|
+
- ++3.3.0 submoduleB
|
|
220
|
+
steps:
|
|
221
|
+
- name: Install libuv
|
|
222
|
+
run: sudo apt-get update && sudo apt-get install -y libuv1-dev
|
|
223
|
+
- name: Setup Scala
|
|
224
|
+
uses: actions/setup-java@v3.10.0
|
|
225
|
+
with:
|
|
226
|
+
distribution: temurin
|
|
227
|
+
java-version: ${{ matrix.java }}
|
|
228
|
+
check-latest: true
|
|
229
|
+
- name: Cache Dependencies
|
|
230
|
+
uses: coursier/cache-action@v6
|
|
231
|
+
- name: Git Checkout
|
|
232
|
+
uses: actions/checkout@v3.3.0
|
|
233
|
+
with:
|
|
234
|
+
fetch-depth: '0'
|
|
235
|
+
- name: Test
|
|
236
|
+
run: sbt ${{ matrix.scala-project }}/test
|
|
237
|
+
```
|
package/package.json
CHANGED