document the fact that project/build.properties file gets created

[alvinj]

problem

The behavior of sbtVersion is inconsistent. The help text states, “Provides the version of sbt. This setting should not be modified.” But the actual behavior is:

• In an SBT project with no project/build.properties file:
  • It creates a project/build.properties file with the version of the current SBT executable
  • It reports the SBT version it wrote in that file
• In an SBT project with an existing project/build.properties file:
  • It reports the SBT version in project/build.properties file
• In my HOME directory:
  • It creates a project directory and project/build.properties file
• In an empty directory:
  • It reports the version of the SBT executable

steps

The following examples show the issue(s).

(1) Move into an existing SBT project that has no project/build.properties file

/Users/al/Projects/Scala/CatoGui> sbt sbtVersion
[info] Updated file /Users/al/Projects/Scala/CatoGui/project/build.properties:
    set sbt.version to 1.2.6

Results:

• It creates a project/build.properties file with the version of the current SBT executable
• It reports the SBT version it wrote in that file

(2) Move into an SBT project that has an existing project/build.properties file

In this example, project/build.properties already has sbt.version=1.1.1:

> sbt sbtVersion
[info] Loading settings from idea.sbt ...
[info] Loading global plugins from /Users/al/.sbt/1.0/plugins
[info] Loading project definition from /Users/al/Projects/Scala/Tmp/project
[info] Updating ProjectRef(uri("file:/Users/al/Projects/Scala/Tmp/project/"), "tmp-build")...
[info] Done updating.
[info] Loading settings from build.sbt ...
[info] Set current project to Tmp (in build file:/Users/al/Projects/Scala/Tmp/)
[info] 1.1.1

Results:

• It reports the SBT version in project/build.properties file

(3) In my HOME directory, it creates a project directory and project/build.properties file

This is the behavior in my HOME directory:

/Users/al> sbt sbtVersion
[info] Updated file /Users/al/project/build.properties: set sbt.version to 1.2.6
[info] Loading settings for project global-plugins from idea.sbt ...
[info] Loading global plugins from /Users/al/.sbt/1.0/plugins
[info] Loading project definition from /Users/al/project
[info] Updating ProjectRef(uri("file:/Users/al/project/"), "al-build")...
[info] Done updating.
[info] Set current project to al (in build file:/Users/al/)
[info] 1.2.6

Results:

• It creates a project/build.properties file under my HOME directory with the version of the current SBT executable
• It reports the SBT version it wrote in that file

(4) In an empty directory, it reports the version of the SBT executable

This is the behavior in a non-SBT directory that is not my HOME directory:

/Users/al/tmp> sbt sbtVersion
[warn] No sbt.version set in project/build.properties, base directory: /Users/al/tmp
[info] Loading settings for project global-plugins from idea.sbt ...
[info] Loading global plugins from /Users/al/.sbt/1.0/plugins
[info] Set current project to tmp (in build file:/Users/al/tmp/)
[info] 1.2.6

Results:

• It reports the version of the sbt executable (without creating a project directory)

expectation

1. Per the help text, I expect it to report the current version of SBT, and it should not write or overwrite project/build.properties.
2. Also, it’s not clear whether the version that is reported should be the version of (a) the sbt executable installed on my system, or (b) the version of SBT that’s configured in project/build.properties of the current project, assuming I’m in an SBT project directory. It seems like these are two different requests that require different commands.

notes

sbt version: 1.2.6 (installed on MacOS with Homebrew)

[eed3si9n]

When we say "sbt", there are actually three parts to the program:

1. sbt launcher script written in Bash script / Windows batch.
2. sbt launcher application, which reads build.properties and downloads the artifacts for the specified sbt version.
3. sbt the main application, colloquially known as "the mother ship", which does the actual interpretation of build.sbt and does the compilation etc.

When someone installs "sbt", depending on the packaging you could have:

• just 1 (sbt-extras)
• 1 and 2 (Debian package)
• 1, 2, and 3 (official zip, tgz, msi packages)

but generally speaking, we think of the launcher script as a sbt-version agnostic launching device ( analogous to gradlew), and project/build.properties to be the authoritative declaration of the sbt (mothership) version.

[alvinj]

Thank you, that’s helpful. I think if I discuss my last point any further (#2 under “expectation”) it might be confusing, so I don’t want to pursue that right now.

My bigger concern is that running sbtVersion writes to project/build.properties. It seems like it should always be a read-only operation where it does one of two things:

• If sbt.version is set in project/build.properties, it reports that version
• If sbt.version is not set, it outputs something like, “The SBT version for this project is not set. (You can set it with the sbt.version parameter in project/build.properties.)”

It may just be a misunderstanding on my part, but with the help text stating, “Provides the version of sbt,” it was a big surprise that this command writes to project/build.properties. (Thanks.)

[eed3si9n]

The creation of project/build.properties is part of sbt (mothership)'s startup process, and it has nothing to do with sbtVersion setting. You could probably call sbt name and get the same behavior.

[alvinj]

The sbt name part is also surprising. Maybe a way to describe this is that as a user I feel like I’m issuing a SQL SELECT query when I run sbtVersion or name, but under certain circumstances it also runs an INSERT as a side effect. If that’s the way it’s supposed to work, no problem, I just thought it was a bug.

[alvinj]

Thanks for your help on this!