Discovering running sbt server instance

Context

This is based on the question I asked on Gitter a time ago. I want to understand how to work with the sbt server, discover a running instance, connect to it and communicate.

Sbt 1.0 release notes say

sbt server: JSON API for tooling integration

sbt 1.0 includes server feature, which allows IDEs and other tools to query the build for settings, and invoke commands via a JSON API. […]

[…] For example, IDEs will be able to issue the compile task and retrieve compiler warning as JSON events:

{"type":"xsbti.Problem","message":{"category":"","severity":"Warn","message":"a pure expression does nothing in statement position; you may be omitting necessary parentheses","position":{"line":2,"lineContent":"  1","offset":29,"pointer":2,"pointerSpace":"  ","sourcePath":"/tmp/hello/Hello.scala","sourceFile":"file:/tmp/hello/Hello.scala"}},"level":"warn"}

That’s exactly what I want: to make an editor plugin that will be able to launch a server or locate a running one, and communicate with it in JSON.

I tried to read docs about launcher, but got only confused. I also read the old blog post by @eed3si9n about server “reboot”, it’s helpful (although uses outdated JSON format).

Questions

Starting a server

I understand that I can just launch sbt (or sbt shell) and it will run as a server.

Is it possible to launch it in the background?

Locating a running server (the main question)

I see that there is --locate option, but running sbt --locate in the project with an already running sbt fails and the launcher docs speak about some specific laucnher configuration, lock files, etc.

Do I have to write a separate launcher config for each project? Isn’t standard launcher config shipped with sbt valid for it? Docs also mention [server] section of the config, but I didn’t see it anywhere. Is this all up to date or I’m looking in the wrong place?

Connecting to a server

This seems to be more or less clear. If I locate server “manually”, i.e. see a message sbt server started at 127.0.0.1:4714, the I can either run sbt client 127.0.0.1:4714, or connect to it with telnet and communicate using this protocol: { "type": "ExecCommand", "commandLine": "compile" }.

Is there anything else I should know about it?

---

@eed3si9n also replied to me in Gitter:

I think you’re refering to the older server implementation that used to run on its own as a forked process with Activator. we no longer do that for the new server, at least for now out of the box. if you think the feature is useful, plz open an issue for it.

So I’m quite confused also about different server incarnations, and which one is referred to in the v1.0 release notes.

[eed3si9n]

@dwijnand What Alexey said, basically.

We still need an exact incantation for a random client to to run that would:

1. start up a server in the background in autoclose mode, if sbt is not yet running.
2. don’t start up at all, if sbt server is already running.
3. when running on autoclose mode, automatically close itself once all clients are gone.

$ sbt -Dsbt.autoclose=true -Dsbt.discover=true

[eed3si9n]

@laughedelic Thanks for writing this up.

When I rebooted (http://eed3si9n.com/sbt-server-reboot) the server project, I opted to go with single instance because it simplifies the implementation, and that’s what bunch of ppl wanted as well (see for example this discussion https://twitter.com/codefinger/status/702561308814741504).

Now that sbt server effort is no longer holding up sbt 1.0 (Zinc + Scala 2.12), I’d love to revisit some of the rich feature that I had to drop to so we can ship 1.0.

port file

I can try to dig to out the sbt-remote-control’s port file spec, and auto detection mechanism.

sbt client

Another one of the early milestone we would have to hit is completing sbt client command, which is a thin client. If we want a mode that runs sbt in the background, we need a commandline front end that can emulate all of sbt’s feature, including run with console input and Scala REPL.