diff --git a/modules/cli/src/main/scala/scala/cli/commands/addpath/AddPathOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/addpath/AddPathOptions.scala index 019e128473..701d4be997 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/addpath/AddPathOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/addpath/AddPathOptions.scala @@ -3,12 +3,15 @@ package scala.cli.commands.addpath import caseapp.* import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.commands.tags // format: off +@HelpMessage("Add entries to the PATH environment variable.") final case class AddPathOptions( @Recurse logging: LoggingOptions = LoggingOptions(), - title: String = "" + @Tag(tags.restricted) + title: String = "" ) extends HasLoggingOptions // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopExitOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopExitOptions.scala index c094e159d5..705f604d60 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopExitOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopExitOptions.scala @@ -2,10 +2,14 @@ package scala.cli.commands.bloop import caseapp.* -import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions} +import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions} // format: off +@HelpMessage( + s"""Stop Bloop if an instance is running. + | + |${HelpMessages.bloopInfo}""".stripMargin) final case class BloopExitOptions( @Recurse logging: LoggingOptions = LoggingOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala index 535fec77b1..df36b6f1f5 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala @@ -2,9 +2,17 @@ package scala.cli.commands.bloop import caseapp.* -import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions} +import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions} +import scala.cli.commands.tags // format: off +@HelpMessage( + s"""Interact with Bloop (the build server) or check its status. + | + |This sub-command allows to check the current status of Bloop. + |If Bloop isn't currently running, it will be started. + | + |${HelpMessages.bloopInfo}""".stripMargin) final case class BloopOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @@ -17,6 +25,7 @@ final case class BloopOptions( @ExtraName("workingDir") @ExtraName("dir") + @Tag(tags.restricted) workingDirectory: Option[String] = None ) extends HasLoggingOptions { // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOutputOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOutputOptions.scala index e324e792d0..81a7ff5e1a 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOutputOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOutputOptions.scala @@ -2,9 +2,13 @@ package scala.cli.commands.bloop import caseapp.* -import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions} +import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions} // format: off +@HelpMessage( + s"""Print Bloop output. + | + |${HelpMessages.bloopInfo}""".stripMargin) final case class BloopOutputOptions( @Recurse logging: LoggingOptions = LoggingOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopStartOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopStartOptions.scala index dcaacbb74a..90ff7ebacb 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopStartOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/bloop/BloopStartOptions.scala @@ -2,9 +2,14 @@ package scala.cli.commands.bloop import caseapp.* -import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions} +import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessages, LoggingOptions, SharedCompilationServerOptions, SharedJvmOptions} +import scala.cli.commands.tags // format: off +@HelpMessage( + s"""Starts a Bloop instance, if none is running. + | + |${HelpMessages.bloopInfo}""".stripMargin) final case class BloopStartOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @@ -15,6 +20,7 @@ final case class BloopStartOptions( @Recurse coursier: CoursierOptions = CoursierOptions(), @Name("f") + @Tag(tags.restricted) force: Boolean = false ) extends HasLoggingOptions // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala index b2a1746bd5..a7fc2793cd 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala @@ -2,10 +2,21 @@ package scala.cli.commands.bsp import caseapp.* -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} +import scala.cli.commands.tags // format: off -@HelpMessage("Start BSP server") +@HelpMessage( + s"""Start BSP server. + | + |BSP stands for Build Server Protocol. + |For more information refer to https://build-server-protocol.github.io/ + | + |This sub-command is not designed to be used by a human. + |It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported. + | + |${HelpMessages.docsWebsiteReference}""".stripMargin) final case class BspOptions( // FIXME There might be too many options in SharedOptions for the bsp command… @Recurse @@ -14,7 +25,8 @@ final case class BspOptions( @HelpMessage("Command-line options JSON file") @ValueDescription("path") @Hidden - jsonOptions: Option[String] = None + @Tag(tags.implementation) + jsonOptions: Option[String] = None ) extends HasSharedOptions { // format: on } diff --git a/modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala index 1bc9e11423..9a1f36de88 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala @@ -2,15 +2,22 @@ package scala.cli.commands.clean import caseapp.* +import scala.cli.ScalaCli.fullRunnerName import scala.cli.commands.shared.{ HasLoggingOptions, + HelpMessages, LoggingOptions, SharedBspFileOptions, SharedWorkspaceOptions } // format: off -@HelpMessage("Clean the workspace") +@HelpMessage( + s"""Clean the workspace. + | + |Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned. + | + |${HelpMessages.commandDocWebsiteReference("clean")}""".stripMargin) final case class CleanOptions( @Recurse logging: LoggingOptions = LoggingOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala index 8b7b56b5f8..947b11a237 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala @@ -3,11 +3,26 @@ package scala.cli.commands.compile import caseapp.* import caseapp.core.help.Help -import scala.cli.commands.shared.{CrossOptions, HasSharedOptions, SharedOptions, SharedWatchOptions} +import scala.cli.commands.shared.{ + CrossOptions, + HasSharedOptions, + HelpMessages, + SharedOptions, + SharedWatchOptions +} import scala.cli.commands.tags +@HelpMessage({ + val cmdName = "compile" + s"""Compile Scala code. + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("Compile Scala code") final case class CompileOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala index 9f867b3285..63556d66fd 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala @@ -2,16 +2,27 @@ package scala.cli.commands.config import caseapp.* +import scala.cli.ScalaCli.{fullRunnerName, progName} import scala.cli.commands.pgp.PgpScalaSigningOptions import scala.cli.commands.shared.{ CoursierOptions, HasLoggingOptions, + HelpMessages, LoggingOptions, SharedJvmOptions } import scala.cli.commands.tags // format: off +@HelpMessage( + s"""Configure global settings for $fullRunnerName. + | + |Syntax: + | $progName ${HelpMessages.PowerString}config key value + |For example, to globally set the interactive mode: + | $progName ${HelpMessages.PowerString}config interactive true + | + |${HelpMessages.commandDocWebsiteReference("misc/config")}""".stripMargin) final case class ConfigOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @@ -25,10 +36,10 @@ final case class ConfigOptions( @Group("Config") @HelpMessage("Dump config DB as JSON") @Hidden + @Tag(tags.implementation) dump: Boolean = false, @Group("Config") @HelpMessage("Create PGP key in config") - @Tag(tags.restricted) createPgpKey: Boolean = false, @Group("Config") @HelpMessage("Email to use to create PGP key in config") @@ -45,6 +56,7 @@ final case class ConfigOptions( @Group("Config") @HelpMessage("Remove an entry from config") @ExtraName("remove") + @Tag(tags.restricted) unset: Boolean = false, @Group("Config") @HelpMessage("For repository.credentials and publish.credentials, whether these credentials should be HTTPS only (default: true)") diff --git a/modules/cli/src/main/scala/scala/cli/commands/default/DefaultFileOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/default/DefaultFileOptions.scala index 7050e9699c..c0239a9041 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/default/DefaultFileOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/default/DefaultFileOptions.scala @@ -2,24 +2,34 @@ package scala.cli.commands.default import caseapp.* -import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions} +import scala.cli.commands.tags // format: off +@HelpMessage( + s"""Generates default files for a $fullRunnerName project (i.e. .gitignore). + | + |${HelpMessages.commandDocWebsiteReference("misc/default-file")}""".stripMargin) final case class DefaultFileOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @Group("Default") @HelpMessage("Write result to files rather than to stdout") + @Tag(tags.restricted) write: Boolean = false, @Group("Default") @HelpMessage("List available default files") + @Tag(tags.restricted) list: Boolean = false, @Group("Default") @HelpMessage("List available default file ids") + @Tag(tags.restricted) listIds: Boolean = false, @Group("Default") @HelpMessage("Force overwriting destination files") @ExtraName("f") + @Tag(tags.restricted) force: Boolean = false ) extends HasLoggingOptions // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/default/LegacyScalaOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/default/LegacyScalaOptions.scala index 662bd19d77..c7708f9ca8 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/default/LegacyScalaOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/default/LegacyScalaOptions.scala @@ -9,6 +9,7 @@ import scala.cli.ScalaCli.{fullRunnerName, progName} import scala.cli.commands.bloop.BloopExit import scala.cli.commands.default.LegacyScalaOptions.* import scala.cli.commands.package0.Package +import scala.cli.commands.shared.HelpMessages.PowerString import scala.cli.commands.shared.ScalacOptions.YScriptRunnerOption import scala.cli.commands.tags @@ -164,9 +165,6 @@ object LegacyScalaOptions { implicit lazy val parser: Parser[LegacyScalaOptions] = Parser.derive implicit lazy val help: Help[LegacyScalaOptions] = Help.derive - private[default] lazy val PowerString = - if ScalaCli.allowRestrictedFeatures then "" else "--power " - def yScriptRunnerWarning(yScriptRunnerValue: Option[String]): String = { val valueSpecificMsg = yScriptRunnerValue match { case Some(v @ "default") => diff --git a/modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala index 35f24b6715..313c4fc809 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala @@ -4,14 +4,16 @@ import caseapp.* import caseapp.core.help.Help import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.commands.tags // format: off -@HelpMessage("Update dependencies in project") +@HelpMessage("Update dependency directives in the project") final case class DependencyUpdateOptions( @Recurse shared: SharedOptions = SharedOptions(), @Group("DependencyUpdate") - @HelpMessage("Update all dependencies if newer version was released") + @HelpMessage("Update all dependencies if a newer version was released") + @Tag(tags.restricted) all: Boolean = false, ) extends HasSharedOptions // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/directories/DirectoriesOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/directories/DirectoriesOptions.scala index 724124b59b..a58f146d8c 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/directories/DirectoriesOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/directories/DirectoriesOptions.scala @@ -2,10 +2,11 @@ package scala.cli.commands.directories import caseapp.* +import scala.cli.ScalaCli.fullRunnerName import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} // format: off -@HelpMessage("Prints directories used by Scala CLI") +@HelpMessage(s"Prints directories used by $fullRunnerName.") final case class DirectoriesOptions( @Recurse logging: LoggingOptions = LoggingOptions() diff --git a/modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala index b2b0757544..8405aaa208 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala @@ -3,11 +3,20 @@ package scala.cli.commands.doc import caseapp.* import caseapp.core.help.Help -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} import scala.cli.commands.tags // format: off -@HelpMessage("Generate Scaladoc documentation", "By default, Scala CLI sets common scaladoc options and this mechanism can be disabled by using `--default-scaladoc-opts:false`.") +@HelpMessage( + message = + s"""Generate Scaladoc documentation. + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference("doc")}""".stripMargin, + messageMd = s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`." +) final case class DocOptions( @Recurse shared: SharedOptions = SharedOptions(), @@ -22,7 +31,7 @@ final case class DocOptions( @Name("f") force: Boolean = false, @Group("Doc") - @HelpMessage("Control if Scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.") + @HelpMessage(s"Control if $fullRunnerName should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.") @Tag(tags.should) @ExtraName("defaultScaladocOpts") defaultScaladocOptions: Option[Boolean] = None, diff --git a/modules/cli/src/main/scala/scala/cli/commands/export/ExportOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/export/ExportOptions.scala deleted file mode 100644 index e10e590bdc..0000000000 --- a/modules/cli/src/main/scala/scala/cli/commands/export/ExportOptions.scala +++ /dev/null @@ -1,38 +0,0 @@ -package scala.cli.commands.export0 - -import caseapp.* - -import scala.cli.commands.shared.{HasSharedOptions, MainClassOptions, SharedOptions} - -// format: off -@HelpMessage("Export current project to sbt or Mill") -final case class ExportOptions( - // FIXME There might be too many options for 'scala-cli export' there - @Recurse - shared: SharedOptions = SharedOptions(), - @Recurse - mainClass: MainClassOptions = MainClassOptions(), - - @Group("Build Tool export options") - sbt: Option[Boolean] = None, - @Group("Build Tool export options") - mill: Option[Boolean] = None, - - @Name("setting") - @Group("Build Tool export options") - sbtSetting: List[String] = Nil, - @Name("p") - @Group("Build Tool export options") - @HelpMessage("Project name to be used on Mill build file") - project: Option[String] = None, - @Group("Build Tool export options") - sbtVersion: Option[String] = None, - @Name("o") - @Group("Build Tool export options") - output: Option[String] = None -) extends HasSharedOptions -// format: on -object ExportOptions { - implicit lazy val parser: Parser[ExportOptions] = Parser.derive - implicit lazy val help: Help[ExportOptions] = Help.derive -} diff --git a/modules/cli/src/main/scala/scala/cli/commands/export/Export.scala b/modules/cli/src/main/scala/scala/cli/commands/export0/Export.scala similarity index 100% rename from modules/cli/src/main/scala/scala/cli/commands/export/Export.scala rename to modules/cli/src/main/scala/scala/cli/commands/export0/Export.scala diff --git a/modules/cli/src/main/scala/scala/cli/commands/export0/ExportOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/export0/ExportOptions.scala new file mode 100644 index 0000000000..db6e293e4c --- /dev/null +++ b/modules/cli/src/main/scala/scala/cli/commands/export0/ExportOptions.scala @@ -0,0 +1,58 @@ +package scala.cli.commands.export0 + +import caseapp.* + +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, MainClassOptions, SharedOptions} +import scala.cli.commands.tags + +// format: off +@HelpMessage( + s"""Export current project to an external build tool (like SBT or Mill). + | + |The whole $fullRunnerName project should get exported along with its dependencies configuration. + | + |Unless otherwise configured, the default export format is SBT. + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.docsWebsiteReference}""".stripMargin) +final case class ExportOptions( + // FIXME There might be too many options for 'scala-cli export' there + @Recurse + shared: SharedOptions = SharedOptions(), + @Recurse + mainClass: MainClassOptions = MainClassOptions(), + + @Group("Build Tool export options") + @Tag(tags.restricted) + @HelpMessage("Sets the export format to SBT") + sbt: Option[Boolean] = None, + @Group("Build Tool export options") + @Tag(tags.restricted) + @HelpMessage("Sets the export format to Mill") + mill: Option[Boolean] = None, + + @Name("setting") + @Group("Build Tool export options") + @Tag(tags.restricted) + sbtSetting: List[String] = Nil, + @Name("p") + @Group("Build Tool export options") + @Tag(tags.restricted) + @HelpMessage("Project name to be used on Mill build file") + project: Option[String] = None, + @Group("Build Tool export options") + @Tag(tags.restricted) + @HelpMessage("Version of SBT to be used for the export") + sbtVersion: Option[String] = None, + @Name("o") + @Group("Build Tool export options") + @Tag(tags.restricted) + output: Option[String] = None +) extends HasSharedOptions +// format: on +object ExportOptions { + implicit lazy val parser: Parser[ExportOptions] = Parser.derive + implicit lazy val help: Help[ExportOptions] = Help.derive +} diff --git a/modules/cli/src/main/scala/scala/cli/commands/fmt/FmtOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/fmt/FmtOptions.scala index ee5e1a0d5f..c834860296 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/fmt/FmtOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/fmt/FmtOptions.scala @@ -7,12 +7,23 @@ import scala.build.EitherCps.{either, value} import scala.build.errors.BuildException import scala.build.internal.FetchExternalBinary import scala.build.options.BuildOptions -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} import scala.cli.commands.{Constants, tags} import scala.util.Properties // format: off -@HelpMessage("Format Scala code") +@HelpMessage( + s"""Formats Scala code. + | + |`scalafmt` is used to perform the formatting under the hood. + | + |The `.scalafmt.conf` configuration file is optional. + |Default configuration values will be assumed by $fullRunnerName. + | + |All standard $fullRunnerName inputs are accepted, but only Scala sources will be formatted (.scala and .sc files). + | + |${HelpMessages.commandDocWebsiteReference("fmt")}""".stripMargin) final case class FmtOptions( @Recurse shared: SharedOptions = SharedOptions(), @@ -49,6 +60,7 @@ final case class FmtOptions( @Hidden scalafmtExtension: Option[String] = None, @Group("Format") + @Tag(tags.implementation) @Hidden scalafmtLauncher: Option[String] = None, @@ -64,6 +76,7 @@ final case class FmtOptions( @Name("scalafmtConfig") scalafmtConf: Option[String] = None, @Group("Format") + @Tag(tags.implementation) @HelpMessage("Pass configuration as a string.") @Name("scalafmtConfigStr") @Name("scalafmtConfSnippet") diff --git a/modules/cli/src/main/scala/scala/cli/commands/github/ListSecretsOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/github/ListSecretsOptions.scala deleted file mode 100644 index 5a222707cc..0000000000 --- a/modules/cli/src/main/scala/scala/cli/commands/github/ListSecretsOptions.scala +++ /dev/null @@ -1,15 +0,0 @@ -package scala.cli.commands.github - -import caseapp.* - -// format: off -final case class ListSecretsOptions( - @Recurse - shared: SharedSecretOptions -) extends HasSharedSecretOptions -// format: on - -object ListSecretsOptions { - implicit lazy val parser: Parser[ListSecretsOptions] = Parser.derive - implicit lazy val help: Help[ListSecretsOptions] = Help.derive -} diff --git a/modules/cli/src/main/scala/scala/cli/commands/github/SecretCreateOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/github/SecretCreateOptions.scala index 212e227884..8e6ca45365 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/github/SecretCreateOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/github/SecretCreateOptions.scala @@ -2,19 +2,28 @@ package scala.cli.commands.github import caseapp.* -import scala.cli.commands.shared.CoursierOptions +import scala.cli.ScalaCli.progName +import scala.cli.commands.shared.{CoursierOptions, HelpMessages} +import scala.cli.commands.tags // format: off +@HelpMessage( + s"""Creates or updates a GitHub repository secret. + | $progName ${HelpMessages.PowerString}github secret create --repo repo-org/repo-name SECRET_VALUE=value:secret + |""".stripMargin) final case class SecretCreateOptions( @Recurse shared: SharedSecretOptions = SharedSecretOptions(), @Recurse coursier: CoursierOptions = CoursierOptions(), + @Tag(tags.restricted) @ExtraName("pubKey") publicKey: Option[String] = None, + @Tag(tags.implementation) @ExtraName("n") dummy: Boolean = false, @Hidden + @Tag(tags.implementation) printRequest: Boolean = false ) extends HasSharedSecretOptions // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/github/SecretList.scala b/modules/cli/src/main/scala/scala/cli/commands/github/SecretList.scala index cbf4d0bfaa..827bbdde7c 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/github/SecretList.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/github/SecretList.scala @@ -12,7 +12,7 @@ import scala.cli.commands.util.ScalaCliSttpBackend import scala.cli.config.Secret import scala.cli.errors.GitHubApiError -object SecretList extends ScalaCommand[ListSecretsOptions] { +object SecretList extends ScalaCommand[SecretListOptions] { override def hidden = false override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED @@ -55,7 +55,7 @@ object SecretList extends ScalaCommand[ListSecretsOptions] { } override def runCommand( - options: ListSecretsOptions, + options: SecretListOptions, args: RemainingArgs, logger: Logger ): Unit = { diff --git a/modules/cli/src/main/scala/scala/cli/commands/github/SecretListOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/github/SecretListOptions.scala new file mode 100644 index 0000000000..8e6086618b --- /dev/null +++ b/modules/cli/src/main/scala/scala/cli/commands/github/SecretListOptions.scala @@ -0,0 +1,16 @@ +package scala.cli.commands.github + +import caseapp.* + +// format: off +@HelpMessage("Lists secrets for a given GitHub repository.") +final case class SecretListOptions( + @Recurse + shared: SharedSecretOptions +) extends HasSharedSecretOptions +// format: on + +object SecretListOptions { + implicit lazy val parser: Parser[SecretListOptions] = Parser.derive + implicit lazy val help: Help[SecretListOptions] = Help.derive +} diff --git a/modules/cli/src/main/scala/scala/cli/commands/github/SharedSecretOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/github/SharedSecretOptions.scala index 596f762198..5065bf6791 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/github/SharedSecretOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/github/SharedSecretOptions.scala @@ -3,6 +3,7 @@ package scala.cli.commands.github import caseapp.* import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.commands.tags import scala.cli.signing.shared.{PasswordOption, Secret} import scala.cli.signing.util.ArgParsers.* @@ -10,8 +11,10 @@ import scala.cli.signing.util.ArgParsers.* final case class SharedSecretOptions( @Recurse logging: LoggingOptions = LoggingOptions(), - token: PasswordOption = PasswordOption.Value(Secret("")), + @Tag(tags.experimental) + token: PasswordOption = PasswordOption.Value(Secret("")), @ExtraName("repo") + @Tag(tags.experimental) repository: String = "" ) extends HasLoggingOptions { // format: on diff --git a/modules/cli/src/main/scala/scala/cli/commands/installcompletions/InstallCompletionsOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/installcompletions/InstallCompletionsOptions.scala index aa52e7e34d..1a10ae6f29 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/installcompletions/InstallCompletionsOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/installcompletions/InstallCompletionsOptions.scala @@ -2,11 +2,15 @@ package scala.cli.commands.installcompletions import caseapp.* -import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions} import scala.cli.commands.tags // format: off -@HelpMessage("Installs completions into your shell") +@HelpMessage( + s"""Installs $fullRunnerName completions into your shell + | + |${HelpMessages.commandDocWebsiteReference("completions")}""".stripMargin) final case class InstallCompletionsOptions( @Recurse logging: LoggingOptions = LoggingOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/installhome/InstallHomeOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/installhome/InstallHomeOptions.scala index 3f9cbbb086..0347e79cb0 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/installhome/InstallHomeOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/installhome/InstallHomeOptions.scala @@ -2,11 +2,12 @@ package scala.cli.commands.installhome import caseapp.* +import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName} import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} import scala.cli.commands.tags // format: off -@HelpMessage("Install Scala CLI in a sub-directory of the home directory") +@HelpMessage(s"Install $fullRunnerName in a sub-directory of the home directory") final case class InstallHomeOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @@ -21,7 +22,7 @@ final case class InstallHomeOptions( @Hidden @Tag(tags.implementation) @HelpMessage("Binary name") - binaryName: String = "scala-cli", + binaryName: String = baseRunnerName, @Tag(tags.implementation) @HelpMessage("Print the update to `env` variable") env: Boolean = false, diff --git a/modules/cli/src/main/scala/scala/cli/commands/package0/PackageOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/package0/PackageOptions.scala index 6831a07a23..5ece2ac5bb 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/package0/PackageOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/package0/PackageOptions.scala @@ -11,17 +11,19 @@ import scala.build.options.* import scala.build.options.packaging.* import scala.build.{BuildThreads, Positioned} import scala.cli.commands.package0.PackageOptions -import scala.cli.commands.shared.{ - CrossOptions, - HasSharedOptions, - MainClassOptions, - SharedJavaOptions, - SharedOptions, - SharedWatchOptions -} +import scala.cli.commands.shared.* +@HelpMessage({ + val cmdName = "package" + s"""Compile and package Scala code. + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("Compile and package Scala code") final case class PackageOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishLocalOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishLocalOptions.scala index d7c8ddcae0..028f91d736 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishLocalOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishLocalOptions.scala @@ -3,16 +3,20 @@ package scala.cli.commands.publish import caseapp.* import scala.cli.commands.pgp.PgpScalaSigningOptions -import scala.cli.commands.shared.{ - CrossOptions, - HasSharedOptions, - MainClassOptions, - SharedOptions, - SharedPythonOptions, - SharedWatchOptions -} +import scala.cli.commands.shared._ // format: off +@HelpMessage( + s"""Publishes build artifacts to the local Ivy2 repository. + | + |The local Ivy2 repository usually lives under `~/.ivy2/local`. + |It is taken into account most of the time by most Scala tools when fetching artifacts. + | + |${HelpMessages.commandConfigurations("publish local")} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference("publishing/publish-local")}""".stripMargin) final case class PublishLocalOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishOptions.scala index 7c6e0e56c1..1586537b5c 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishOptions.scala @@ -2,10 +2,24 @@ package scala.cli.commands.publish import caseapp.* +import scala.cli.ScalaCli.baseRunnerName import scala.cli.commands.pgp.PgpScalaSigningOptions import scala.cli.commands.shared.* // format: off +@HelpMessage( + s"""Publishes build artifacts to Maven repositories. + | + |We recommend running the `publish setup` sub-command once prior to + |running `publish` in order to set missing `using` directives for publishing. + |(but this is not mandatory) + | $baseRunnerName ${HelpMessages.PowerString}publish setup . + | + |${HelpMessages.commandConfigurations("publish")} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference("publishing/publish")}""".stripMargin) final case class PublishOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishSetupOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishSetupOptions.scala index c4b2edca22..d55cdb63e6 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/publish/PublishSetupOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/publish/PublishSetupOptions.scala @@ -8,6 +8,10 @@ import scala.cli.signing.shared.PasswordOption import scala.cli.signing.util.ArgParsers.* // format: off +@HelpMessage( + s"""Configures the project for publishing. + | + |${HelpMessages.commandDocWebsiteReference("publishing/publish-setup")}""".stripMargin) final case class PublishSetupOptions( @Recurse logging: LoggingOptions = LoggingOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/repl/ReplOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/repl/ReplOptions.scala index ee35c8f426..383730869b 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/repl/ReplOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/repl/ReplOptions.scala @@ -2,10 +2,22 @@ package scala.cli.commands.repl import caseapp.* -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.ScalaCli.fullRunnerName +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} +@HelpMessage({ + val cmdName = "repl" + s"""Fire-up a Scala REPL. + | + |The entire $fullRunnerName project's classpath is loaded to the repl. + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("Fire-up a Scala REPL") final case class ReplOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/run/RunOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/run/RunOptions.scala index 144295c1c2..bf6350ee06 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/run/RunOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/run/RunOptions.scala @@ -3,16 +3,29 @@ package scala.cli.commands.run import caseapp.* import caseapp.core.help.Help -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.ScalaCli +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} +@HelpMessage({ + val cmdName = "run" + s"""|Compile and run Scala code. + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |For a run to be successful, a main method must be present on the classpath. + |.sc scripts are an exception, as a main class is provided in their wrapper. + | + |${HelpMessages.acceptedInputs} + | + |To pass arguments to the actual application, just add them after `--`, like: + | + |```sh + |${ScalaCli.progName} run Main.scala AnotherSource.scala -- first-arg second-arg + |``` + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("""|Compile and run Scala code. - | - |To pass arguments to the application, just add them after `--`, like: - | - |```sh - |scala-cli MyApp.scala -- first-arg second-arg - |```""".stripMargin) final case class RunOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/setupide/SetupIdeOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/setupide/SetupIdeOptions.scala index 9239d7fc7d..0622f6f67b 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/setupide/SetupIdeOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/setupide/SetupIdeOptions.scala @@ -2,11 +2,30 @@ package scala.cli.commands.setupide import caseapp.* -import scala.cli.commands.shared.{HasSharedOptions, SharedBspFileOptions, SharedOptions} +import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName} +import scala.cli.commands.shared.{ + HasSharedOptions, + HelpMessages, + SharedBspFileOptions, + SharedOptions +} import scala.cli.commands.tags +@HelpMessage({ + val cmdName = "setup-ide" + s"""Generates a BSP file that you can import into your IDE. + | + |The `setup-ide` sub-command allows to pre-configure a $fullRunnerName project to import to an IDE with BSP support. + |It is also ran implicitly when `compile`, `run`, `shebang` or `test` sub-commands are called. + | + |The pre-configuration should be saved in a BSP json connection file under the path: + | {project-root}/.bsp/$baseRunnerName.json + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("Generate a BSP file that you can import into your IDE") final case class SetupIdeOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/shared/HelpMessages.scala b/modules/cli/src/main/scala/scala/cli/commands/shared/HelpMessages.scala index 5773c85058..b253e5a394 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/shared/HelpMessages.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/shared/HelpMessages.scala @@ -1,5 +1,28 @@ package scala.cli.commands.shared +import scala.cli.ScalaCli + object HelpMessages { - val passwordOption = "A github token used to access GitHub. Not needed in most cases." + lazy val PowerString: String = if ScalaCli.allowRestrictedFeatures then "" else "--power " + val passwordOption = "A github token used to access GitHub. Not needed in most cases." + private val docsWebsiteUrl = "https://scala-cli.virtuslab.org" + val docsWebsiteReference = + s"Detailed documentation can be found on our website: $docsWebsiteUrl" + def commandDocWebsiteReference(websiteSuffix: String): String = + s"For detailed documentation refer to our website: $docsWebsiteUrl/docs/commands/$websiteSuffix" + val installationDocsWebsiteReference = + s"For detailed installation instructions refer to our website: $docsWebsiteUrl/install" + val acceptedInputs: String = + """Multiple inputs can be passed at once. + |Paths to directories, URLs and supported file types are accepted as inputs. + |Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip + |For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md + |All supported types of inputs can be mixed with each other.""".stripMargin + lazy val bloopInfo: String = + s"""Bloop is the build server used by ${ScalaCli.fullRunnerName}. + |For more information about Bloop, refer to https://scalacenter.github.io/bloop/""".stripMargin + def commandConfigurations(cmdName: String): String = + s"""Specific $cmdName configurations can be specified with both command line options and using directives defined in sources. + |Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. + |Using directives can be defined in all supported input source file types.""".stripMargin } diff --git a/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala index 79a319c8da..3e53dc3de1 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/shebang/ShebangOptions.scala @@ -2,36 +2,38 @@ package scala.cli.commands.shebang import caseapp.* +import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName, progName} import scala.cli.commands.run.RunOptions -import scala.cli.commands.shared.{HasSharedOptions, SharedOptions} +import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions} @HelpMessage( - """|Like `run`, but more handy from shebang scripts - | - |This command is equivalent to `run`, but it changes the way - |Scala CLI parses its command-line arguments in order to be compatible - |with shebang scripts. - | - |Normally, inputs and scala-cli options can be mixed. And program arguments have to be - |specified after `--`. - | - |```sh - |scala-cli [command] [scala_cli_options | input]... -- [program_arguments]... - |``` - | - |Contrary, for shebang command, only a single input file can be set, all scala-cli options - |have to be set before the input file, and program arguments after the input file - |```sh - |scala-cli shebang [scala_cli_options]... input [program_arguments]... - |``` - | - |Using this, it is possible to conveniently set up Unix shebang scripts. For example: - |```sh - |#!/usr/bin/env -S scala-cli shebang --scala-version 2.13 - |println("Hello, world) - |``` - | - |""".stripMargin + s"""|Like `run`, but handier for shebang scripts. + | + |This command is equivalent to the `run` sub-command, but it changes the way + |$fullRunnerName parses its command-line arguments in order to be compatible + |with shebang scripts. + | + |When relying on the `run` sub-command, inputs and $baseRunnerName options can be mixed, + |while program args have to be specified after `--` + | + |```sh + |$progName [command] [${baseRunnerName}_options | input]... -- [program_arguments]... + |``` + | + |However, for the `shebang` sub-command, only a single input file can be set, while all $baseRunnerName options + |have to be set before the input file. + |All inputs after the first are treated as program arguments, without the need for `--` + |```sh + |$progName shebang [${baseRunnerName}_options]... input [program_arguments]... + |``` + | + |Using this, it is possible to conveniently set up Unix shebang scripts. For example: + |```sh + |#!/usr/bin/env -S $progName shebang --scala-version 2.13 + |println("Hello, world") + |``` + | + |${HelpMessages.commandDocWebsiteReference("shebang")}""".stripMargin ) final case class ShebangOptions( @Recurse diff --git a/modules/cli/src/main/scala/scala/cli/commands/test/TestOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/test/TestOptions.scala index 1a38f6d85a..4ee9722085 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/test/TestOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/test/TestOptions.scala @@ -6,14 +6,30 @@ import caseapp.core.help.Help import scala.cli.commands.shared.{ CrossOptions, HasSharedOptions, + HelpMessages, SharedJavaOptions, SharedOptions, SharedWatchOptions } import scala.cli.commands.tags +@HelpMessage({ + val cmdName = "test" + s"""Compile and test Scala code. + | + |Test sources are compiled separately (after the 'main' sources), and may use different dependencies, compiler options, and other configurations. + |A source file is treated as a test source if: + | - it contains the `//> using target.scope "test"` directive + | - the file name ends with `.test.scala` + | - the file comes from a directory that is provided as input, and the relative path from that file to its original directory contains a `test` directory + | + |${HelpMessages.commandConfigurations(cmdName)} + | + |${HelpMessages.acceptedInputs} + | + |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin +}) // format: off -@HelpMessage("Compile and test Scala code") final case class TestOptions( @Recurse shared: SharedOptions = SharedOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/uninstall/UninstallOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/uninstall/UninstallOptions.scala index 27485bac1f..b70b68b810 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/uninstall/UninstallOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/uninstall/UninstallOptions.scala @@ -4,13 +4,17 @@ import caseapp.* import java.nio.file.Path +import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName} import scala.cli.commands.bloop.BloopExitOptions -import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions} import scala.cli.commands.tags import scala.cli.commands.uninstallcompletions.SharedUninstallCompletionsOptions // format: off -@HelpMessage("Uninstall scala-cli - only works when installed by the installation script") +@HelpMessage( + s"""Uninstalls $fullRunnerName. + |Works only when installed with the installation script. + |${HelpMessages.installationDocsWebsiteReference}""".stripMargin) final case class UninstallOptions( @Recurse bloopExit: BloopExitOptions = BloopExitOptions(), @@ -18,17 +22,17 @@ final case class UninstallOptions( sharedUninstallCompletions: SharedUninstallCompletionsOptions = SharedUninstallCompletionsOptions(), @Group("Uninstall") @Name("f") - @HelpMessage("Force scala-cli uninstall") + @HelpMessage(s"Force $baseRunnerName uninstall") @Tag(tags.implementation) force: Boolean = false, @Hidden - @HelpMessage("Don't clear scala-cli cache") + @HelpMessage(s"Don't clear $fullRunnerName cache") @Tag(tags.implementation) skipCache: Boolean = false, @Hidden @HelpMessage("Binary name") @Tag(tags.implementation) - binaryName: String = "scala-cli", + binaryName: String = baseRunnerName, @Hidden @HelpMessage("Binary directory") @Tag(tags.implementation) @@ -36,7 +40,7 @@ final case class UninstallOptions( ) extends HasLoggingOptions { override def logging: LoggingOptions = bloopExit.logging // format: on - lazy val binDirPath = binDir.map(os.Path(_, os.pwd)) + lazy val binDirPath: Option[os.Path] = binDir.map(os.Path(_, os.pwd)) } object UninstallOptions { diff --git a/modules/cli/src/main/scala/scala/cli/commands/uninstallcompletions/UninstallCompletionsOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/uninstallcompletions/UninstallCompletionsOptions.scala index bac22e7695..376491d61d 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/uninstallcompletions/UninstallCompletionsOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/uninstallcompletions/UninstallCompletionsOptions.scala @@ -2,11 +2,14 @@ package scala.cli.commands.uninstallcompletions import caseapp.* -import scala.cli.commands.shared.{HasLoggingOptions, LoggingOptions} +import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions} import scala.cli.commands.uninstallcompletions.SharedUninstallCompletionsOptions // format: off -@HelpMessage("Uninstalls completions from your shell") +@HelpMessage( + s"""Uninstalls completions from your shell + | + |${HelpMessages.commandDocWebsiteReference("completions")}""".stripMargin) final case class UninstallCompletionsOptions( @Recurse shared: SharedUninstallCompletionsOptions = SharedUninstallCompletionsOptions(), diff --git a/modules/cli/src/main/scala/scala/cli/commands/update/UpdateOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/update/UpdateOptions.scala index a689d4e823..96893248f7 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/update/UpdateOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/update/UpdateOptions.scala @@ -2,13 +2,17 @@ package scala.cli.commands.update import caseapp.* +import scala.cli.ScalaCli.{baseRunnerName, fullRunnerName} import scala.cli.commands.shared.{HasLoggingOptions, HelpMessages, LoggingOptions} import scala.cli.commands.tags import scala.cli.signing.shared.PasswordOption import scala.cli.signing.util.ArgParsers.* // format: off -@HelpMessage("Update scala-cli - only works when installed by the installation script") +@HelpMessage(s"""Updates $fullRunnerName. + |Works only when installed with the installation script. + |If $fullRunnerName was installed with an external tool, refer to its update methods. + |${HelpMessages.installationDocsWebsiteReference}""".stripMargin) final case class UpdateOptions( @Recurse logging: LoggingOptions = LoggingOptions(), @@ -16,14 +20,14 @@ final case class UpdateOptions( @Group("Update") @HelpMessage("Binary name") @Tag(tags.implementation) - binaryName: String = "scala-cli", + binaryName: String = baseRunnerName, @Hidden @Group("Update") @HelpMessage("Binary directory") @Tag(tags.implementation) binDir: Option[String] = None, @Name("f") - @HelpMessage("Force update scala-cli if is outdated") + @HelpMessage(s"Force update $fullRunnerName if it is outdated") @Tag(tags.implementation) force: Boolean = false, @Hidden diff --git a/modules/cli/src/main/scala/scala/cli/commands/version/VersionOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/version/VersionOptions.scala index 4fc952eb34..0013cdb04c 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/version/VersionOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/version/VersionOptions.scala @@ -10,13 +10,15 @@ import scala.cli.signing.util.ArgParsers.* // format: off @HelpMessage( - """|Print the version of the scala runner and the default version of Scala (unless specified in the project). - | - |The version of the scala runner is the version of the command-line tool that runs Scala programs, which - |is distinct from the Scala version of a program. We recommend you specify the version of Scala of a - |program in the program itself (via a configuration directive). Otherwise, the runner falls back to the default - |Scala version defined by the runner. - |""".stripMargin + s"""|Prints the version of the $fullRunnerName and the default version of Scala (which can be overridden in the project). + |If network connection is available, this sub-command also checks if the installed $fullRunnerName is up-to-date. + | + |The version of the $fullRunnerName is the version of the command-line tool that runs Scala programs, which + |is distinct from the Scala version of the compiler. We recommend to specify the version of the Scala compiler + |for a project in its sources (via a using directive). Otherwise, $fullRunnerName falls back to the default + |Scala version defined by the runner. + | + |${HelpMessages.commandDocWebsiteReference("version")}""".stripMargin ) final case class VersionOptions( @Recurse diff --git a/website/docs/reference/cli-options.md b/website/docs/reference/cli-options.md index 4485044425..b652b6c05d 100644 --- a/website/docs/reference/cli-options.md +++ b/website/docs/reference/cli-options.md @@ -220,7 +220,7 @@ Available in commands: ### `--all` -Update all dependencies if newer version was released +Update all dependencies if a newer version was released ## Doc options @@ -258,8 +258,12 @@ Available in commands: ### `--sbt` +Sets the export format to SBT + ### `--mill` +Sets the export format to Mill + ### `--sbt-setting` Aliases: `--setting` @@ -272,6 +276,8 @@ Project name to be used on Mill build file ### `--sbt-version` +Version of SBT to be used for the export + ### `--output` Aliases: `-o` @@ -345,7 +351,7 @@ Pass scalafmt version before running it (3.6.1 by default). If passed, this over Available in commands: -[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp create`](./commands.md#pgp-create), [`pgp key-id`](./commands.md#pgp-key-id), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`pgp sign`](./commands.md#pgp-sign), [`pgp verify`](./commands.md#pgp-verify), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) +[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp create`](./commands.md#pgp-create), [`pgp key-id`](./commands.md#pgp-key-id), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`pgp sign`](./commands.md#pgp-sign), [`pgp verify`](./commands.md#pgp-verify), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) @@ -519,7 +525,7 @@ Port for BSP debugging Available in commands: -[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) +[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) @@ -1284,7 +1290,7 @@ Turn verbosity on for scalac. This is an alias for --scalac-option -verbose Available in commands: -[`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`github secret create` , `gh secret create`](./commands.md#github-secret-create) +[`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`github secret list` , `gh secret list`](./commands.md#github-secret-list) @@ -1506,7 +1512,7 @@ Force scala-cli uninstall ### `--skip-cache` [Internal] -Don't clear scala-cli cache +Don't clear Scala CLI cache ### `--binary-name` @@ -1562,7 +1568,7 @@ Binary directory Aliases: `-f` -Force update scala-cli if is outdated +Force update Scala CLI if it is outdated ### `--is-internal-run` @@ -1576,7 +1582,7 @@ A github token used to access GitHub. Not needed in most cases. Available in commands: -[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) +[`add-path`](./commands.md#add-path), [`bloop`](./commands.md#bloop), [`bloop exit`](./commands.md#bloop-exit), [`bloop output`](./commands.md#bloop-output), [`bloop start`](./commands.md#bloop-start), [`bsp`](./commands.md#bsp), [`clean`](./commands.md#clean), [`compile`](./commands.md#compile), [`config`](./commands.md#config), [`default-file`](./commands.md#default-file), [`dependency-update`](./commands.md#dependency-update), [`directories`](./commands.md#directories), [`doc`](./commands.md#doc), [`export`](./commands.md#export), [`fmt` , `format` , `scalafmt`](./commands.md#fmt), [`help`](./commands.md#help), [`install completions` , `install-completions`](./commands.md#install-completions), [`install-home`](./commands.md#install-home), [`browse` , `metabrowse`](./commands.md#browse), [`package`](./commands.md#package), [`pgp pull`](./commands.md#pgp-pull), [`pgp push`](./commands.md#pgp-push), [`publish`](./commands.md#publish), [`publish local`](./commands.md#publish-local), [`publish setup`](./commands.md#publish-setup), [`repl` , `console`](./commands.md#repl), [`run`](./commands.md#run), [`github secret create` , `gh secret create`](./commands.md#github-secret-create), [`github secret list` , `gh secret list`](./commands.md#github-secret-list), [`setup-ide`](./commands.md#setup-ide), [`shebang`](./commands.md#shebang), [`test`](./commands.md#test), [`uninstall`](./commands.md#uninstall), [`uninstall completions` , `uninstall-completions`](./commands.md#uninstall-completions), [`update`](./commands.md#update), [`version`](./commands.md#version) diff --git a/website/docs/reference/commands.md b/website/docs/reference/commands.md index b0ea39b467..8fe4865e1f 100644 --- a/website/docs/reference/commands.md +++ b/website/docs/reference/commands.md @@ -8,31 +8,67 @@ sidebar_position: 3 ## clean -Clean the workspace +Clean the workspace. + +Passed inputs will establish the Scala CLI project, for which the workspace will be cleaned. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/clean Accepts option groups: [bsp file](./cli-options.md#bsp-file-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ## compile -Compile Scala code +Compile Scala code. + +Specific compile configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/compile Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [compile](./cli-options.md#compile-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## dependency-update -Update dependencies in project +Update dependency directives in the project Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [dependency update](./cli-options.md#dependency-update-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ## doc -Generate Scaladoc documentation +Generate Scaladoc documentation. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/doc Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [doc](./cli-options.md#doc-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ## export -Export current project to sbt or Mill +Export current project to an external build tool (like SBT or Mill). + +The whole Scala CLI project should get exported along with its dependencies configuration. + +Unless otherwise configured, the default export format is SBT. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +Detailed documentation can be found on our website: https://scala-cli.virtuslab.org Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [export](./cli-options.md#export-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) @@ -40,7 +76,16 @@ Accepts option groups: [compilation server](./cli-options.md#compilation-server- Aliases: `format`, `scalafmt` -Format Scala code +Formats Scala code. + +`scalafmt` is used to perform the formatting under the hood. + +The `.scalafmt.conf` configuration file is optional. +Default configuration values will be assumed by Scala CLI. + +All standard Scala CLI inputs are accepted, but only Scala sources will be formatted (.scala and .sc files). + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/fmt Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [fmt](./cli-options.md#fmt-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) @@ -54,7 +99,9 @@ Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity]( Aliases: `install-completions` -Installs completions into your shell +Installs Scala CLI completions into your shell + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions Accepts option groups: [install completions](./cli-options.md#install-completions-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) @@ -62,98 +109,218 @@ Accepts option groups: [install completions](./cli-options.md#install-completion Aliases: `console` -Fire-up a Scala REPL +Fire-up a Scala REPL. + +The entire Scala CLI project's classpath is loaded to the repl. + +Specific repl configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/repl Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [repl](./cli-options.md#repl-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## package -Compile and package Scala code +Compile and package Scala code. + +Specific package configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/package Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [package](./cli-options.md#package-options), [packager](./cli-options.md#packager-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## publish +Publishes build artifacts to Maven repositories. + +We recommend running the `publish setup` sub-command once prior to +running `publish` in order to set missing `using` directives for publishing. +(but this is not mandatory) + scala-cli publish setup . + +Specific publish configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/publishing/publish + Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [pgp scala signing](./cli-options.md#pgp-scala-signing-options), [publish](./cli-options.md#publish-options), [publish params](./cli-options.md#publish-params-options), [publish repository](./cli-options.md#publish-repository-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## publish local +Publishes build artifacts to the local Ivy2 repository. + +The local Ivy2 repository usually lives under `~/.ivy2/local`. +It is taken into account most of the time by most Scala tools when fetching artifacts. + +Specific publish local configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/publishing/publish-local + Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [pgp scala signing](./cli-options.md#pgp-scala-signing-options), [publish](./cli-options.md#publish-options), [publish params](./cli-options.md#publish-params-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## publish setup +Configures the project for publishing. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/publishing/publish-setup + Accepts option groups: [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [pgp push pull](./cli-options.md#pgp-push-pull-options), [pgp scala signing](./cli-options.md#pgp-scala-signing-options), [publish params](./cli-options.md#publish-params-options), [publish repository](./cli-options.md#publish-repository-options), [publish setup](./cli-options.md#publish-setup-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ## run Compile and run Scala code. -To pass arguments to the application, just add them after `--`, like: +Specific run configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For a run to be successful, a main method must be present on the classpath. +.sc scripts are an exception, as a main class is provided in their wrapper. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +To pass arguments to the actual application, just add them after `--`, like: ```sh -scala-cli MyApp.scala -- first-arg second-arg +scala-cli run Main.scala AnotherSource.scala -- first-arg second-arg ``` +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/run + Accepts option groups: [benchmarking](./cli-options.md#benchmarking-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [run](./cli-options.md#run-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## github secret create Aliases: `gh secret create` +Creates or updates a GitHub repository secret. + scala-cli github secret create --repo repo-org/repo-name SECRET_VALUE=value:secret + + Accepts option groups: [coursier](./cli-options.md#coursier-options), [logging](./cli-options.md#logging-options), [secret](./cli-options.md#secret-options), [secret create](./cli-options.md#secret-create-options), [verbosity](./cli-options.md#verbosity-options) ## github secret list Aliases: `gh secret list` +Lists secrets for a given GitHub repository. + Accepts option groups: [logging](./cli-options.md#logging-options), [secret](./cli-options.md#secret-options), [verbosity](./cli-options.md#verbosity-options) ## setup-ide -Generate a BSP file that you can import into your IDE +Generates a BSP file that you can import into your IDE. + +The `setup-ide` sub-command allows to pre-configure a Scala CLI project to import to an IDE with BSP support. +It is also ran implicitly when `compile`, `run`, `shebang` or `test` sub-commands are called. + +The pre-configuration should be saved in a BSP json connection file under the path: + {project-root}/.bsp/scala-cli.json + +Specific setup-ide configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/setup-ide Accepts option groups: [bsp file](./cli-options.md#bsp-file-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [setup IDE](./cli-options.md#setup-ide-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ## shebang -Like `run`, but more handy from shebang scripts +Like `run`, but handier for shebang scripts. -This command is equivalent to `run`, but it changes the way +This command is equivalent to the `run` sub-command, but it changes the way Scala CLI parses its command-line arguments in order to be compatible with shebang scripts. -Normally, inputs and scala-cli options can be mixed. And program arguments have to be -specified after `--`. +When relying on the `run` sub-command, inputs and scala-cli options can be mixed, +while program args have to be specified after `--` ```sh -scala-cli [command] [scala_cli_options | input]... -- [program_arguments]... +scala-cli [command] [scala-cli_options | input]... -- [program_arguments]... ``` -Contrary, for shebang command, only a single input file can be set, all scala-cli options -have to be set before the input file, and program arguments after the input file +However, for the `shebang` sub-command, only a single input file can be set, while all scala-cli options +have to be set before the input file. +All inputs after the first are treated as program arguments, without the need for `--` ```sh -scala-cli shebang [scala_cli_options]... input [program_arguments]... +scala-cli shebang [scala-cli_options]... input [program_arguments]... ``` Using this, it is possible to conveniently set up Unix shebang scripts. For example: ```sh #!/usr/bin/env -S scala-cli shebang --scala-version 2.13 -println("Hello, world) +println("Hello, world") ``` - +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/shebang Accepts option groups: [benchmarking](./cli-options.md#benchmarking-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [run](./cli-options.md#run-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## test -Compile and test Scala code +Compile and test Scala code. + +Test sources are compiled separately (after the 'main' sources), and may use different dependencies, compiler options, and other configurations. +A source file is treated as a test source if: + - it contains the `//> using target.scope "test"` directive + - the file name ends with `.test.scala` + - the file comes from a directory that is provided as input, and the relative path from that file to its original directory contains a `test` directory + +Specific test configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/test Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [test](./cli-options.md#test-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ## uninstall -Uninstall scala-cli - only works when installed by the installation script +Uninstalls Scala CLI. +Works only when installed with the installation script. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [logging](./cli-options.md#logging-options), [uninstall](./cli-options.md#uninstall-options), [uninstall completions](./cli-options.md#uninstall-completions-options), [verbosity](./cli-options.md#verbosity-options) @@ -163,23 +330,30 @@ Aliases: `uninstall-completions` Uninstalls completions from your shell +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions + Accepts option groups: [logging](./cli-options.md#logging-options), [uninstall completions](./cli-options.md#uninstall-completions-options), [verbosity](./cli-options.md#verbosity-options) ## update -Update scala-cli - only works when installed by the installation script +Updates Scala CLI. +Works only when installed with the installation script. +If Scala CLI was installed with an external tool, refer to its update methods. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install Accepts option groups: [logging](./cli-options.md#logging-options), [update](./cli-options.md#update-options), [verbosity](./cli-options.md#verbosity-options) ## version -Print the version of the scala runner and the default version of Scala (unless specified in the project). +Prints the version of the Scala CLI and the default version of Scala (which can be overridden in the project). +If network connection is available, this sub-command also checks if the installed Scala CLI is up-to-date. -The version of the scala runner is the version of the command-line tool that runs Scala programs, which -is distinct from the Scala version of a program. We recommend you specify the version of Scala of a -program in the program itself (via a configuration directive). Otherwise, the runner falls back to the default +The version of the Scala CLI is the version of the command-line tool that runs Scala programs, which +is distinct from the Scala version of the compiler. We recommend to specify the version of the Scala compiler +for a project in its sources (via a using directive). Otherwise, Scala CLI falls back to the default Scala version defined by the runner. +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/version Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options), [version](./cli-options.md#version-options) @@ -187,41 +361,87 @@ Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity]( ### add-path +Add entries to the PATH environment variable. + Accepts option groups: [add path](./cli-options.md#add-path-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### bloop +Interact with Bloop (the build server) or check its status. + +This sub-command allows to check the current status of Bloop. +If Bloop isn't currently running, it will be started. + +Bloop is the build server used by Scala CLI. +For more information about Bloop, refer to https://scalacenter.github.io/bloop/ + Accepts option groups: [bloop](./cli-options.md#bloop-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### bloop exit +Stop Bloop if an instance is running. + +Bloop is the build server used by Scala CLI. +For more information about Bloop, refer to https://scalacenter.github.io/bloop/ + Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### bloop output +Print Bloop output. + +Bloop is the build server used by Scala CLI. +For more information about Bloop, refer to https://scalacenter.github.io/bloop/ + Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### bloop start +Starts a Bloop instance, if none is running. + +Bloop is the build server used by Scala CLI. +For more information about Bloop, refer to https://scalacenter.github.io/bloop/ + Accepts option groups: [bloop start](./cli-options.md#bloop-start-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### bsp -Start BSP server +Start BSP server. + +BSP stands for Build Server Protocol. +For more information refer to https://build-server-protocol.github.io/ + +This sub-command is not designed to be used by a human. +It is normally supposed to be invoked by your IDE when a Scala CLI project is imported. + +Detailed documentation can be found on our website: https://scala-cli.virtuslab.org Accepts option groups: [bsp](./cli-options.md#bsp-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ### config +Configure global settings for Scala CLI. + +Syntax: + scala-cli config key value +For example, to globally set the interactive mode: + scala-cli config interactive true + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/misc/config + Accepts option groups: [config](./cli-options.md#config-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [pgp scala signing](./cli-options.md#pgp-scala-signing-options), [verbosity](./cli-options.md#verbosity-options) ### default-file +Generates default files for a Scala CLI project (i.e. .gitignore). + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/misc/default-file + Accepts option groups: [default file](./cli-options.md#default-file-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) ### directories -Prints directories used by Scala CLI +Prints directories used by Scala CLI. Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) diff --git a/website/docs/reference/scala-command/cli-options.md b/website/docs/reference/scala-command/cli-options.md index 878f60322b..324b2e9052 100644 --- a/website/docs/reference/scala-command/cli-options.md +++ b/website/docs/reference/scala-command/cli-options.md @@ -1070,7 +1070,7 @@ Force scala-cli uninstall `IMPLEMENTATION specific` per Scala Runner specification -Don't clear scala-cli cache +Don't clear Scala CLI cache ### `--binary-name` @@ -1136,7 +1136,7 @@ Aliases: `-f` `IMPLEMENTATION specific` per Scala Runner specification -Force update scala-cli if is outdated +Force update Scala CLI if it is outdated ### `--is-internal-run` @@ -1291,13 +1291,11 @@ Available in commands: Dump config DB as JSON -### `--unset` - -Aliases: `--remove` +### `--create-pgp-key` `IMPLEMENTATION specific` per Scala Runner specification -Remove an entry from config +Create PGP key in config ### Coursier options diff --git a/website/docs/reference/scala-command/commands.md b/website/docs/reference/scala-command/commands.md index 7cffc78285..7b12c1cfef 100644 --- a/website/docs/reference/scala-command/commands.md +++ b/website/docs/reference/scala-command/commands.md @@ -17,17 +17,46 @@ that is reserved for commands that need to be present for Scala CLI to work prop ### compile -Compile Scala code +Compile Scala code. + +Specific compile configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/compile Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [compile](./cli-options.md#compile-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ### config +Configure global settings for Scala CLI. + +Syntax: + scala-cli config key value +For example, to globally set the interactive mode: + scala-cli config interactive true + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/misc/config + Accepts option groups: [config](./cli-options.md#config-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [pgp scala signing](./cli-options.md#pgp-scala-signing-options), [verbosity](./cli-options.md#verbosity-options) ### doc -Generate Scaladoc documentation +Generate Scaladoc documentation. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/doc Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [doc](./cli-options.md#doc-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) @@ -35,7 +64,21 @@ Accepts option groups: [compilation server](./cli-options.md#compilation-server- Aliases: `console` -Fire-up a Scala REPL +Fire-up a Scala REPL. + +The entire Scala CLI project's classpath is loaded to the repl. + +Specific repl configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/repl Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [repl](./cli-options.md#repl-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) @@ -43,42 +86,58 @@ Accepts option groups: [compilation server](./cli-options.md#compilation-server- Compile and run Scala code. -To pass arguments to the application, just add them after `--`, like: +Specific run configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For a run to be successful, a main method must be present on the classpath. +.sc scripts are an exception, as a main class is provided in their wrapper. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +To pass arguments to the actual application, just add them after `--`, like: ```sh -scala-cli MyApp.scala -- first-arg second-arg +scala-cli run Main.scala AnotherSource.scala -- first-arg second-arg ``` +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/run + Accepts option groups: [benchmarking](./cli-options.md#benchmarking-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [run](./cli-options.md#run-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ### shebang -Like `run`, but more handy from shebang scripts +Like `run`, but handier for shebang scripts. -This command is equivalent to `run`, but it changes the way +This command is equivalent to the `run` sub-command, but it changes the way Scala CLI parses its command-line arguments in order to be compatible with shebang scripts. -Normally, inputs and scala-cli options can be mixed. And program arguments have to be -specified after `--`. +When relying on the `run` sub-command, inputs and scala-cli options can be mixed, +while program args have to be specified after `--` ```sh -scala-cli [command] [scala_cli_options | input]... -- [program_arguments]... +scala-cli [command] [scala-cli_options | input]... -- [program_arguments]... ``` -Contrary, for shebang command, only a single input file can be set, all scala-cli options -have to be set before the input file, and program arguments after the input file +However, for the `shebang` sub-command, only a single input file can be set, while all scala-cli options +have to be set before the input file. +All inputs after the first are treated as program arguments, without the need for `--` ```sh -scala-cli shebang [scala_cli_options]... input [program_arguments]... +scala-cli shebang [scala-cli_options]... input [program_arguments]... ``` Using this, it is possible to conveniently set up Unix shebang scripts. For example: ```sh #!/usr/bin/env -S scala-cli shebang --scala-version 2.13 -println("Hello, world) +println("Hello, world") ``` - +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/shebang Accepts option groups: [benchmarking](./cli-options.md#benchmarking-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [main class](./cli-options.md#main-class-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [run](./cli-options.md#run-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) @@ -88,25 +147,54 @@ Accepts option groups: [benchmarking](./cli-options.md#benchmarking-options), [c Aliases: `format`, `scalafmt` -Format Scala code +Formats Scala code. + +`scalafmt` is used to perform the formatting under the hood. + +The `.scalafmt.conf` configuration file is optional. +Default configuration values will be assumed by Scala CLI. + +All standard Scala CLI inputs are accepted, but only Scala sources will be formatted (.scala and .sc files). + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/fmt Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [fmt](./cli-options.md#fmt-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ### test -Compile and test Scala code +Compile and test Scala code. + +Test sources are compiled separately (after the 'main' sources), and may use different dependencies, compiler options, and other configurations. +A source file is treated as a test source if: + - it contains the `//> using target.scope "test"` directive + - the file name ends with `.test.scala` + - the file comes from a directory that is provided as input, and the relative path from that file to its original directory contains a `test` directory + +Specific test configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/test Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [cross](./cli-options.md#cross-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [java](./cli-options.md#java-options), [java prop](./cli-options.md#java-prop-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [test](./cli-options.md#test-options), [verbosity](./cli-options.md#verbosity-options), [watch](./cli-options.md#watch-options), [workspace](./cli-options.md#workspace-options) ### version -Print the version of the scala runner and the default version of Scala (unless specified in the project). +Prints the version of the Scala CLI and the default version of Scala (which can be overridden in the project). +If network connection is available, this sub-command also checks if the installed Scala CLI is up-to-date. -The version of the scala runner is the version of the command-line tool that runs Scala programs, which -is distinct from the Scala version of a program. We recommend you specify the version of Scala of a -program in the program itself (via a configuration directive). Otherwise, the runner falls back to the default +The version of the Scala CLI is the version of the command-line tool that runs Scala programs, which +is distinct from the Scala version of the compiler. We recommend to specify the version of the Scala compiler +for a project in its sources (via a using directive). Otherwise, Scala CLI falls back to the default Scala version defined by the runner. +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/version Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options), [version](./cli-options.md#version-options) @@ -116,13 +204,25 @@ Commands which are used within Scala CLI and should be a part of the `scala` com ### bsp -Start BSP server +Start BSP server. + +BSP stands for Build Server Protocol. +For more information refer to https://build-server-protocol.github.io/ + +This sub-command is not designed to be used by a human. +It is normally supposed to be invoked by your IDE when a Scala CLI project is imported. + +Detailed documentation can be found on our website: https://scala-cli.virtuslab.org Accepts option groups: [bsp](./cli-options.md#bsp-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ### clean -Clean the workspace +Clean the workspace. + +Passed inputs will establish the Scala CLI project, for which the workspace will be cleaned. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/clean Accepts option groups: [bsp file](./cli-options.md#bsp-file-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) @@ -136,7 +236,9 @@ Accepts option groups: [logging](./cli-options.md#logging-options), [verbosity]( Aliases: `install-completions` -Installs completions into your shell +Installs Scala CLI completions into your shell + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions Accepts option groups: [install completions](./cli-options.md#install-completions-options), [logging](./cli-options.md#logging-options), [verbosity](./cli-options.md#verbosity-options) @@ -148,13 +250,27 @@ Accepts option groups: [install home](./cli-options.md#install-home-options), [l ### setup-ide -Generate a BSP file that you can import into your IDE +Generates a BSP file that you can import into your IDE. + +The `setup-ide` sub-command allows to pre-configure a Scala CLI project to import to an IDE with BSP support. +It is also ran implicitly when `compile`, `run`, `shebang` or `test` sub-commands are called. + +The pre-configuration should be saved in a BSP json connection file under the path: + {project-root}/.bsp/scala-cli.json + +Specific setup-ide configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/setup-ide Accepts option groups: [bsp file](./cli-options.md#bsp-file-options), [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [debug](./cli-options.md#debug-options), [dependency](./cli-options.md#dependency-options), [help group](./cli-options.md#help-group-options), [input](./cli-options.md#input-options), [jvm](./cli-options.md#jvm-options), [logging](./cli-options.md#logging-options), [markdown](./cli-options.md#markdown-options), [python](./cli-options.md#python-options), [Scala.js](./cli-options.md#scalajs-options), [Scala Native](./cli-options.md#scala-native-options), [scalac](./cli-options.md#scalac-options), [scalac extra](./cli-options.md#scalac-extra-options), [setup IDE](./cli-options.md#setup-ide-options), [shared](./cli-options.md#shared-options), [snippet](./cli-options.md#snippet-options), [suppress warning](./cli-options.md#suppress-warning-options), [verbosity](./cli-options.md#verbosity-options), [workspace](./cli-options.md#workspace-options) ### uninstall -Uninstall scala-cli - only works when installed by the installation script +Uninstalls Scala CLI. +Works only when installed with the installation script. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install Accepts option groups: [compilation server](./cli-options.md#compilation-server-options), [coursier](./cli-options.md#coursier-options), [logging](./cli-options.md#logging-options), [uninstall](./cli-options.md#uninstall-options), [uninstall completions](./cli-options.md#uninstall-completions-options), [verbosity](./cli-options.md#verbosity-options) @@ -164,11 +280,16 @@ Aliases: `uninstall-completions` Uninstalls completions from your shell +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions + Accepts option groups: [logging](./cli-options.md#logging-options), [uninstall completions](./cli-options.md#uninstall-completions-options), [verbosity](./cli-options.md#verbosity-options) ### update -Update scala-cli - only works when installed by the installation script +Updates Scala CLI. +Works only when installed with the installation script. +If Scala CLI was installed with an external tool, refer to its update methods. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install Accepts option groups: [logging](./cli-options.md#logging-options), [update](./cli-options.md#update-options), [verbosity](./cli-options.md#verbosity-options) diff --git a/website/docs/reference/scala-command/runner-specification.md b/website/docs/reference/scala-command/runner-specification.md index b22e8d91ee..85c0a674a1 100644 --- a/website/docs/reference/scala-command/runner-specification.md +++ b/website/docs/reference/scala-command/runner-specification.md @@ -46,7 +46,19 @@ are assumed to be Scala compiler options and will be propagated to Scala Compile ## `compile` command **MUST have for Scala Runner specification.** -Compile Scala code +Compile Scala code. + +Specific compile configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/compile ### MUST have options @@ -551,6 +563,15 @@ Aliases: `--toolkit` ## `config` command **MUST have for Scala Runner specification.** +Configure global settings for Scala CLI. + +Syntax: + scala-cli config key value +For example, to globally set the interactive mode: + scala-cli config interactive true + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/misc/config + ### SHOULD have options **--debug** @@ -677,11 +698,9 @@ Whether to run the Scala Signing CLI on the JVM or using a native executable Dump config DB as JSON -**--unset** - -Remove an entry from config +**--create-pgp-key** -Aliases: `--remove` +Create PGP key in config @@ -690,7 +709,15 @@ Aliases: `--remove` ## `doc` command **MUST have for Scala Runner specification.** -Generate Scaladoc documentation +Generate Scaladoc documentation. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/doc ### MUST have options @@ -1199,7 +1226,21 @@ Aliases: `--toolkit` Aliases: `console` -Fire-up a Scala REPL +Fire-up a Scala REPL. + +The entire Scala CLI project's classpath is loaded to the repl. + +Specific repl configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/repl ### MUST have options @@ -1718,12 +1759,27 @@ Don't actually run the REPL, just fetch it Compile and run Scala code. -To pass arguments to the application, just add them after `--`, like: +Specific run configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For a run to be successful, a main method must be present on the classpath. +.sc scripts are an exception, as a main class is provided in their wrapper. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +To pass arguments to the actual application, just add them after `--`, like: ```sh -scala-cli MyApp.scala -- first-arg second-arg +scala-cli run Main.scala AnotherSource.scala -- first-arg second-arg ``` +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/run + ### MUST have options **--dependency** @@ -2259,32 +2315,33 @@ Run Java commands using a manifest-based class path (shortens command length) ## `shebang` command **MUST have for Scala Runner specification.** -Like `run`, but more handy from shebang scripts +Like `run`, but handier for shebang scripts. -This command is equivalent to `run`, but it changes the way +This command is equivalent to the `run` sub-command, but it changes the way Scala CLI parses its command-line arguments in order to be compatible with shebang scripts. -Normally, inputs and scala-cli options can be mixed. And program arguments have to be -specified after `--`. +When relying on the `run` sub-command, inputs and scala-cli options can be mixed, +while program args have to be specified after `--` ```sh -scala-cli [command] [scala_cli_options | input]... -- [program_arguments]... +scala-cli [command] [scala-cli_options | input]... -- [program_arguments]... ``` -Contrary, for shebang command, only a single input file can be set, all scala-cli options -have to be set before the input file, and program arguments after the input file +However, for the `shebang` sub-command, only a single input file can be set, while all scala-cli options +have to be set before the input file. +All inputs after the first are treated as program arguments, without the need for `--` ```sh -scala-cli shebang [scala_cli_options]... input [program_arguments]... +scala-cli shebang [scala-cli_options]... input [program_arguments]... ``` Using this, it is possible to conveniently set up Unix shebang scripts. For example: ```sh #!/usr/bin/env -S scala-cli shebang --scala-version 2.13 -println("Hello, world) +println("Hello, world") ``` - +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/shebang ### MUST have options @@ -2825,7 +2882,16 @@ Run Java commands using a manifest-based class path (shortens command length) Aliases: `format`, `scalafmt` -Format Scala code +Formats Scala code. + +`scalafmt` is used to perform the formatting under the hood. + +The `.scalafmt.conf` configuration file is optional. +Default configuration values will be assumed by Scala CLI. + +All standard Scala CLI inputs are accepted, but only Scala sources will be formatted (.scala and .sc files). + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/fmt ### MUST have options @@ -3376,7 +3442,25 @@ Aliases: `--fmt-version` ## `test` command **SHOULD have for Scala Runner specification.** -Compile and test Scala code +Compile and test Scala code. + +Test sources are compiled separately (after the 'main' sources), and may use different dependencies, compiler options, and other configurations. +A source file is treated as a test source if: + - it contains the `//> using target.scope "test"` directive + - the file name ends with `.test.scala` + - the file comes from a directory that is provided as input, and the relative path from that file to its original directory contains a `test` directory + +Specific test configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +Multiple inputs can be passed at once. +Paths to directories, URLs and supported file types are accepted as inputs. +Accepted file extensions: .scala, .sc, .java, .jar, .md, .jar, .c, .h, .zip +For piped inputs use the corresponding alias: _.scala, _.java, _.sc, _.md +All supported types of inputs can be mixed with each other. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/test ### MUST have options @@ -3901,13 +3985,15 @@ Aliases: `--java-prop` ## `version` command **SHOULD have for Scala Runner specification.** -Print the version of the scala runner and the default version of Scala (unless specified in the project). +Prints the version of the Scala CLI and the default version of Scala (which can be overridden in the project). +If network connection is available, this sub-command also checks if the installed Scala CLI is up-to-date. -The version of the scala runner is the version of the command-line tool that runs Scala programs, which -is distinct from the Scala version of a program. We recommend you specify the version of Scala of a -program in the program itself (via a configuration directive). Otherwise, the runner falls back to the default +The version of the Scala CLI is the version of the command-line tool that runs Scala programs, which +is distinct from the Scala version of the compiler. We recommend to specify the version of the Scala compiler +for a project in its sources (via a using directive). Otherwise, Scala CLI falls back to the default Scala version defined by the runner. +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/version
@@ -3980,7 +4066,15 @@ Don't check for the newest available Scala CLI version upstream ## `bsp` command **IMPLEMENTATION specific for Scala Runner specification.** -Start BSP server +Start BSP server. + +BSP stands for Build Server Protocol. +For more information refer to https://build-server-protocol.github.io/ + +This sub-command is not designed to be used by a human. +It is normally supposed to be invoked by your IDE when a Scala CLI project is imported. + +Detailed documentation can be found on our website: https://scala-cli.virtuslab.org ### MUST have options @@ -4473,7 +4567,11 @@ Command-line options JSON file ## `clean` command **IMPLEMENTATION specific for Scala Runner specification.** -Clean the workspace +Clean the workspace. + +Passed inputs will establish the Scala CLI project, for which the workspace will be cleaned. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/clean
@@ -4605,7 +4703,9 @@ Use progress bars Aliases: `install-completions` -Installs completions into your shell +Installs Scala CLI completions into your shell + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions
@@ -4769,7 +4869,19 @@ Binary directory ## `setup-ide` command **IMPLEMENTATION specific for Scala Runner specification.** -Generate a BSP file that you can import into your IDE +Generates a BSP file that you can import into your IDE. + +The `setup-ide` sub-command allows to pre-configure a Scala CLI project to import to an IDE with BSP support. +It is also ran implicitly when `compile`, `run`, `shebang` or `test` sub-commands are called. + +The pre-configuration should be saved in a BSP json connection file under the path: + {project-root}/.bsp/scala-cli.json + +Specific setup-ide configurations can be specified with both command line options and using directives defined in sources. +Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources. +Using directives can be defined in all supported input source file types. + +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/setup-ide ### MUST have options @@ -5274,7 +5386,9 @@ Aliases: `--name` ## `uninstall` command **IMPLEMENTATION specific for Scala Runner specification.** -Uninstall scala-cli - only works when installed by the installation script +Uninstalls Scala CLI. +Works only when installed with the installation script. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install
@@ -5416,7 +5530,7 @@ Aliases: `-f` **--skip-cache** -Don't clear scala-cli cache +Don't clear Scala CLI cache **--binary-name** @@ -5437,6 +5551,8 @@ Aliases: `uninstall-completions` Uninstalls completions from your shell +For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/completions +
### Implementantation specific options @@ -5504,7 +5620,10 @@ Use progress bars ## `update` command **IMPLEMENTATION specific for Scala Runner specification.** -Update scala-cli - only works when installed by the installation script +Updates Scala CLI. +Works only when installed with the installation script. +If Scala CLI was installed with an external tool, refer to its update methods. +For detailed installation instructions refer to our website: https://scala-cli.virtuslab.org/install
@@ -5564,7 +5683,7 @@ Binary directory **--force** -Force update scala-cli if is outdated +Force update Scala CLI if it is outdated Aliases: `-f`