You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 2.x/docs/en/changes/migrating-from-sbt-1.x.html
+8-2Lines changed: 8 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -211,13 +211,13 @@ <h1 class="menu-title">The Book of sbt</h1>
211
211
<h1id="migrating-from-sbt-1x"><aclass="header" href="#migrating-from-sbt-1x">Migrating from sbt 1.x</a></h1>
212
212
<h2id="changing-buildsbt-dsl-to-scala-3x"><aclass="header" href="#changing-buildsbt-dsl-to-scala-3x">Changing <code>build.sbt</code> DSL to Scala 3.x</a></h2>
213
213
<p>As a reminder, users can build either Scala 2.x or Scala 3.x programs using either sbt 1.x or sbt 2.x. However, the Scala that underlies the <code>build.sbt</code> DSL is determined by the sbt version. In sbt 2.0, we are migrating to Scala 3.x.</p>
214
-
<p>This means that if you implement custom tasks or sbt plugins for sbt 2.x, it must be done using Scala 3.x. See<ahref="https://docs.scala-lang.org/scala3/guides/migration/incompatibility-table.html">Scala 3.x incompatibility table</a> and <ahref="https://docs.scala-lang.org/scala3/guides/migration/tooling-scala2-xsource3.html">Scala 2 with -Xsource:3</a>.</p>
214
+
<p>This means that if you implement custom tasks or sbt plugins for sbt 2.x, it must be done using Scala 3.x. Consult<ahref="https://docs.scala-lang.org/scala3/guides/migration/incompatibility-table.html">Scala 3.x incompatibility table</a> and <ahref="https://docs.scala-lang.org/scala3/guides/migration/tooling-scala2-xsource3.html">Scala 2 with -Xsource:3</a> for details about Scala 3.x.</p>
215
215
<pre><codeclass="language-scala">// This works on Scala 2.12.20 under -Xsource:3
<p>In sbt 2.x, bare settings settings should no longer be scoped to <code>ThisBuild</code>. One benefit of the new <em>common settings</em> over <code>ThisBuild</code> is that it would act in a more predictable delegation. These settings are inserted between plugins settings and those defined in <code>settings(...)</code>, meaning they can be used to define settings like <code>Compile / scalacOptions</code>, which was not possible with <code>ThisBuild</code>.</p>
239
+
<h2id="migrating-to-cached-tasks"><aclass="header" href="#migrating-to-cached-tasks">Migrating to cached tasks</a></h2>
240
+
<p>See <ahref="../reference/cached-task.html">Cached task</a> reference for details, including the way to opt out of caching.</p>
241
+
<h2id="migration-away-from-integrationtest"><aclass="header" href="#migration-away-from-integrationtest">Migration away from IntegrationTest</a></h2>
242
+
<p>To migrate away from the <code>IntegrationTest</code> configuration, create a separate subproject and implement it as normal test.</p>
239
243
<h2id="migrating-to-slash-syntax"><aclass="header" href="#migrating-to-slash-syntax">Migrating to slash syntax</a></h2>
240
244
<p>sbt 1.x supported both the sbt 0.13 style syntax and the slash syntax. sbt 2.x removes the support for the sbt 0.13 syntax, so use the slash syntax for both sbt shell and in <code>build.sbt</code>:</p>
<p>For example, <code>test:compile</code> will no longer work on the shell. Use <code>Test/compile</code> instead. See <ahref="https://eed3si9n.com/syntactic-scalafix-rule-for-unified-slash-syntax/">syntactic Scalafix rule for unified slash syntax</a> for semi-automated migration of <code>build.sbt</code> files.</p>
<h2id="changes-with-compatibility-implications"><aclass="header" href="#changes-with-compatibility-implications">Changes with compatibility implications</a></h2>
226
226
<p>See also <ahref="./migrating-from-sbt-1.x.html">Migrating from sbt 1.x</a>.</p>
227
227
<ul>
228
-
<li>sbt 2.x uses Scala 3.x (currently <strong>3.6.4</strong>) for build definitions and plugins (Both sbt 1.x and 2.x are capable of building Scala 2.x and 3.x) by <ahref="https://github.com/eed3si9n">@eed3si9n</a>, <ahref="https://github.com/adpi2">@adpi2</a>, and others.</li>
229
-
<li>Bare settings are added to all subprojects, as opposed to just the root subproject, and thus replacing the role that <code>ThisBuild</code> has played.</li>
230
-
<li><code>test</code> task is changed to be incremental test that can cache test results. Use <code>testFull</code> for full test by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7686">#7686</a></li>
231
-
<li>Default settings and tasks keys typed to <code>URL</code><code>apiMappings</code>, <code>apiURL</code>, <code>homepage</code>, <code>organizationHomepage</code>, <code>releaseNotesURL</code> were changed to <code>URI</code> in <ahref="https://github.com/sbt/sbt/pull/7927">#7927</a>.</li>
228
+
<li><strong>Scala 3 in metabuild</strong>. sbt 2.x build.sbt DSL, used for build definitions and plugins, is based on Scala 3.x (currently <strong>3.7.2</strong>) (Both sbt 1.x and 2.x are capable of building Scala 2.x and 3.x) by <ahref="https://github.com/eed3si9n">@eed3si9n</a>, <ahref="https://github.com/adpi2">@adpi2</a>, and others.</li>
229
+
<li><strong>Common settings</strong>. Bare settings are added to all subprojects, as opposed to just the root subproject, and thus replacing the role that <code>ThisBuild</code> has played.</li>
230
+
<li><strong>Cached task</strong>. All tasks are cached by default. Details in <ahref="../concepts/caching.html">Caching</a>.</li>
231
+
<li><strong>Incremental test</strong>. <code>test</code> task is changed to be incremental test that can cache test results. Use <code>testFull</code> for full test by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7686">#7686</a></li>
232
+
<li><code>test</code> task type is changed from <code>Unit</code> to <code>TestResult</code> by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/8181">#8181</a></li>
233
+
<li>Default settings and tasks keys typed to <code>URL</code> (i.e. <code>apiMappings</code>, <code>apiURL</code>, <code>homepage</code>, <code>organizationHomepage</code>, <code>releaseNotesURL</code>) were changed to <code>URI</code> in <ahref="https://github.com/sbt/sbt/pull/7927">#7927</a>.</li>
232
234
<li><code>licenses</code> key is changed from <code>Seq[(String, URL)]</code> to <code>Seq[License]</code> in <ahref="https://github.com/sbt/sbt/pull/7927">#7927</a>.</li>
233
235
<li>sbt 2.x plugins are published with <code>_sbt2_3</code> suffix by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7671">#7671</a></li>
234
236
<li>sbt 2.x adds <code>platform</code> setting so <code>ModuleID</code>'s <code>%%</code> operator can cross build on JVM as well as JS and Native, as opposed to <code>%%%</code> operator that was created in a plugin to workaround this issue, by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/6746">#6746</a></li>
235
237
<li>Dropped <code>useCoursier</code> setting so Coursier cannot be opted out, by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7712">#7712</a></li>
236
238
<li><code>Key.Classpath</code> is changed to be an alias of the <code>Seq[Attributed[xsbti.HashedVirtualFileRef]]</code> type, instead of <code>Seq[Attributed[File]]</code>. Similarly, some task keys that used to return <code>File</code> have changed to return <code>HashedVirtualFileRef</code> instead. See <ahref="../concepts/caching.html#caching-files">Caching Files</a>.</li>
237
-
<li>In sbt 2.x <code>target</code> defaults to <code>target/out/jvm/scala-3.6.4/<subproject>/</code>, as opposed to <code><subproject>/target/</code>.</li>
239
+
<li>In sbt 2.x <code>target</code> defaults to <code>target/out/jvm/scala-3.7.2/<subproject>/</code>, as opposed to <code><subproject>/target/</code>.</li>
<p>In sbt 2.x, the bare settings in <code>build.sbt</code> are interpreted to be common settings, and are injected to all subprojects. This means we can now set <code>scalaVersion</code> without using <code>ThisBuild</code> scoping:</p>
<p>This also fixes the so-called dynamic dispatch problem:</p>
254
257
<pre><codeclass="language-scala">lazy val hi = taskKey[String]("")
255
258
hi := name.value + "!"
256
259
</code></pre>
257
260
<p>In sbt 1.x <code>hi</code> task will capture the name of the root project, but in sbt 2.x it will return the <code>name</code> of each subproject with <code>!</code>:</p>
<p>The above runs all subprojects whose <code>scalaBinaryVersion</code> is <code>3</code>. Contributed by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7699">#7699</a></p>
<p>sbt 2.x implements cached task, which can automatically cache the task results to local disk and Bazel-compatible remote cache.</p>
280
+
<p>sbt 2.x implements cached task by default, which can automatically cache the task results to local disk and Bazel-compatible remote cache.</p>
280
281
<pre><codeclass="language-scala">lazy val task1 = taskKey[String]("doc for task1")
281
282
282
-
task1 := (Def.cachedTask {
283
-
name.value + version.value + "!"
284
-
}).value
283
+
task1 := name.value + version.value + "!"
285
284
</code></pre>
286
285
<p>This tracks the inputs into the <code>task1</code> and creates a machine-wide disk cache, which can also be configured to also use a remote cache. Since it's common for sbt tasks to also produce files on the side, we also provide a mechanism to cache file contents:</p>
287
286
<pre><codeclass="language-scala">lazy val task1 = taskKey[String]("doc for task1")
288
287
289
-
task1 := (Def.cachedTask {
288
+
task1 := {
290
289
val converter = fileConverter.value
291
290
....
292
291
val output = converter.toVirtualFile(somefile)
293
292
Def.declareOutput(output)
294
293
name.value + version.value + "!"
295
-
}).value
294
+
}
296
295
</code></pre>
297
-
<p>Contributed by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7464">#7464</a> / <ahref="https://github.com/sbt/sbt/pull/7525">#7525</a></p>
296
+
<p>See <ahref="../concepts/caching.html">Caching</a> for details. Contributed by <ahref="https://github.com/eed3si9n">@eed3si9n</a> in <ahref="https://github.com/sbt/sbt/pull/7464">#7464</a> / <ahref="https://github.com/sbt/sbt/pull/7525">#7525</a>.</p>
298
297
<h2id="previously-on-sbt"><aclass="header" href="#previously-on-sbt">Previously on sbt</a></h2>
<p>A build that ends up capturing ephemeral inputs, are said to <em>break the hermeticity</em> or <em>non-hermetic</em>. Another common way the hermeticity is broken is capturing absolute paths as either input or output. Sometimes the path gets embedded into the JAR via a macro, you might not know until you inspect the bytecode.</p>
<p>The task will be automatically cached based on the two settings <code>name</code> and <code>version</code>. The first time we run the task it will be executed onsite, but the second time onward, it will use the disk cache:</p>
229
+
<p>In sbt 2.x, the task result will be automatically cached based on the two settings <code>name</code> and <code>version</code>. The first time we run the task it will be executed onsite, but the second time onward, it will use the disk cache:</p>
<h3id="the-effect-of-file-creation"><aclass="header" href="#the-effect-of-file-creation">The effect of file creation</a></h3>
258
254
<p>There are many tasks that generate file that do not use <code>VirtualFile</code> as the return type. For example, <code>compile</code> returns <code>Analysis</code> instead, and <code>*.class</code> file generation happens as a <em>side effect</em> in sbt 1.x.</p>
259
255
<p>To participate in caching, we need to declare these effects as something we care about.</p>
<p>You can optionally extend the build to use remote cache in addition to the local disk cache. Remote caching could improve build performance by allowing multiple machines to share build artifacts and outputs.</p>
270
266
<p>Imagine you have a dozen people in your project or a company. Each morning, you will <code>git pull</code> the changes the dozen people made, and you need to build their code. If you have a successful project, the code size will only get bigger over time, and the % of the time you spend building someone else's in your day increases. This becomes the limiting factor of your team size and code size. Remote caching reverses this tide by CI systems hydrate the cache and you can download the artifacts and task outputs.</p>
271
-
<p>sbt 2.x implements Bazel-compatible gRPC interface, which works with number of backend both open source and commercial.</p>
267
+
<p>sbt 2.x implements Bazel-compatible gRPC interface, which works with number of backend both open source and commercial. See <ahref="../reference/remote-cache-setup.html">Remote cache setup</a> for more details.</p>
0 commit comments