Merge pull request #716 from eed3si9n/wip/scripted

SbtPlugin

src/reference/00-Getting-Started/03-Directories.md

@@ -2,22 +2,22 @@
 out: Directories.html
 ---
 
-  [Hello]: Hello.html
+  [ByExample]: sbt-by-example.html
   [Setup]: Setup.html
   [Organizing-Build]: Organizing-Build.html
 
 Directory structure
 -------------------
 
 This page assumes you've [installed sbt][Setup] and seen the
-[Hello, World][Hello] example.
+[sbt by example][ByExample].
 
 ### Base directory
 
 In sbt's terminology, the "base directory" is the directory containing
 the project. So if you created a project `hello` containing
-`hello/build.sbt` as in the [Hello, World][Hello]
-example, `hello` is your base directory.
+`/tmp/foo-build/build.sbt` as in the [sbt by example][ByExample],
+`/tmp/foo-build` is your base directory.
 
 ### Source code
 

src/reference/00-Getting-Started/04-Running.md

@@ -2,7 +2,7 @@
 out: Running.html
 ---
 
-  [Hello]: Hello.html
+  [ByExample]: sbt-by-example.html
   [Setup]: Setup.html
   [Triggered-Execution]: ../docs/Triggered-Execution.html
   [Command-Line-Reference]: ../docs/Command-Line-Reference.html
@@ -11,8 +11,8 @@ Running
 -------
 
 This page describes how to use sbt once you have set up your project. It
-assumes you've [installed sbt][Setup] and created a
-[Hello, World][Hello] or other project.
+assumes you've [installed sbt][Setup] and went through
+[sbt by example][ByExample].
 
 ### sbt shell
 

src/reference/00-Getting-Started/05-Basic-Def.md

@@ -63,12 +63,13 @@ The key-value pairs are listed under the `.settings(...)` method as follows:
 called *setting expressions* using *build.sbt DSL*.
 
 ```scala
+ThisBuild / organization := "com.example"
+ThisBuild / scalaVersion := "$example_scala_version$"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+
 lazy val root = (project in file("."))
   .settings(
-    name         := "hello",
-    organization := "com.example",
-    scalaVersion := "$example_scala_version$",
-    version      := "0.1.0-SNAPSHOT"
+    name := "hello"
   )
 ```
 
@@ -241,17 +242,16 @@ import Keys._
 
 ### Bare .sbt build definition
 
-Instead of defining `Project`s, bare `.sbt` build definition consists of
-a list of `Setting[_]` expressions.
+The settings can be written directly into the `build.sbt` file instead of
+putting them inside a `.settings(...)` call. We call this the "bare style."
 
 ```scala
-name := "hello"
-version := "1.0"
-scalaVersion := "$example_scala_version$"
+ThisBuild / version := "1.0"
+ThisBuild / scalaVersion := "$example_scala_version$"
 ```
 
-This syntax is recommended mostly for using plugins. See later section
-about the plugins.
+This syntax is recommended for `ThisBuild` scoped settings and adding plugins.
+See later section about the scoping and the plugins.
 
 ### Adding library dependencies
 
@@ -262,15 +262,12 @@ managed dependencies, which will look like this in `build.sbt`:
 ```scala
 val derby = "org.apache.derby" % "derby" % "10.4.1.3"
 
-lazy val commonSettings = Seq(
-  organization := "com.example",
-  version := "0.1.0-SNAPSHOT",
-  scalaVersion := "$example_scala_version$"
-)
+ThisBuild / organization := "com.example"
+ThisBuild / scalaVersion := "$example_scala_version$"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
 
 lazy val root = (project in file("."))
   .settings(
-    commonSettings,
     name := "Hello",
     libraryDependencies += derby
   )

src/reference/00-Getting-Started/09-Multi-Project.md → src/reference/00-Getting-Started/05B-Multi-Project.md

@@ -46,17 +46,42 @@ lazy val util = project
 lazy val core = project
 ```
 
-#### Common settings
+#### Build-wide settings
 
 To factor out common settings across multiple projects,
