Rewrite docs to teach to use the shell, e.g. not 'sbt compile'

[dwijnand]

It's far too common to hear "sbt is too slow" and then find out that the complainer doesn't use sbt's shell.

Eventually sbt server might solve this problem, but in the meantime we should start teaching to use the shell.

As an example, instead of saying "then run 'sbt compile'" we should say "run 'compile' in the sbt shell" or "start sbt and run 'compile'".

Credit to @adriaanm - it's originally his suggestion.

[eed3si9n]

During #306 (the January revamp), I have added the following in Getting Started (http://www.scala-sbt.org/0.13/docs/Running.html):

Coincidently @kmizu had also posted series of tweets in Japanese about this topic especially in comparison to Kotlin compilation speed, and wrote up a blog post http://qiita.com/kmizu/items/234a9e5ba91ee182a925. In his test, there's 2x difference in compiling from batch mode vs compiling from sbt shell.

We should continue to spread this knowledge and warn ppl about it.
There might also be a limitation to evangelism because many other build tools are executed from terminal, and it's hard to fight people's habit. In that sense, the approach sbt-remote-control and Gradle daemon took is interesting because they'd essentially launch something that'll stay permanent in the background.
Our sbt server intentionally stays in a single JVM process for the sake of simplicity (fewer moving parts).

Basically sbt docs have always documented sbt shell usages, so just updating docs might not be enough. Maybe we can print out couple lines of log saying something like:

[info] executing batch mode. Please note that compilation would be faster if you ran from sbt shell mode due to JIT.

[adriaanm]

This issue cuts across our whole stack. I like the idea of warning when sbt is run in single-task mode from the command line.

Could we make it more "interactive" with a message like

[info] entering batch mode; for better performance, hit any key to remain in the sbt shell

Then, if they hit a key, run the shell command, and explain that next time they can just run sbt and then launch their task?

[eed3si9n]

Could we make it more "interactive" with a message like...

You mean if someone runs sbt test on Travis CI or Jenkins, there's a JLine thread monitoring if the user hits any key? I feel like that's a risky move.

[leifwickland]

I agree that watching for input to sbt in batch mode is risky and wouldn't recommend it.

[adriaanm]

If you could reliably detect whether you're in interactive mode, you could pass that as an argument to sbt from the runner script. See scala/scala#5663 for how we propose to do this for the scala runner.

[dwijnand]

I think such a feature could be hugely benefitial to sbt's reputation, so we should defintely not shy away and give it a proper go. We should definitely test various scenarios to harden the implementation (there's a bunch of shenanigans in the history of sbt-extras working out its -batch feature). And then we'll include an opt-out sys prop, as a fallback (and for any paranoid users).

[dwijnand]

The runtime feature request is being tracked at sbt/sbt#2987.

[bennettellis]

Stupid question maybe, but is this real time savings? What I mean is in an earlier comment someone claimed "there's 2x difference in compiling from batch mode vs compiling from sbt shell."

I'm not seeing it.

So for clarification, are you really just saying that compiling from an already-opened shell saves the time to open the shell (startup Java etc). If so, maybe just say exactly that.

For our project, I started a shell and not counting the startup time, here's the output of running clean, then compile.
[success] Total time: 9 s, completed Aug 30, 2017 8:15:24 AM
[success] Total time: 270 s, completed Aug 30, 2017 8:19:57 AM
add about 5 seconds to start up the shell (type sbt wait for prompt)
Total time probably close to 300 s (5 minutes)

Then, for that same project, no changes, I ran sbt clean compile. Here's the output from running that:
[success] Total time: 253 s, completed Aug 30, 2017 8:25:54 AM (4.2 minutes)

I'm not seeing the 2x difference here. In fact, I'm seeing slower compilation from an existing shell than running in batch mode. Maybe I'm misunderstanding or maybe I'm doing something different. Or maybe this is old and batch is more optimal these days, but it's annoying that I keep getting the message when I compile, but I don't get the real benefit claimed. Maybe the 2x is only realized if not clean?

Would love to be wrong here and find a faster compile time. Thanks!