From 9af8a01407e990486abf2afab78f1f843c176a5d Mon Sep 17 00:00:00 2001 From: Maciej Gajek Date: Wed, 22 Feb 2023 09:54:46 +0100 Subject: [PATCH] Add export command documentation --- .../cli/commands/export0/ExportOptions.scala | 3 +- website/docs/commands/export.md | 156 ++++++++++++++++++ website/docs/reference/commands.md | 2 +- 3 files changed, 159 insertions(+), 2 deletions(-) create mode 100644 website/docs/commands/export.md 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 index a18cc19f0e..150b1389c0 100644 --- a/modules/cli/src/main/scala/scala/cli/commands/export0/ExportOptions.scala +++ b/modules/cli/src/main/scala/scala/cli/commands/export0/ExportOptions.scala @@ -54,7 +54,8 @@ object ExportOptions { implicit lazy val parser: Parser[ExportOptions] = Parser.derive implicit lazy val help: Help[ExportOptions] = Help.derive - private val helpHeader = "Export current project to an external build tool (like SBT or Mill)." + private val helpHeader = + "Export current project to an external build tool (like SBT or Mill) or to JSON." val helpMessage: String = s"""$helpHeader | diff --git a/website/docs/commands/export.md b/website/docs/commands/export.md new file mode 100644 index 0000000000..b186bce864 --- /dev/null +++ b/website/docs/commands/export.md @@ -0,0 +1,156 @@ +--- +title: Export ⚡️ +sidebar_position: 27 +--- + +In case your project outgrows the cabapilities of Scala CLI (e.g support for modules) it may be beneficial +to switch to a build tool such as SBT or Mill. +The `export` sub-command allows to do that by converting a Scala CLI project into an SBT or Mill configuration. +Additionally the sub-command supports the JSON format for custom analysis of projects. + +:::caution +The `export` sub-command is restricted and requires setting the `--power` option to be used. +You can pass it explicitly or set it globally by running: +scala-cli config power true +::: + +The project configuration is read both from information specified in source files +as well as options passed to the `export` sub-command. + +Let's take a simple one-file project as an example: +```scala title=Hello.scala +//> using scala "3.1.3" +//> using option "-Xasync" +//> using dep "com.lihaoyi::os-lib:0.9.0" + +object Hello { + def main(args: Array[String]): Unit = + println(os.pwd) +} +``` + +# Exporting to SBT: + +```bash +scala-cli --power export Hello.scala --sbt +``` +Note that `--sbt` is not required here since it's the default. + +The result is a sbt-compliant project created in the `dest/` directory: + +``` +dest +├── project +│ └── build.properties +├── src +│ └── main +│ └── scala +│ └── Hello.scala +└── build.sbt +``` + +All the project's configuration resides now in `dest/build.sbt`: + + +```scala title=dest/build.sbt +scalaVersion := "3.1.3" + +scalacOptions ++= Seq("-Xasync") + +libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.9.0" + +libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.9.0" % Test + +``` + + +To configure the version of SBT used in the new project provide the `--sbtVersion` option to the `export` sub-command. + +# Exporting to Mill: + +```bash +scala-cli --power export Hello.scala --mill +``` +Mill is not the default `export` format, so passing the `--mill` option is required. + +The results are again created in the `dest/` directory: + +``` +dest +├── project +│ └── src +│ └── Hello.scala +├── .mill-version +├── build.sc +├── mill +└── mill.bat +``` + +And all the project's configuration resides now in `dest/build.sc`: + +```scala title=dest/build.sc +import mill._ +import mill.scalalib._ +object project extends ScalaModule { + def scalaVersion = "3.1.3" + def scalacOptions = super.scalacOptions() ++ Seq("-Xasync") + def ivyDeps = super.ivyDeps() ++ Seq( + ivy"com.lihaoyi::os-lib:0.9.0" + ) + + object test extends Tests { + def ivyDeps = super.ivyDeps() ++ Seq( + ivy"com.lihaoyi::os-lib:0.9.0" + ) + } +} + +``` + +The script files `mill` and `mill.bat` are mill wrappers fetched from [lefou/millw repository](https://github.com/lefou/millw/tree/166bcdf5741de8569e0630e18c3b2ef7e252cd96). +To change the build tool version used override the contents of `dest/.mill-version`. + + +# Exporting to JSON: + +To export project information in a human-comprehensible format, use the `--json` flag. + +```bash +scala-cli --power export Hello.scala --json +``` + +The result is the `dest/export.json` file: + +```json title=dest/export.json +{ + "scalaVersion": "3.1.3", + "platform": "JVM", + "scopes": { + "main": { + "sources": [ + "Foo.scala" + ], + "scalacOptions": [ + "-Xasync" + ], + "dependencies": [ + { + "groupId": "com.lihaoyi", + "artifactId": { + "name": "os-lib", + "fullName": "os-lib_3" + }, + "version": "0.9.0" + } + ], + "resolvers": [ + "https://repo1.maven.org/maven2", + "ivy:file:///Users/mgajek/Library/Caches/ScalaCli/local-repo/v0.1.20-111-648755-DIRTY2ba64fdc//[organisation]/[module]/(scala_[scalaVersion]/)(sbt_[sbtVersion]/)[revision]/[type]s/[artifact](-[classifier]).[ext]", + "ivy:file:/Users/mgajek/.ivy2/local/[organisation]/[module]/(scala_[scalaVersion]/)(sbt_[sbtVersion]/)[revision]/[type]s/[artifact](-[classifier]).[ext]" + ] + } + } +} +``` + +Note that the path to the output directory (`dest` by default) can be overriden with the `--output` option. diff --git a/website/docs/reference/commands.md b/website/docs/reference/commands.md index 423110f44c..5021caedd3 100644 --- a/website/docs/reference/commands.md +++ b/website/docs/reference/commands.md @@ -54,7 +54,7 @@ Accepts option groups: [compilation server](./cli-options.md#compilation-server- ## export -Export current project to an external build tool (like SBT or Mill). +Export current project to an external build tool (like SBT or Mill) or to JSON. Detailed documentation can be found on our website: https://scala-cli.virtuslab.org