+define the settings scoped to `ThisBuild`.
+The limitation is that the right-hand side needs to a pure value
+or settings scoped to `Global` or `ThisBuild`,
+and there are no defeault settings scoped to subprojects. (See [Scopes][Scopes])
+
+```scala
+ThisBuild / organization := "com.example"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+ThisBuild / scalaVersion := "$example_scala_version$"
+
+lazy val core = (project in file("core"))
+  .settings(
+    // other settings
+  )
+
+lazy val util = (project in file("util"))
+  .settings(
+    // other settings
+  )
+```
+
+Now we can bump up `version` in one place, and it will be reflected
+across subprojects when you reload the build.
+
+#### Common settings
+
+Another way to factor out common settings across multiple projects is to
 create a sequence named `commonSettings` and call `settings` method
 on each project.
 
 ```scala
 lazy val commonSettings = Seq(
-  organization := "com.example",
-  version := "0.1.0-SNAPSHOT",
-  scalaVersion := "$example_scala_version$"
+  target := { baseDirectory.value / "target2" }
 )
 
 lazy val core = (project in file("core"))
@@ -72,14 +97,6 @@ lazy val util = (project in file("util"))
   )
 ```
 
-Now we can bump up `version` in one place, and it will be reflected
-across subprojects when you reload the build.
-
-#### Build-wide settings
-
-Another a bit advanced technique for factoring out common settings
-across subprojects is to define the settings scoped to `ThisBuild`. (See [Scopes][Scopes])
-
 ### Dependencies
 
 Projects in the build can be completely independent of one another, but

src/reference/00-Getting-Started/06-Task-Graph.md

@@ -68,12 +68,13 @@ regardless of which line it appears in the body.**
 See the following example:
 
 ```scala
+ThisBuild / organization := "com.example"
+ThisBuild / scalaVersion := "$example_scala_version$"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+
 lazy val root = (project in file("."))
   .settings(
     name := "Hello",
-    organization := "com.example",
-    scalaVersion := "$example_scala_version$",
-    version := "0.1.0-SNAPSHOT",
     scalacOptions := {
       val out = streams.value // streams task happens-before scalacOptions
       val log = out.log
@@ -104,12 +105,13 @@ either of them.
 Here's another example:
 
 ```scala
