From c596951895658b3bf7a102ac51256b2b223fcbb4 Mon Sep 17 00:00:00 2001 From: Yadu Krishnan Date: Thu, 8 Feb 2024 07:33:22 +0100 Subject: [PATCH] Documentation for creation of custom toolkit (#2715) * Documentation for creation of custom toolkit * Update website/docs/guides/advanced/custom-toolkit.md Co-authored-by: Piotr Chabelski * Update website/docs/guides/advanced/custom-toolkit.md Co-authored-by: Piotr Chabelski * Update website/docs/guides/advanced/custom-toolkit.md Co-authored-by: Piotr Chabelski --------- Co-authored-by: Piotr Chabelski --- .../docs/guides/advanced/custom-toolkit.md | 60 +++++++++++++++++++ website/docs/guides/intro.md | 1 + 2 files changed, 61 insertions(+) create mode 100644 website/docs/guides/advanced/custom-toolkit.md diff --git a/website/docs/guides/advanced/custom-toolkit.md b/website/docs/guides/advanced/custom-toolkit.md new file mode 100644 index 0000000000..7b24b6402b --- /dev/null +++ b/website/docs/guides/advanced/custom-toolkit.md @@ -0,0 +1,60 @@ +title: Custom Toolkit +sidebar_position: 44 +--- +Similar to the Scala Toolkit and Typelevel toolkit, it is possible to create your own, custom toolkit. +Having a custom toolkit with common libraries can speed up the development using scala-cli. + +Let's look at how we can create a new toolkit. + +For example, to create a LiHaoyi ecosystem toolkit, we can name the file as `LiHaoyiToolkit.scala` and add the required libraries as dependency directives: + +```scala +//> using scala 2.13, 3 +//> using publish.name toolkit +//> using dep com.lihaoyi::upickle::3.1.3 +//> using dep com.lihaoyi::os-lib::0.9.2 +//> using dep com.lihaoyi::requests::0.8.0 +//> using dep com.lihaoyi::fansi::0.4.0 +``` +This toolkit is a combination of 4 libraries from `com.lihaoyi` organization as defined before. The key `publish.name` must have the value `toolkit` to be used as a toolkit. + +Similarly, define the scalajs version of toolkit in `LiHaoyiToolkit.js.scala` file. Notice the `js.scala` extension. It should also have `publish.name` as `toolkit`. + +If testkit is supported, it can also be added as another file, `LiHaoyiToolkitTest.scala` with `publish.name` as `toolkit-test`: +``` +//> using scala 2.13, 3 +//> using publish.name toolkit-test +//> using dep com.lihaoyi::utest::0.8.2 +``` + +Additionally, more configurations needed for publishing the toolkit can be kept in a conf file, for example, `publish-conf.scala`: +``` +//> using publish.organization com.yadavan88 +//> using publish.version 0.1.0 +//> using publish.url https://github.com/yadavan88/lihaoyi-toolkit +//> using publish.license Apache-2.0 +//> using publish.repository central +//> using publish.developer "yadavan88|Yadu Krishnan|https://github.com/yadavan88" +//> using repository sonatype:public +``` + +The toolkit can be published locally using the command: +``` +scala-cli --power publish local --cross LiHaoyiToolkit.scala publish-conf.scala +``` + +Similarly, it is also possible to publish to a central repository. Refer to the [GitHub Action workflow](https://github.com/scala/toolkit/blob/main/.github/workflows/deploy.yaml) for more details. + +Once it is published, it can be accessed using the org-name with which it got published. For example, with the published toolkit under the organization `com.yadavan88`, it can be accessed as: + +``` +//> using toolkit com.yadavan88:0.1.0 + +@main +def main() = { + println(fansi.Color.Blue("Hello world!")) + println("path is : " + os.pwd) +} + +``` +This brings in all the dependencies mentioned in the custom toolkit file. diff --git a/website/docs/guides/intro.md b/website/docs/guides/intro.md index 95fbe91a84..43f82a845e 100644 --- a/website/docs/guides/intro.md +++ b/website/docs/guides/intro.md @@ -43,6 +43,7 @@ Less introductory guides on specific topics. - [Verbosity](advanced/verbosity.md) - learn how to control logs verbosity in Scala CLI. - [Java properties](advanced/java-properties.md) - learn how to pass Java properties to Scala CLI. - [Internals](advanced/internals.md) - learn about how Scala CLI works under the hood. +- [Custom Toolkit](advanced/custom-toolkit.md) - learn how to create custom toolkits ## ⚡️ `--power` mode guides