From 058f17a5076fffd98ea514adaacb38c6e3c46531 Mon Sep 17 00:00:00 2001 From: Jorge Vicente Cantero Date: Wed, 18 Jul 2018 11:31:42 +0200 Subject: [PATCH 1/4] Add log locations for homebrew plist --- project/ReleaseUtils.scala | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/project/ReleaseUtils.scala b/project/ReleaseUtils.scala index 544647f9b1..eed17c1061 100644 --- a/project/ReleaseUtils.scala +++ b/project/ReleaseUtils.scala @@ -95,6 +95,10 @@ object ReleaseUtils { | | KeepAlive | + | StandardOutPath + | #{var}/log/bloop/bloop.out.log + | StandardErrorPath + | #{var}/log/bloop/bloop.err.log | | | EOS From 21f3bcdcbd332166b4477f1e775e97bb652353d6 Mon Sep 17 00:00:00 2001 From: Jorge Vicente Cantero Date: Wed, 18 Jul 2018 12:51:42 +0200 Subject: [PATCH 2/4] Add release notes for v1.0.0 --- README.md | 11 ++ .../src/main/scala/bloop/cli/Commands.scala | 3 +- notes/v1.0.0.md | 177 ++++++++++++++++++ 3 files changed, 189 insertions(+), 2 deletions(-) create mode 100644 notes/v1.0.0.md diff --git a/README.md b/README.md index 88c6be4c52..02c2f7cdc1 100644 --- a/README.md +++ b/README.md @@ -36,3 +36,14 @@ Bloop's documentation lives in [our website](https://scalacenter.github.io/bloop documentation](https://scalacenter.github.io/bloop/docs/developer-documentation/) to learn how to hack on the project, run our community build, improve documentation, etc. + +### Maintainers + +The people that can merge pull requests are: + +1. [Paweł Bartkiewicz](https://github.com/tues) +1. [Ruben Berenguel](https://github.com/Duhemm) +1. [Martin Duhem](https://github.com/Duhemm) +1. [Jorge Vicente Cantero](https://github.com/jvican) +1. You? :smile: Follow our [CONTRIBUTING guide](https://scalacenter.github.io/bloop/docs/developer-documentation/). + diff --git a/frontend/src/main/scala/bloop/cli/Commands.scala b/frontend/src/main/scala/bloop/cli/Commands.scala index e018d98b62..07d76292c8 100644 --- a/frontend/src/main/scala/bloop/cli/Commands.scala +++ b/frontend/src/main/scala/bloop/cli/Commands.scala @@ -63,8 +63,7 @@ object Commands { ) extends RawCommand case class Configure( - @ExtraName("parallelism") - @HelpMessage("Set the number of threads used for parallel compilation and test execution.") + @HelpMessage("Set the number of threads used to compile and test all projects.") threads: Int = ExecutionContext.executor.getCorePoolSize, @Recurse cliOptions: CliOptions = CliOptions.default ) extends RawCommand diff --git a/notes/v1.0.0.md b/notes/v1.0.0.md new file mode 100644 index 0000000000..b9152fda26 --- /dev/null +++ b/notes/v1.0.0.md @@ -0,0 +1,177 @@ +# Install `v1.0.0` :candy: + +If you're on Mac OS X, upgrade to the latest version with: + +```sh +$ brew install scalacenter/bloop/bloop +``` + +Otherwise, run: + +``` +$ curl -L https://github.com/scalacenter/bloop/releases/download/v1.0.0-RC1/install.py | python +``` + +Read the complete installation instructions in our [Installation page][installation instructions]. + +# What is bloop + +Bloop is a Scala build server and command-line tool to make the compile and test developer +workflows fast and productive in a build-tool-agnostic way. Learn more about Bloop and its +origins in [this ScalaDays Berlin talk](https://slideslive.com/38908131). + +Initially as an idea by [Martin Duhem](@Duhemm), Bloop has iterated into its design several times and +materialized into a stable compile/test server that people from different build tools can leverage to +have a faster developer workflow. + +We're in debt with the people that have believed in the project, adopted Bloop and joined our +developer team in the early days, most notably [@tues](https://github.com/tues), +[@fizzy33](https://github.com/fizzy33), [@rberenguel](https://github.com/rberenguel), +[@propensive](https://github.com/propensive), +[@lefou](https://github.com/lefou) and [@tindzk](https://github.com/tindzk). + +Bloop `v1.0.0` is just the beginning. The next `v1.1.0` release will keep focusing on developer +productivity and feature more speedups in compilation. Stay tuned. + +# Highlights :books: + +## A new configuration file format + +The configuration file format is a JSON file that describes the configuration of your project. +It contains a subset of all the configuration keys required to compile, test and run your project +like the project name, source directories, classpath and the like. + +Bloop configuration files are easy to generate, easy to read and easy to modify. Bloop keeps a +strict forward and backward compatibility on the source files in every major version so that +whatever tooling that you build on top of them keeps running in your computers. + +## Compile, test and run your projects quicker! + +After you have exported your build to Bloop configuration files, Bloop can compile, test and +run your projects quicker than any other build tool. Bloop can compile your projects around 20-30% +faster than sbt. + +## Generate bloop configuration files from `sbt`, `Maven` and `mill` + +There are plugin integrations for `sbt`, `Maven` and `mill` that generate configuration files +when the task `bloopInstall` is executed. These integrations allow you to use Bloop for these build +tools. + +A [gradle plugin integration is coming](https://github.com/scalacenter/bloop/pull/566) and will be +merged into 1.1.0. + +## Compile and run Scala Native and Scala.js projects + +Run your Scala Native and Scala.js projects with Bloop. If your build tool supports Scala Native +and Scala.js (like sbt), Bloop's integration will automatically create projects for your Scala +Native and Scala.js projects. Support for tests and incremental linking is left as future work +for 1.1.0. + +# Improvements since 1.0.0-RC1 + +### Log output of server in OSX services (plists) + +The Homebrew formulas now installs plist services that will log stdout and stderr to Bloop's log +directories `/var/log/bloop`. + +### [Upgrade to NuProcess 1.2.4](https://github.com/scalacenter/bloop/pull/587) + +Running Bloop projects in JDK 10 didn't work because [NuProcess][nuprocess] failed to link with the new +process API in JDK 10. Upgrading to the last NuProcess version fixes this issue. + +### [Remove `--isolated` flag and add `--propagate` / `--include-dependencies`](https://github.com/scalacenter/bloop/pull/590) + +The flag `--isolated` has been removed because it was not a good default. In most of the cases, +users want to clean and test a project in isolation, and propagate that to all their dependencies +only in concrete cases. + +As a result, a new flag `--include-dependencies` (aliased to `--propagate`) has been added to +the CLI `test` and `clean` commands. + +### Remove `--parallelism` flag in `bloop configure` + +Remove the `--parallelism` alias of `--threads` to avoid confusion with the future parallel +compilation configuration settings that will be merged in 1.1.0. Use `--threads` instead. + +# Complete changelog + +`v1.0.0` is a release that contains changes that span almost half a year. To fully catch up +with all the changes that have gone into the creation of `v1.0.0`, we redirect users to the +release notes of all our previous versions. + +1. [`v1.0.0-RC1`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-RC1) +1. [`v1.0.0-M11`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M11) +1. [`v1.0.0-M10`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M10) +1. [`v1.0.0-M9`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M9) +1. [`v1.0.0-M8`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M8) +1. [`v1.0.0-M7`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M7) +1. [`v1.0.0-M6`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M6) +1. [`v1.0.0-M5`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M5) +1. [`v1.0.0-M4`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M4) +1. [`v1.0.0-M3`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M3) +1. [`v1.0.0-M2`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M2) +1. [`v1.0.0-M1`](https://github.com/scalacenter/bloop/releases/tag/v1.0.0-M1) + + + +## Contributors :busts_in_silhouette: + +According to `git shortlog -sn --no-merges v1.0.0-M11..1.0.0-RC1`, 27 people contributed to this +`v1.0.0` release: Jorge Vicente Cantero, Martin Duhem, Paweł Bartkiewicz, Ruben Berenguel Montoro, Tim Nieradzik, +msvaljek, Jon Pretty, Jorge, Andrew Valencik, Gabriele Petronella, Olivier Mélois, Sam Halliday, +David Barri, Alexander Samsig, travisltq, Alexey Alekhin, Emilien Taque, Eugene Platonov, +Guillaume Massé, Justin Kaeser, Olivier Melois, Pawel Bartkiewicz, Samantha Li, Sean Sullivan, +Stephen Nancekivell, Tobias Roeser and shamsak58. + +The core team is grateful to all the contributors that have submitted PRs and helped +improved the documentation of Bloop. To a faster developer workflow! :clinking_glasses: + +[installation instructions]: https://scalacenter.github.io/bloop/docs/installation +[configuration]: https://scalacenter.github.io/bloop/docs/configuration-format/ + +[#540]: https://github.com/scalacenter/bloop/pull/540 +[#538]: https://github.com/scalacenter/bloop/pull/538 +[#537]: https://github.com/scalacenter/bloop/pull/537 +[#532]: https://github.com/scalacenter/bloop/pull/532 +[#535]: https://github.com/scalacenter/bloop/pull/535 +[#530]: https://github.com/scalacenter/bloop/pull/530 +[#529]: https://github.com/scalacenter/bloop/pull/529 +[#528]: https://github.com/scalacenter/bloop/pull/528 +[#527]: https://github.com/scalacenter/bloop/pull/527 +[#526]: https://github.com/scalacenter/bloop/pull/526 +[#457]: https://github.com/scalacenter/bloop/pull/457 +[#525]: https://github.com/scalacenter/bloop/pull/525 +[#524]: https://github.com/scalacenter/bloop/pull/524 +[#523]: https://github.com/scalacenter/bloop/pull/523 +[#521]: https://github.com/scalacenter/bloop/pull/521 +[#513]: https://github.com/scalacenter/bloop/pull/513 +[#517]: https://github.com/scalacenter/bloop/pull/517 +[#512]: https://github.com/scalacenter/bloop/pull/512 +[#511]: https://github.com/scalacenter/bloop/pull/511 +[#479]: https://github.com/scalacenter/bloop/pull/479 +[#499]: https://github.com/scalacenter/bloop/pull/499 +[#509]: https://github.com/scalacenter/bloop/pull/509 +[#502]: https://github.com/scalacenter/bloop/pull/502 +[#503]: https://github.com/scalacenter/bloop/pull/503 +[#495]: https://github.com/scalacenter/bloop/pull/495 +[#494]: https://github.com/scalacenter/bloop/pull/494 +[#489]: https://github.com/scalacenter/bloop/pull/489 +[#488]: https://github.com/scalacenter/bloop/pull/488 +[#487]: https://github.com/scalacenter/bloop/pull/487 +[#486]: https://github.com/scalacenter/bloop/pull/486 + +[scala-native-pr-1234]: https://github.com/scala-native/scala-native/pull/1234 +[nuprocess]: https://github.com/brettwooldridge/NuProcess + +[@asamsig]: https://github.com/asamsig +[@Baccata]: https://github.com/Baccata +[@Duhemm]: https://github.com/Duhemm +[@gabro]: https://github.com/gabro +[@jvican]: https://github.com/jvican +[@lefou]: https://github.com/lefou +[@msvaljek]: https://github.com/msvaljek +[@tindzk]: https://github.com/tindzk +[@stephennancekivell]: https://github.com/stephennancekivell +[@travisltq]: https://github.com/travisltq +[@tues]: https://github.com/tues +[@japgolly]: https://github.com/japgollly From 845725d1e213c6990f4607f0f74da550681a759c Mon Sep 17 00:00:00 2001 From: Jorge Vicente Cantero Date: Wed, 18 Jul 2018 16:17:23 +0200 Subject: [PATCH 3/4] Add generator for command documentation `bloop run frontend bloop.util.CommandsDocGenerator` generates the commands documentation automatically. The generation can then be copy-pasted to commands-reference.md. This will prove useful in future changes to the CLI. Fixes https://github.com/scalacenter/bloop/issues/377. --- .../src/main/scala/bloop/cli/CliOptions.scala | 10 +- .../src/main/scala/bloop/cli/CliParsers.scala | 6 +- .../src/main/scala/bloop/cli/Commands.scala | 7 +- .../main/scala/bloop/cli/CommonOptions.scala | 3 +- .../bloop/util/CommandsDocGenerator.scala | 138 +++++ website/content/docs/commands-reference.md | 505 +++++++++--------- 6 files changed, 402 insertions(+), 267 deletions(-) create mode 100644 frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala diff --git a/frontend/src/main/scala/bloop/cli/CliOptions.scala b/frontend/src/main/scala/bloop/cli/CliOptions.scala index bcb19b1669..171bc531bf 100644 --- a/frontend/src/main/scala/bloop/cli/CliOptions.scala +++ b/frontend/src/main/scala/bloop/cli/CliOptions.scala @@ -6,15 +6,17 @@ import caseapp.{ExtraName, HelpMessage, Recurse, ValueDescription} case class CliOptions( @ExtraName("c") - @HelpMessage("File path to the bloop config directory.") + @HelpMessage( + "File path to the bloop config directory, defaults to `.bloop` in the current working directory.") @ValueDescription(".bloop") configDir: Option[Path] = None, @ExtraName("v") - @HelpMessage("If set, print the about section at the beginning of the execution.") + @HelpMessage( + "If set, print the about section at the beginning of the execution. Defaults to false.") version: Boolean = false, - @HelpMessage("If set, print out debugging information to stderr.") + @HelpMessage("If set, print out debugging information to stderr. Defaults to false.") verbose: Boolean = false, - @HelpMessage("If set, do not color output.") + @HelpMessage("If set, do not color output. Defaults to false.") noColor: Boolean = false, @Recurse common: CommonOptions = CommonOptions.default, ) diff --git a/frontend/src/main/scala/bloop/cli/CliParsers.scala b/frontend/src/main/scala/bloop/cli/CliParsers.scala index ba6e09c7e5..b9398e2304 100644 --- a/frontend/src/main/scala/bloop/cli/CliParsers.scala +++ b/frontend/src/main/scala/bloop/cli/CliParsers.scala @@ -16,14 +16,14 @@ object CliParsers { ArgParser.instance[InputStream]("stdin")(_ => Right(System.in)) implicit val printStreamRead: ArgParser[PrintStream] = ArgParser.instance[PrintStream]("stdout")(_ => Right(System.out)) - implicit val pathParser: ArgParser[Path] = ArgParser.instance("A filepath parser") { + implicit val pathParser: ArgParser[Path] = ArgParser.instance("path") { case supposedPath: String => val toPath = Try(Paths.get(supposedPath)).toEither toPath.left.map(t => s"The provided path ${supposedPath} is not valid: '${t.getMessage()}'.") } implicit val completionFormatRead: ArgParser[completion.Format] = { - ArgParser.instance[completion.Format]("format") { + ArgParser.instance[completion.Format]("\"bash\" | \"zsh\"") { case "bash" => Right(completion.BashFormat) case "zsh" => Right(completion.ZshFormat) case w00t => Left(s"Unrecognized format: $w00t") @@ -31,7 +31,7 @@ object CliParsers { } implicit val optimizerConfigRead: ArgParser[OptimizerConfig] = { - ArgParser.instance[OptimizerConfig]("optimize") { + ArgParser.instance[OptimizerConfig]("\"debug\" | \"release\"") { case "debug" => Right(OptimizerConfig.Debug) case "release" => Right(OptimizerConfig.Release) case w00t => Left(s"Unrecognized optimizer config: $w00t") diff --git a/frontend/src/main/scala/bloop/cli/Commands.scala b/frontend/src/main/scala/bloop/cli/Commands.scala index 07d76292c8..3b12d1bec8 100644 --- a/frontend/src/main/scala/bloop/cli/Commands.scala +++ b/frontend/src/main/scala/bloop/cli/Commands.scala @@ -6,7 +6,7 @@ import java.nio.file.Path import bloop.cli.CliParsers.CommandsMessages import bloop.engine.ExecutionContext import bloop.io.AbsolutePath -import caseapp.{ArgsName, CommandName, ExtraName, HelpMessage, Hidden, Recurse} +import caseapp.{CommandName, ExtraName, HelpMessage, Recurse} import caseapp.core.CommandMessages object Commands { @@ -56,7 +56,6 @@ object Commands { ) extends RawCommand case class Projects( - @ExtraName("dot") @HelpMessage("Print out a dot graph you can pipe into `dot`. By default, false.") dotGraph: Boolean = false, @Recurse cliOptions: CliOptions = CliOptions.default @@ -80,18 +79,14 @@ object Commands { @CommandName("bsp") case class Bsp( - @ExtraName("p") @HelpMessage("The connection protocol for the bsp server. By default, local.") protocol: BspProtocol = BspProtocol.Local, - @ExtraName("h") @HelpMessage("The server host for the bsp server (TCP only).") host: String = "127.0.0.1", @HelpMessage("The port for the bsp server (TCP only).") port: Int = 5101, - @ExtraName("s") @HelpMessage("A path to a socket file to communicate through Unix sockets (local only).") socket: Option[Path] = None, - @ExtraName("pn") @HelpMessage( "A path to a new existing socket file to communicate through Unix sockets (local only).") pipeName: Option[String] = None, diff --git a/frontend/src/main/scala/bloop/cli/CommonOptions.scala b/frontend/src/main/scala/bloop/cli/CommonOptions.scala index 7c7294a7ac..cd09058c5f 100644 --- a/frontend/src/main/scala/bloop/cli/CommonOptions.scala +++ b/frontend/src/main/scala/bloop/cli/CommonOptions.scala @@ -23,8 +23,7 @@ case class CommonOptions( @Hidden err: PrintStream = System.err, @Hidden ngout: PrintStream = System.out, @Hidden ngerr: PrintStream = System.err, - @Hidden env: CommonOptions.PrettyProperties = CommonOptions.currentEnv, - threads: Int = ExecutionContext.nCPUs + @Hidden env: CommonOptions.PrettyProperties = CommonOptions.currentEnv ) { def workingPath: AbsolutePath = AbsolutePath(workingDirectory) } diff --git a/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala b/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala new file mode 100644 index 0000000000..a26e0b353e --- /dev/null +++ b/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala @@ -0,0 +1,138 @@ +package bloop.util + +import bloop.Cli +import bloop.cli.{CliParsers, Commands, CommonOptions} +import bloop.engine.Run +import caseapp.{Name, ValueDescription} +import caseapp.core.{Arg, Messages, NameOps, ValueDescriptionOps} + +object CommandsDocGenerator { + def main(args: Array[String]): Unit = { + def generateHTML(commandExamples: Map[String, Seq[String]]): Seq[String] = { + CliParsers.CommandsMessages.messages.map { + case (commandName, messages) => + val examples = commandExamples.getOrElse(commandName, Nil).map { example => + s" * $example" + } + + val argsOption = messages.argsNameOption.map(" <" + _ + ">").mkString + val progName = "bloop" + val b = new StringBuilder + b ++= Messages.NL + b ++= s"## `$progName $commandName$argsOption`" + b ++= Messages.NL + b ++= Messages.NL + b ++= "### Usage" + b ++= Messages.NL + b ++= Messages.NL + b ++= s"
" + b ++= Messages.NL + b ++= optionsMessage(messages.args) + b ++= Messages.NL + b ++= s"
" + b ++= Messages.NL + if (examples.nonEmpty) { + b ++= Messages.NL + b ++= s"### Examples ${Messages.NL}" + b ++= Messages.NL + b ++= examples.mkString(Messages.NL) + } + b.result() + } + } + + parseExamples match { + case Left(msg) => println(s"Error: $msg") + case Right(commandExamples) => + println(generateHTML(commandExamples).mkString(Messages.NL)) + } + } + + def optionsMessage(args: Seq[Arg]): String = { + val options = args.collect { + case arg if !arg.noHelp => + val names = (Name(arg.name) +: arg.extraNames).distinct + val valueDescription = + arg.valueDescription.orElse(if (!arg.isFlag) Some(ValueDescription("value")) else None) + + val message = arg.helpMessage.map(_.message).getOrElse("") + val cmdNames = names.map("" + _.option + "").mkString(" or ") + val usage = s"${Messages.WW}$cmdNames ${valueDescription.map(_.message).mkString}" + val description = + if (message.isEmpty) message + else s"${Messages.NL}

${message}

" + s"
$cmdNames (type: ${arg.hintDescription})
$description" + } + + options.mkString(Messages.NL) + } + + private val ExampleProjectName: String = "foobar" + private val ExampleMainClass: String = "com.acme.Main" + private final val CommandExamples = { + val tmp = java.nio.file.Files.createTempDirectory("tmp") + List( + "bloop projects", + "bloop projects --dot-graph", + s"bloop clean $ExampleProjectName", + s"bloop clean $ExampleProjectName --propagate", + s"bloop bsp --protocol local --socket ${tmp.resolve("socket").toString} --pipe-name windows-name-pipe", + "bloop bsp --protocol tcp --host 127.0.0.1 --port 5101", + s"bloop compile $ExampleProjectName", + s"bloop compile $ExampleProjectName -w", + s"bloop compile $ExampleProjectName --reporter bloop", + s"bloop compile $ExampleProjectName --reporter scalac", + s"bloop test $ExampleProjectName", + s"bloop test $ExampleProjectName -w", + s"bloop test $ExampleProjectName --propagate", + s"bloop test $ExampleProjectName --propagate -w", + s"bloop test $ExampleProjectName --only com.acme.StringSpecification", + s"bloop console $ExampleProjectName", + s"bloop console $ExampleProjectName --exclude-root", + s"bloop run $ExampleProjectName", + s"bloop run $ExampleProjectName -m $ExampleMainClass -- arg1 arg2", + s"bloop run $ExampleProjectName -O debug -- arg1", + s"bloop run $ExampleProjectName -m $ExampleMainClass -O release -w", + s"bloop link $ExampleProjectName", + s"bloop link $ExampleProjectName --main $ExampleMainClass", + s"bloop link $ExampleProjectName -O debug -w", + s"bloop link $ExampleProjectName -O release -w", + s"bloop link $ExampleProjectName --main $ExampleMainClass -w", + ) + } + + private def commandName(cmd: Commands.Command): Option[String] = { + cmd match { + case _: Commands.About => Some("about") + case _: Commands.Projects => Some("projects") + case _: Commands.Clean => Some("clean") + case _: Commands.Bsp => Some("bsp") + case _: Commands.Compile => Some("compile") + case _: Commands.Test => Some("test") + case _: Commands.Console => Some("console") + case _: Commands.Run => Some("run") + case _: Commands.Link => Some("link") + case _ => None + } + } + + case class Example(projectName: String, examples: List[String]) + def parseExamples: Either[String, Map[String, List[String]]] = { + val parsed = CommandExamples.foldLeft[Either[String, List[Example]]](Right(Nil)) { + case (l @ Left(_), _) => l + case (Right(prevExamples), example) => + Cli.parse(example.split(" ").tail, CommonOptions.default) match { + case Run(cmd: Commands.Command, _) => + commandName(cmd) match { + case Some(name) => + Right(Example(name, List(example)) :: prevExamples) + case None => Right(prevExamples) + } + + case a => Left(s"Example $example yielded unrecognized action $a") + } + } + + parsed.map(_.groupBy(_.projectName).mapValues(_.flatMap(_.examples))) + } +} diff --git a/website/content/docs/commands-reference.md b/website/content/docs/commands-reference.md index 9ff4532a8f..b139f783a2 100644 --- a/website/content/docs/commands-reference.md +++ b/website/content/docs/commands-reference.md @@ -8,301 +8,302 @@ bref = "An explanation of all the commands that Bloop provides" toc = true +++ -## `bloop projects` +## `bloop about` + +### Usage + +
+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+
-This commands displays all the projects that have been loaded from the current working directory: -``` -$ bloop projects -Projects loaded from '/Users/martin/foobar/.bloop': - * foobar - * foobar-test -``` +## `bloop autocomplete` -This command can also be used to generate `dot` graph: +### Usage + +
+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+
--mode (type: mode)
+
--format (type: "bash" | "zsh")
+
--command (type: string?)
+
--project (type: string?)
+
-## `bloop compile` -This command takes care of starting compilation for a project and all of its dependencies. +## `bloop bsp` -The supported options are: +### Usage
-
-p or --project
-
-

Select the project to compile. This argument is required, but will be inferred if it's a remaining CLI args.

-

example: bloop compile foobar

-

example: bloop compile -p foobar

-
- -
--incremental
-
-

- Whether to compile the project incrementally. Defaults to true. If this option is - set to false, then the compiler will recompile all the sources. -

-

example: bloop compile foobar --incremental=false

-
- -
--reporter
-
-

- The error reporter to use. By default, Bloop's error reporter is used. The possible choices - are bloop and scalac. -

-

example: bloop compile foobar --reporter scalac -

- -
--watch
-
-

- Whether to re-run the command when the projects' files are modified. Each time one of the - file of the project, or of the dependencies of the project, is modified, the - compile command will be issued again, automatically. -

-

example: bloop compile foobar --watch

-
+
--protocol or -p (type: protocol)
+

The connection protocol for the bsp server. By default, local.

+
--host or -h (type: string)
+

The server host for the bsp server (TCP only).

+
--port (type: int)
+

The port for the bsp server (TCP only).

+
--socket or -s (type: path?)
+

A path to a socket file to communicate through Unix sockets (local only).

+
--pipe-name or --pn (type: string?)
+

A path to a new existing socket file to communicate through Unix sockets (local only).

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

-## `bloop test` -This command runs the tests for one or more projects. +## `bloop clean` + +### Usage + +
+
--project or -p (type: string*)
+

The projects to clean.

+
--include-dependencies or --propagate (type: bool)
+

Run clean for the project's dependencies. By default, false.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+
+ +### Examples + + * bloop clean foobar --propagate + * bloop clean foobar -The supported options are: +## `bloop compile` + +### Usage
-
-p or --project
-
-

Select the project to test. This argument is required, but will be inferred if it's a remaining CLI args.

-

example: bloop test foobar

-

example: bloop test -p foobar

-
- -
--isolated
-
-

- Whether to run the tests only for the specified project, not including its dependencies. By - default, the tests are run for the dependencies of the specified project and the project. -

-

example: bloop test foobar --isolated

-
- -
--reporter
-
-

- The error reporter to use. By default, Bloop's error reporter is use. The possible choices - are bloop and scalac. -

-

example: bloop test foobar --reporter scalac -

- -
--watch
-
-

- Whether to re-run the command when the projects' files are modified. Each time one of the - file of the project, or of the dependencies of the project, is modified, the - test command will be issued again, automatically. -

-

example: bloop test foobar --watch

-
+
--project or -p (type: string)
+

The project to compile (will be inferred from remaining cli args).

+
--incremental (type: bool)
+

Compile the project incrementally. By default, true.

+
--reporter (type: reporter)
+

Pick reporter to show compilation messages. By default, bloop's used.

+
--watch or -w (type: bool)
+

Run the command when projects' source files change. By default, false.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

-## `bloop run` +### Examples -This command is used to run the code of your project. It requires having at least one runnable class -in your project. + * bloop compile foobar --reporter scalac + * bloop compile foobar --reporter bloop + * bloop compile foobar -w + * bloop compile foobar -The supported options are: +## `bloop configure` + +### Usage
-
-p or --project
-
-

Select the project to run. This argument is required, but will be inferred if it's a remaining CLI args.

-

example: bloop run foobar

-

example: bloop run -p foobar

-
- -
-m or --main
-
-

- The fully qualified class name of the class to run. Leave blank to let Bloop select - automatically the class to run. -

-

example: bloop run foobar --main com.acme.Main

-
- -
--reporter
-
-

- The error reporter to use. By default, Bloop's error reporter is use. The possible choices - are bloop and scalac. -

-

example: bloop run foobar --reporter scalac -

- -
--args
-
-

- The arguments to pass to the main() function of the application. it is possible - to specify this option more than once to pass several parameters. -

-

example: bloop run foobar --args hello --args world -

- -
--watch
-
-

- Whether to re-run the command when the projects' files are modified. Each time one of the - file of the project, or of the dependencies of the project, is modified, the - run command will be issued again, automatically. -

-

example: bloop run foobar --watch

-
+
--threads (type: int)
+

Set the number of threads used to compile and test all projects.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+ ## `bloop console` -`bloop console` starts a Scala REPL with your project and its dependencies on the classpath. +### Usage -The following options are supported: +
+
--project or -p (type: string)
+

The project to run the console at (will be inferred from remaining cli args).

+
--reporter (type: reporter)
+

Pick reporter to show compilation messages. By default, bloop's used.

+
--exclude-root (type: bool)
+

Start up the console compiling only the target project's dependencies.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+
+ +### Examples + + * bloop console foobar --exclude-root + * bloop console foobar + +## `bloop help` + +### Usage
-
-p or --project
-
-

Select the project for which to start the console. This argument is required, but will be inferred if it's a remaining CLI args.

-

example: bloop console foobar

-

example: bloop console -p foobar

-
- -
--reporter
-
-

- The error reporter to use. By default, Bloop's error reporter is use. The possible choices - are bloop and scalac. -

-

example: bloop console foobar --reporter scalac -

- -
--exclude-root
-
-

- Use this argument to start the console with all the dependencies of your project on the - classpath, but not the project itself. -

-

example: bloop console foobar --exclude-root -

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

-## `bloop clean` -This command is used to remove the results of the compilation. +## `bloop link` -The following options are supported: +### Usage
-
-p or --project
-
-

Select the project to clean. This argument is required.

-

example: bloop clean -p foobar

-

example: bloop clean foobar

-

example: bloop clean -p foobar foobar-test

-

example: bloop clean foobar foobar-test biz

-
- -
--isolated
-
-

- Set this option if only the specified project should be cleaned, excluding its dependencies. -

-

example: bloop clean -p foobar --isolated -

+
--project or -p (type: string)
+

The project to run (will be inferred from remaining cli args).

+
--main or -m (type: string?)
+

The main class to link. Leave unset to let bloop select automatically.

+
--reporter (type: reporter)
+

Pick reporter to show compilation messages. By default, bloop's used.

+
--watch or -w (type: bool)
+

If set, run the command whenever projects' source files change.

+
--optimize or -O (type: "debug" | "release"?)
+

Optimization level of the linker. Valid options: `debug` or `release` mode. Defaults to `debug`.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

-## `bloop configure` +### Examples + + * bloop link foobar --main com.acme.Main -w + * bloop link foobar -O release -w + * bloop link foobar -O debug -w + * bloop link foobar --main com.acme.Main + * bloop link foobar -This command is used to configure the behavior of the Bloop server. +## `bloop projects` -The following options are supported: +### Usage
-
--threads or --parallelism
-
-

- Configures the maximum number of threads that Bloop should use when doing tasks in - parallel. The default is the number of processors on the machine. -

-

example: bloop configure --threads 8

-
+
--dot-graph or --dot (type: bool)
+

Print out a dot graph you can pipe into `dot`. By default, false.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

-## `bloop bsp` +### Examples -This command is used to start the BSP server. -You can check a specification of BSP here. + * bloop projects --dot-graph + * bloop projects -The following options are supported: +## `bloop run` + +### Usage
-
--p or --protocol
-
-

- The connection protocol that the server should use. Defaults to local. -

-

- The accepted values are local and tcp -

-

- Note - when using the `tcp` protocol, the `--socket` option must be set, too. -

-

example: bloop bsp --protocol tcp

-
- -
--h or --host
-
-

- The hostname of the server. -

-

- Note - this option can only be set when the `--protocol` is set to `tcp`. -

-

example: bloop bsp --protocol tcp --host my-server.com

-
- -
--port
-
-

- The port on which the server is listening. Defaults to 5001 -

-

- Note - this option can only be set when the `--protocol` is set to `tcp`. -

-

example: bloop bsp --protocol tcp --port 65001

-
- -
-s or --socket
-
-

- The path to the UNIX socket file. Ignored if OS is not Unix (Linux, OSX, *bsd). -

-

- Note - this option can only be set when the `--protocol` is set to `local`. You can specify the pipe name as well if you aim to support Windows too. -

-

example: bloop bsp --socket /var/run/bsp

-
- -
--pn or --pipename
-
-

- The name of the Windows communication pipe. Ignored if OS is not Windows. -

-

- Note - this option can only be set when the `--protocol` is set to `local`. You can specify the UNIX socket path if you aim to support UNIX systems too. -

-

example: bloop bsp --protocol local --pipename /var/run/bsp

-
+
--project or -p (type: string)
+

The project to run (will be inferred from remaining cli args). Requires Node.js to be in $PATH for Scala.js.

+
--main or -m (type: string?)
+

The main class to run. Leave unset to let bloop select automatically.

+
--reporter (type: reporter)
+

Pick reporter to show compilation messages. By default, bloop's used.

+
--args (type: string*)
+

The arguments to pass in to the main class.

+
--watch or -w (type: bool)
+

If set, run the command whenever projects' source files change.

+
--optimize or -O (type: "debug" | "release"?)
+

If an optimizer is used (e.g. Scala Native or Scala.js), run it in `debug` or `release` mode. Defaults to `debug`.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+ +### Examples + + * bloop run foobar -m com.acme.Main -O release -w + * bloop run foobar -O debug -- arg1 + * bloop run foobar -m com.acme.Main -- arg1 arg2 + * bloop run foobar + +## `bloop test` + +### Usage + +
+
--project or -p (type: string)
+

The project to test (will be inferred from remaining cli args).

+
--include-dependencies or --propagate (type: bool)
+

Run tests for the project dependencies. By default, false.

+
--only or -o (type: string*)
+

The list of test suite filters to test for only.

+
--args (type: string*)
+

The arguments to pass in to the test framework.

+
--reporter (type: reporter)
+

Pick reporter to show compilation messages. By default, bloop's used.

+
--watch or -w (type: bool)
+

Run the command when projects' source files change. By default, false.

+
--config-dir or -c (type: path?)
+

File path to the bloop config directory.

+
--version or -v (type: bool)
+

If set, print the about section at the beginning of the execution.

+
--verbose (type: bool)
+

If set, print out debugging information to stderr.

+
--no-color (type: bool)
+

If set, do not color output.

+
+ +### Examples + + * bloop test foobar --only com.acme.StringSpecification + * bloop test foobar --propagate -w + * bloop test foobar --propagate + * bloop test foobar -w + * bloop test foobar From 25a50f19c8aeee29cc97539dfbb46c9f4da88442 Mon Sep 17 00:00:00 2001 From: Jorge Vicente Cantero Date: Wed, 18 Jul 2018 16:28:45 +0200 Subject: [PATCH 4/4] Reverse the order of examples in the commands docs --- .../bloop/util/CommandsDocGenerator.scala | 2 +- website/content/docs/commands-reference.md | 34 +++++++++---------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala b/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala index a26e0b353e..2995591261 100644 --- a/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala +++ b/frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala @@ -11,7 +11,7 @@ object CommandsDocGenerator { def generateHTML(commandExamples: Map[String, Seq[String]]): Seq[String] = { CliParsers.CommandsMessages.messages.map { case (commandName, messages) => - val examples = commandExamples.getOrElse(commandName, Nil).map { example => + val examples = commandExamples.getOrElse(commandName, Nil).reverse.map { example => s" * $example" } diff --git a/website/content/docs/commands-reference.md b/website/content/docs/commands-reference.md index b139f783a2..bba4b729d6 100644 --- a/website/content/docs/commands-reference.md +++ b/website/content/docs/commands-reference.md @@ -91,8 +91,8 @@ toc = true ### Examples - * bloop clean foobar --propagate * bloop clean foobar + * bloop clean foobar --propagate ## `bloop compile` @@ -119,10 +119,10 @@ toc = true ### Examples - * bloop compile foobar --reporter scalac - * bloop compile foobar --reporter bloop - * bloop compile foobar -w * bloop compile foobar + * bloop compile foobar -w + * bloop compile foobar --reporter bloop + * bloop compile foobar --reporter scalac ## `bloop configure` @@ -165,8 +165,8 @@ toc = true ### Examples - * bloop console foobar --exclude-root * bloop console foobar + * bloop console foobar --exclude-root ## `bloop help` @@ -211,11 +211,11 @@ toc = true ### Examples - * bloop link foobar --main com.acme.Main -w - * bloop link foobar -O release -w - * bloop link foobar -O debug -w - * bloop link foobar --main com.acme.Main * bloop link foobar + * bloop link foobar --main com.acme.Main + * bloop link foobar -O debug -w + * bloop link foobar -O release -w + * bloop link foobar --main com.acme.Main -w ## `bloop projects` @@ -236,8 +236,8 @@ toc = true ### Examples - * bloop projects --dot-graph * bloop projects + * bloop projects --dot-graph ## `bloop run` @@ -268,10 +268,10 @@ toc = true ### Examples - * bloop run foobar -m com.acme.Main -O release -w - * bloop run foobar -O debug -- arg1 - * bloop run foobar -m com.acme.Main -- arg1 arg2 * bloop run foobar + * bloop run foobar -m com.acme.Main -- arg1 arg2 + * bloop run foobar -O debug -- arg1 + * bloop run foobar -m com.acme.Main -O release -w ## `bloop test` @@ -302,8 +302,8 @@ toc = true ### Examples - * bloop test foobar --only com.acme.StringSpecification - * bloop test foobar --propagate -w - * bloop test foobar --propagate - * bloop test foobar -w * bloop test foobar + * bloop test foobar -w + * bloop test foobar --propagate + * bloop test foobar --propagate -w + * bloop test foobar --only com.acme.StringSpecification