+ThisBuild / organization := "com.example"
+ThisBuild / scalaVersion := "$example_scala_version$"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+
 lazy val root = (project in file("."))
   .settings(
     name := "Hello",
-    organization := "com.example",
-    scalaVersion := "$example_scala_version$",
-    version := "0.1.0-SNAPSHOT",
     scalacOptions := {
       val ur = update.value  // update task happens-before scalacOptions
       if (false) {

src/reference/00-Getting-Started/07A-Scopes.md

@@ -344,23 +344,15 @@ sbt will look for it in `ThisBuild` as a fallback.
 Using the mechanism, we can define a build-level default setting for
 frequently used keys such as `version`, `scalaVersion`, and `organization`.
 
-For convenience, there is `inThisBuild(...)` function that will
-scope both the key and the body of the setting expression to `ThisBuild`.
-Putting setting expressions in there would be equivalent to appending `in ThisBuild` where possible.
-
 ```scala
+ThisBuild / organization := "com.example",
+ThisBuild / scalaVersion := "$example_scala_version$",
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+
 lazy val root = (project in file("."))
   .settings(
-    inThisBuild(List(
-      // Same as:
-      // ThisBuild / organization := "com.example"
-      organization := "com.example",
-      scalaVersion := "$example_scala_version$",
-      version      := "0.1.0-SNAPSHOT"
-    )),
     name := "Hello",
-    publish := (),
-    publishLocal := ()
+    publish / skip := true
   )
 
 lazy val core = (project in file("core"))
@@ -374,8 +366,12 @@ lazy val util = (project in file("util"))
   )
 ```
 
+For convenience, there is `inThisBuild(...)` function that will
+scope both the key and the body of the setting expression to `ThisBuild`.
+Putting setting expressions in there would be equivalent to prepending `ThisBuild /` where possible.
+
 Due to the nature of [scope delegation][Scope-Delegation] that we will cover later,
-we do not recommend using build-level settings beyond simple value assignments.
+build-level settings should be set only to a pure value or settings from either `Global` or `ThisBuild` scoping.
 
 ### Scope delegation
 

src/reference/00-Getting-Started/11-Custom-Settings.md

@@ -64,14 +64,12 @@ to associate some code with the task key:
 val sampleStringTask = taskKey[String]("A sample string task.")
 val sampleIntTask = taskKey[Int]("A sample int task.")
 
-lazy val commonSettings = Seq(
-  organization := "com.example",
-  version := "0.1.0-SNAPSHOT"
-)
+ThisBuild / organization := "com.example"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+ThisBuild / scalaVersion := "$example_scala_version$"
 
 lazy val library = (project in file("library"))
   .settings(
-    commonSettings,
     sampleStringTask := System.getProperty("user.home"),
     sampleIntTask := {
       val sum = 1 + 2
@@ -125,14 +123,12 @@ val stopServer = taskKey[Unit]("stop server")
 val sampleIntTask = taskKey[Int]("A sample int task.")
 val sampleStringTask = taskKey[String]("A sample string task.")
 
-lazy val commonSettings = Seq(
-  organization := "com.example",
-  version := "0.1.0-SNAPSHOT"
-)
+ThisBuild / organization := "com.example"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+ThisBuild / scalaVersion := "$example_scala_version$"
 
 lazy val library = (project in file("library"))
   .settings(
-    commonSettings,
     startServer := {
       println("starting...")
       Thread.sleep(500)
@@ -218,7 +214,6 @@ at which point `stopServer` should be the `sampleStringTask`.
 ```scala
 lazy val library = (project in file("library"))
   .settings(
-    commonSettings,
     startServer := {
       println("starting...")
       Thread.sleep(500)

src/reference/00-Getting-Started/12-Organizing-Build.md

@@ -105,14 +105,13 @@ To use the `val`s under it easier, import `Dependencies._`.
 ```scala
 import Dependencies._
 
-lazy val commonSettings = Seq(
-  version := "0.1.0",
-  scalaVersion := "$example_scala_version$"
-)
+ThisBuild / organization := "com.example"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+ThisBuild / scalaVersion := "$example_scala_version$"
 
 lazy val backend = (project in file("backend"))
   .settings(
-    commonSettings,
+    name := "backend",
     libraryDependencies ++= backendDeps
   )
 ```

src/reference/01-General-Info/04-Bintray-For-Plugins.md

@@ -66,20 +66,18 @@ addSbtPlugin("org.foundweekends" % "sbt-bintray" % "$sbt_bintray_version$")
 Next, a make sure your `build.sbt` file has the following settings
 
 ```scala
-lazy val commonSettings = Seq(
-  version in ThisBuild := "<YOUR PLUGIN VERSION HERE>",
-  organization in ThisBuild := "<INSERT YOUR ORG HERE>"
-)
+ThisBuild / version := "<YOUR PLUGIN VERSION HERE>"
+ThisBuild / organization := "<INSERT YOUR ORG HERE>"
+ThisBuild / description := "<YOUR DESCRIPTION HERE>"
+
+// This is an example.  sbt-bintray requires licenses to be specified
+// (using a canonical name).
+ThisBuild / licenses += ("Apache-2.0", url("https://www.apache.org/licenses/LICENSE-2.0.html"))
 
 lazy val root = (project in file("."))
   .settings(
-    commonSettings,
     sbtPlugin := true,
     name := "<YOUR PLUGIN HERE>",
-    description := "<YOUR DESCRIPTION HERE>",
-    // This is an example.  sbt-bintray requires licenses to be specified 
-    // (using a canonical name).
-    licenses += ("Apache-2.0", url("https://www.apache.org/licenses/LICENSE-2.0.html")),
     publishMavenStyle := false,
     bintrayRepository := "sbt-plugins",
     bintrayOrganization in bintray := None