sbt runEngineDistribution ...args... to build and execute the engine (#5609)

Automating the assembly of the engine and its execution into a single task. If you are modifying standard libraries, engine sources or Enso tests, you can launch `sbt` and then just:
```
sbt:enso> runEngineDistribution --run test/Tests/src/Data/Maybe_Spec.enso
[info] Engine package created at built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev
[info] Executing built-distribution/enso-engine-...-dev/bin/enso --run test/Tests/src/Data/Maybe_Spec.enso
Maybe:  [5/5, 30ms]
- should have a None variant [14ms]
- should have a Some variant [5ms]
- should provide the `maybe` function [4ms]
- should provide `is_some` [2ms]
- should provide `is_none` [3ms]
5 tests succeeded.
0 tests failed.unEngineDistribution 4s
0 tests skipped.
```
the [runEngineDistribution](3a581f29ee/docs/CONTRIBUTING.md (running-enso)) `sbt` input task makes sure all your sources are properly compiled and only then executes your enso source. Everything ready at a single press of Enter.

# Important Notes
To debug in chrome dev tools, just add `--inspect`:
```
sbt:enso> runEngineDistribution --inspect --run test/Tests/src/Data/Maybe_Spec.enso
E.g. in Chrome open: devtools://devtools/bundled/js_app.html?ws=127.0.0.1:9229/7JsgjXlntK8
```
everything gets build and one can just attach the Enso debugger.

CHANGELOG.md

@@ -567,6 +567,7 @@
 - [Profile engine startup][4110]
 - [Report type of polyglot values][4111]
 - [Engine can now recover from serialization failures][5591]
+- [Use sbt runEngineDistribution][5609]
 - [Update to GraalVM 22.3.1][5602]
 
 [3227]: https://github.com/enso-org/enso/pull/3227
@@ -662,6 +663,7 @@
 [4110]: https://github.com/enso-org/enso/pull/4110
 [4111]: https://github.com/enso-org/enso/pull/4111
 [5591]: https://github.com/enso-org/enso/pull/5591
+[5609]: https://github.com/enso-org/enso/pull/5609
 [5602]: https://github.com/enso-org/enso/pull/5602
 
 # Enso 2.0.0-alpha.18 (2021-10-12)

build.sbt

@@ -2214,6 +2214,13 @@ buildEngineDistribution := {
   log.info(s"Engine package created at $root")
 }
 
+lazy val runEngineDistribution = inputKey[Unit]("Run the engine distribution with arguments")
+runEngineDistribution := {
+  buildEngineDistribution.value
+  val args: Seq[String] = spaceDelimited("<arg>").parsed
+  DistributionPackage.runEnginePackage(engineDistributionRoot.value, args, streams.value.log)
+}
+
 val stdBitsProjects =
   List("Base", "Database", "Google_Api", "Image", "Table", "All")
 val allStdBits: Parser[String] =

docs/CONTRIBUTING.md

@@ -581,17 +581,21 @@ and generate the Enso distribution:
 
 ```bash
 $ sbt buildEngineDistribution
-...
-Engine package created at built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev
+$ sbt runEngineDistribution --help
 ```
 
+Engine package created at
+built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev - use it or
+the `sbt runEngineDistribution` command to invoke Enso.
+
 ##### PowerShell
 
 ```powershell
 sbt.bat buildEngineDistribution
+sbt.bat runEngineDistribution --help
 ```
 
-Then one can execute the launcher:
+One can use the `runEngineDistribution` command or execute the launcher:
 
 ```bash
 $ built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso

project/DistributionPackage.scala

@@ -182,6 +182,29 @@ object DistributionPackage {
     )
   }
 
+  def runEnginePackage(
+    distributionRoot: File,
+    args: Seq[String],
+    log: Logger
+  ): Boolean = {
+    import scala.collection.JavaConverters._
+
+    val enso = distributionRoot / "bin" / "enso"
+    log.info(s"Executing $enso ${args.mkString(" ")}")
+    val pb = new java.lang.ProcessBuilder()
+    val all = new java.util.ArrayList[String]()
+    all.add(enso.getAbsolutePath())
+    all.addAll(args.asJava)
+    pb.command(all)
+    pb.inheritIO()
+    val p = pb.start()
+    val exitCode = p.waitFor()
+    if (exitCode != 0) {
+      log.warn(enso + " finished with exit code " + exitCode)
+    }
+    exitCode == 0
+  }
+
   def fixLibraryManifest(
     packageRoot: File,
     targetVersion: String,

tools/enso4igv/README.md

@@ -54,16 +54,11 @@ to _finish_ the installation.
 ## Using the IGV
 
 Build an instance of the Enso runtime engine (see
-[Running Enso](../../docs/CONTRIBUTING.md#running-enso)) using:
+[Running Enso](../../docs/CONTRIBUTING.md#running-enso)) using and then launch
+it with special `--dump-graphs` option:
 
 ```bash
-enso$ sbt buildEngineDistribution
-```
-
-and then launch it with special `--dump-graphs` option:
-
-```bash
-enso$ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --dump-graphs --run yourprogram.enso
+enso$ sbt runEngineDistribution --dump-graphs --run yourprogram.enso
 ```
 
 When executed on [GraalVM 22.3.1](http://graalvm.org) these options instruct the

tools/language-server/wstest/benchmarks/apply-edit/README.md

@@ -5,16 +5,11 @@ message and waits for the visualization message on binary WebSocket.
 
 ## Run
 
-Build Enso distribution.
+Build Enso distribution. Start the Language Server and redirect ouput to
+`language-server.log`
 
 ```bash
-sbt buildEngineDistribution
-```
-
-Start the Language Server and redirect ouput to `language-server.log`
-
-```bash
-built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso \
+sbt runEngineDistribution \
   --log-level trace \
   --server \
   --root-id 6f7d58dd-8ee8-44cf-9ab7-9f0454033641 \