Humane guidance for sbt DSL

Question

I have yet to need to do something beyond entirely trivial with sbt, and not find myself wasting a whole lot of time. The official documentation is story-like and cyclic, entirely not helpful for wrangling the DSL. The DSL, at large, is left undocumented other than its scaladoc. E.g. examine http://www.scala-sbt.org/0.13/tutorial/Basic-Def.html as a case in point.

Can someone recommend a humane tutorial or reference covering the topics of the last link, or alternatively, better yet, provide clear constructive descriptions for the following:

1. Keys

2. Settings

3. Tasks

4. Scopes

5. Key operators and methods of the DSL relevant to the above entities/classes

6. Key out-of-the-box objects that can be interacted with in the DSL

7. How to define and call functions as opposed to ordinary scala code, and are .scala build definitions really deprecated?

8. How to split build definitions over several files rather than having one huge long pile of code in build.sbt (or, how to structure a .sbt file that you can still read a month later).

9. Multi project .sbt v.s. bare project .sbt - how do you tell the difference?

10. Is there any ScalaIDE support for sbt files?

Please focus only on sbt 0.13.x, as everything else is getting old...

Answer 1

1- References I know about apart from the official doc, I recommend the blog All Jazz with these excellent articles:

• Task engine
• A declarative DSL

7- I don't care if project/*.scala files are deprecated, but for defining setting and tasks *.sbt syntax is lighter. I use *.scala files just for code.

8- Myself I have splitted my build.sbt file into several files. All files in the base folder with the .sbt extension will be aggregated into one big file.

I've just had to repeat the definition of a settingKey, not its implementation.

My *.sbt files are 62 Kb, and I consider them readable. A task and a setting can have embedded documentation, that can be verbose.

val mySetting = settingKey[String]("""
   documentation.....
""")

val myTask = taskKey[String]("""
   documentation.....
""")

With IDEA, I can easily see the structure and navigate quicly to any setting or task, and see its implementation.

For avoiding noise in *.sbt, when the implementation of a task is long, I write it in a separate project/*.scala file.

Generic code that can be reused in other projects, I place it in a separate .scala file.

9- Multiproject SBT file.

It simply has several lines like theses:

lazy val myFirstProject = project.settings(Seq(
   setting1 := value1,
   setting2 := value2
))
lazy val mySecondProject = project.settings(Seq(
   setting1 := value1,
   setting2 := value2
))

It's not very different from a single project one:

setting1 := value1
setting2 := value2

10- For editing SBT files, IDEA with its Scala plugin works indeed well.
Scala IDE doesn't, and that's the main reason I'm using IDEA instead of Eclipse.