Run in background

[steinybot]

Resolves #737

This does a couple of things.

The first is to add a --background setting which stops mdoc from reading from standard input and waiting for the enter key and instead it blocks until being interrupted. See the first two commits for this.

The last commit wraps this up in a useful sbt tasks for starting and stopping which takes care of some non-trivial stuff like tracking the job handle.

[tgodzik]

Thanks for the contribution! Testing it locally I can't seem to make it work, it never starts watching:

sbt:default-ce2872> docs/mdocBgStart
[info] running mdoc.SbtMain --watch --background
[success] Total time: 3 s, completed Jan 12, 2023, 5:24:39 PM
sbt:default-ce2872> 

I was testing it on scalameta/metals.

Also why would you need to run it in the background? Is it an issue with the fact that watch doesn't work well if you need to recompile some sources?

[tgodzik]

Suggested change

// TODO: Do we need the -Xmx setting and any other future options?

I don't think we need any other options for the test, should we remove the comment?

[steinybot]

Thanks for the contribution! Testing it locally I can't seem to make it work, it never starts watching:

sbt:default-ce2872> docs/mdocBgStart
[info] running mdoc.SbtMain --watch --background
[success] Total time: 3 s, completed Jan 12, 2023, 5:24:39 PM
sbt:default-ce2872> 

I was testing it on scalameta/metals.

Hmm that's odd. I'll look into it.

Also why would you need to run it in the background? Is it an issue with the fact that watch doesn't work well if you need to recompile some sources?

It's convenient to return the sbt shell so that other commands can be issued, especially if mdoc is only one of many tools in the pipeline that each have their own watch mode. I want to run mdoc in watch mode and then another tool which watches for the output of mdoc, and run that via a single sbt command that calls both of those tasks.

[armanbilge]

I want to run mdoc in watch mode and then another tool which watches for the output of mdoc, and run that via a single sbt command that calls both of those tasks.

We have this exact usecase as well, we currently run the other tool in the background. It's a bit tricky, see:
https://github.com/typelevel/sbt-typelevel/blob/9ae6ac00f3c30a10e29cd308292596b90d05c7e3/site/src/main/scala/org/typelevel/sbt/TypelevelSitePlugin.scala#L213-L231

[steinybot]

@tgodzik I ran publishLocal and added it to another project using mdoc and it worked fine for me:

sbt:root> docs/mdocBgStart
[info] running mdoc.SbtMain --watch --background
[success] Total time: 1 s, completed 15/01/2023, 8:15:38 pm
info: LiveReload server started on http://localhost:4000/
sbt:root> Jan 15, 2023 8:15:39 PM io.undertow.Undertow start
INFO: starting server: Undertow - 2.2.20.Final
Jan 15, 2023 8:15:39 PM org.xnio.Xnio <clinit>
INFO: XNIO version 3.8.8.Final
Jan 15, 2023 8:15:39 PM org.xnio.nio.NioXnio <clinit>
INFO: XNIO NIO Implementation Version 3.8.8.Final
Jan 15, 2023 8:15:39 PM org.jboss.threads.Version <clinit>
INFO: JBoss Threads version 3.1.0.Final
info: Compiling 37 files to /Users/jason/src/goodcover/stable-slinky/target/docs
sbt:root> reload plugins
[info] welcome to sbt 1.8.2 (Azul Systems, Inc. Java 17.0.3)
[info] loading global plugins from /Users/jason/.sbt/1.0/plugins
[info] loading settings for project project from plugins.sbt ...
[info] loading project definition from /Users/jason/src/goodcover/stable-slinky/project
sbt:project> show libraryDependencies
[info] * org.scala-lang:scala-library:2.12.17:provided
[info] * com.github.sbt:sbt-ghpages:0.7.0 (e:sbtVersion=1.0, e:scalaVersion=2.12)
[info] * com.typesafe.sbt:sbt-site:1.4.1 (e:sbtVersion=1.0, e:scalaVersion=2.12)
[info] * io.github.davidgregory084:sbt-tpolecat:0.4.2 (e:sbtVersion=1.0, e:scalaVersion=2.12)
[info] * org.scalameta:sbt-mdoc:2.3.6+49-50d0f693-SNAPSHOT (e:sbtVersion=1.0, e:scalaVersion=2.12)
[info] * org.scala-js:sbt-scalajs:1.12.0 (e:sbtVersion=1.0, e:scalaVersion=2.12)

I'm assuming in your test setup, running docs/mdoc --watch task works fine yeah?

It's weird how undertow isn't even starting. My change should only change the behaviour after startLivereload is called. If that isn't happening then something else is going on. You don't have something like noLivereload or check set somewhere do you?

Does bgList show anything?

sbt:project> show bgList
[info] * JobHandle(1, mdocBgStart, ProjectRef(uri("file:/Users/jason/src/goodcover/stable-slinky/"), "docs") / mdocBgStart)
[success] Total time: 0 s, completed 15/01/2023, 8:20:07 pm

[tgodzik]

@olafurpg could you take a quick look if this makes sense?

@steinybot sorry for no response, I will try it out later this week. Could you take a look at the scripted tests?