Make cs setup include scala-cli

[bjornregnell]

(*) Edit + TLDR This issue started out by discussing how scala-cli and coursier should align installation and also discussed the gettingstarted experience and the official download instructions. The consensus seem to be that coursier's cs setup should include installation of scala-cli as a first step, before scala-cli eventually becomes the new official scala runner. (scroll down to the end and see conclusions)

---

(Initial issue kick-off text:)

Is your feature request related to a problem? Please describe.
The current official Scala Getting-started-instructions are based on coursier, because cs can install stuff like sbt and what not. But scala-cli is more beginner-friendly and could replace cs as the official install method to make the getting-started experience even better.

Describe the solution you'd like
Enhance scala-cli with install abilities similar to cs so that scala-cli can install stuff like sbt, sbtn, scalac, scalafmt, and other useful stuff.

Additional context
scala-cli already wraps coursier under the hood so this should be a low-hanging-fruit if I have understood it correctly.

[bjornregnell]

This is one of the things pointed out by @julienrf as a step towards basing the official getting-started on scala cli.
#905

[ckipp01]

Enhance scala-cli with install abilities similar to cs so that scala-cli can install stuff like sbt, sbtn, scalac, scalafmt, and other useful stuff.

Just to add my two cents. I personally find this a bit odd that my build tool (scala-cli) would be installing other tools, like sbt or scalafmt. I personally wouldn't want this, but understand the desire to have something easier for people to get started on.

Ever since we created "Solidify Getting Started with Coursier" in here the goal was to ensure an easy start with coursier. Why is it not sufficient that cs setup just gives you scala-cli? By doing it the other way around we're also introducing all sorts of oddities and potential confusion where maybe you installed X with brew, maybe with cs, or maybe with scala-cli?

I sort of feel like we started to chase the idea of making coursier a solid way to get started, and are now considering just stopping and backing another horse to get started. I really love scala-cli, but I feel like coursier should install it, not the other way around where it installs my other tools. If there are issues with the current getting started experience with Coursier I'd be more in favor of making that as user friendly as possible because it already can install all the things I want and need to get started with Scala.

[romanowski]

I think there are 2 aspects here and I got a feeling that we mixing them up. So we have:

• scala-cli as a tool should allow to install things or be a frontend to coursier
• newcomers, after installing Scala should be able to easily install sbt, scalac etc.

I think scala-cli should not double what coursier offers but on the other hand, I think installing scala-cli (or scala in the future) run should also install couriser.

Coursier is amazing and the idea that it should be the entry point to Scala ecosystem is good however I think that a need to install another tool to install Scala will be confusing to newcomers - that is why we think this 'bundle install' is a way forward.

[ckipp01]

I think installing scala-cli (or scala in the future) run should also install couriser.

Sure, this makes sense.

[bjornregnell]

Thank you @ckipp01 for raising the need for clarification. Scala-cli and Coursier are both amazing tools and they benefit from each other, and my phrasing of the topic of this issue is perhaps a bit misleading as I meant to discuss how scala-cli can build on cs to do the things needed by a new-comer to Scala.

If a beginner should only install one thing to run their first Scala program then a runner is more important than an installer, so a one-click install would be great.

If scala-cli installs cs without any extra effort then professionals and beginners are both happy :)

This issue is a step towards making the official getting-started page suitable for both pure beginners and experienced professionals, which is not an easy job and requires careful thinking about various user types use cases...

[alexarchambault]

What do you all think about moving (or duplicating in a first time) the setup command of coursier in Scala CLI? That way, a typical beginner path should be something like

• install Scala CLI
• toy a bit with it on small projects
• if the user wants to works on bigger Scala projects, run scala-cli setup to properly install a JVM + sbt, scalafmt, … and cs.
• now cs is installed, it can update itself (although there are issues with that on Windows…, but there's a workaround: cs update coursier && coursier update cs) and update the other apps, but for Scala CLI.

The only minor issue I see with this is that scala-cli isn't managed by coursier, but by whichever way users installed it initially.

[bjornregnell]

What do you all think about moving (or duplicating in a first time) the setup command of coursier in Scala CLI?

I think that duplicating the cs setup capability in scala-cli seems like a great idea!

minor issue I see with this is that scala-cli isn't managed by coursier

So I would still have to do scala-cli update to update scala-cli but scala-cli will remind/notify me of new available versions of scala-cli (and cs?) and state in that message how to update?

Or could coursier detect that it didn't install scala-cli and explain that scala-cli should be updated manually using scala-cli update when updating the other stuff with coursier?

Perhaps the user's ability to "talk" to underlying coursier could be expanded, by also duplicating other useful commands like install and update? That might perhaps be a road towards a (partly) unified user experience?

[bjornregnell]

Anyway, any minor install quirks across scala-cli + cs is not so much a problem, and getting the setup capability would greatly simply my students lives as they move from scala-cli simple project, towards trying out a "real" build tool.

[julienrf]

@alexarchambault It is unclear to me how those two items below would work in this order:

• toy a bit with it on small projects

• if the user wants to works on bigger Scala projects, run scala-cli setup to properly install a JVM + sbt, scalafmt, … and cs.

How would scala-cli run work if there is no JVM? It would download and cache a JVM somewhere but that JVM would not be made available to other tools (such as sbt)? Then, the role of scala-cli setup would only be to make the JVM available (e.g., by setting JAVA_HOME), and to install the usual Scala command-line tools (sbt, scalafmt, etc.)?

• now cs is installed, it can update itself (although there are issues with that on Windows…, but there's a workaround: cs update coursier && coursier update cs) and update the other apps, but for Scala CLI.

I think if scala-cli can do setup it should also do install and update. Basically, scala-cli and cs would become a single tool, so, there would be no need to install cs when running scala-cli setup.

[adpi2]

The solution described by @alexarchambault seems a bit odd to me. It makes things easier for the Scala beginners, they only see scala-cli and they don't need to interact with anything else. But then if they want to discover more in the existing Scala ecosystem they need to install another thing, called cs, and use that thing to manage other tools like sbt and mill. So the path from beginner to intermediate level programmer is still quite tortuous.

It is also a bit confusing. Because it can be interpreted as: scala-cli is the getting started tool but then if I want to become expert I must setup my workspace, use cs and the tools made available by cs. I was writing some Scala but my environment was not yet "set up".

In order to make things equally good for beginners and experts, I think there are two ways forward, etiher 1 or 2.

1. The "one-click install" installs both cs and scala-cli

The "one-click install" installs cs and then uses cs to install scala-cli.
scala-cli is always managed by Coursier and can be updated by Coursier. There is no scala-cli setup.

It is clear for beginners and experts what the roles of cs and scala-cli are:

• cs is the Scala applications manager
• scala-cli is the main Scala runner

In all our documentations and tutorials (in docs.scala-lang.org, but also in the sbt and Mill websites or any other Scala related website) we can assume that cs is already installed and can safely be used to install sbt, mill...

2. Merge Coursier CLI into scala-cli

scala-cli is the main Scala runner and the Scala applications manager.
cs is deprecated.

In terms of usage that means we will add a dozen commands into scala-cli. It will looks like this:

$ scala-cli
Usage: /home/piquerez/.local/share/coursier/bin/.scala-cli.aux <COMMAND>
Scala CLI is a command-line tool to interact with the Scala language. It lets you compile, run, test, and package your Scala code.

Other commands:
  export                                    Export current project to sbt or Mill
  help                                      Print help message
  install completions, install-completions  Installs completions into your shell
  setup-ide                                 Generate a BSP file that you can import into your IDE
  shebang                                   Like `run`, but more handy from shebang scripts

Doctor commands:
  doctor  Print details about this application

Main commands:
  clean                  Clean the workspace
  compile                Compile Scala code
  fmt, format, scalafmt  Format Scala code
  console, repl          Fire-up a Scala REPL
  package                Compile and package Scala code
  publish
  run                    Compile and run Scala code.
  test                   Compile and test Scala code

Resolution commands:
  fetch    Transitively fetch the JARs of one or more dependencies or an application.
  resolve  Resolve and print the transitive dependencies of one or more dependencies or an application.

Application commands:
  install    Install an application from its descriptor.
  list       List all currently installed applications.
  setup      Setup a machine for Scala development.
  uninstall  Uninstall one or more applications.
  update     Update one or more applications.
  channel  Manage additional channels, used by coursier to resolve application descriptors.
  search   Search application names from known channels.
  bootstrap  Create a binary launcher from a dependency or an application descriptor.
  launch     Launch an application from a dependency or an application descriptor.

Miscellaneous commands:
  about    Print details about this application
  version  Print `scala-cli` version

See 'scala-cli <command> --help' to read about a specific subcommand. To see full help run 'scala-cli <command> --help-full'.
To run another Scala CLI version, specify it with '--cli-version' before any other argument, like 'scala-cli --cli-version <version> args'.

[bjornregnell]

I agree with @adpi2 that every extra concept increases the risk of confusion. Having only one thing that can do it all is much easier, than for a beginner having to understand what scala-cli does and does not and what cs does and does not.

So if merging scala-cli and cs is in scope of the roadmap and nearby releases then I'm very happy with that.

But if the solution by @alexarchambault is needed as a temprorary work-around for making it possible to get scala-cli to become the official installer sooner rather than later (preferrably under the name scala if that doesn't delay things too much...) then I can live with a step-wise merge of scala-cli and cs.

(I'm currently creating/updating teaching material for the fall semester, so I'm very interested in that the simple-beginner-use-case is determined as soon as possible so my material can go in print before summer. I guess there are more teachers than me that are prepping the fall semester currently...)

[kpodsiad]

I really like @adpi2's first proposal because:

• provides very clear distinction between what cs and scala-cli does and when they should be used
• complies with Unix philosophy - it's easier to understand two simpler tools with well defined responsibilities than one big swiss knife which can do anything except the thing that you want at the moment
• it doesn't add cognitive overhead when someone is trying to use that tool. Difficulty of searching sth in documentation scales with documentation's size and tool's features. I sometimes feel overwhelmed when searching documentation of some tool and I can easily imagine that someone with lesser experience could be overwhelmed as well, even more probably. Sticking with modular approach helps when user has to build a mental model of some set of tools.

I think there are 2 aspects here and I got a feeling that we mixing them up. So we have:

• scala-cli as a tool should allow to install things or be a frontend to coursier
• newcomers, after installing Scala should be able to easily install sbt, scalac etc.

I think scala-cli should not double what coursier offers but on the other hand, I think installing scala-cli (or scala in the future) run should also install couriser.

Coursier is amazing and the idea that it should be the entry point to Scala ecosystem is good however I think that a need to install another tool to install Scala will be confusing to newcomers - that is why we think this 'bundle install' is a way forward.

@romanowski Wouldn't this be solved if cs setup was installing scala-cli as well? Currently it's installing tools such as ammonite or scalafmt. Adding scala-cli to this list seems like a solution to the one install command problem. With this approach starting with Scala will be as simple as typing cs setup is.

[bjornregnell]

Well, I'm fine with keeping cs for other stuff, but I don't want beginners having to install more than one thing. So first cs and then scala-cli is not so good IMHO.

I agree that help can be daunting if too long, but it also depends how the help is structured and I think that if you e.g. never use a certain capability that help-text does not have to be shown upfront, but as subhelp when you need it.

So if we keep cs and scala-cli as separate tools, then I think scala-cli should be the official getting-started experience, preferrably named scala, and then cs for those that want the extra stuff if that does not get integrated with the scala-cli experience.

[bjornregnell]

If the official start is cs setup and then via that install scala-cli, you still need to understand several things as a beginner. Also, the cs page is more directed towards Scala professionals IMHO https://get-coursier.io/
(what is even artifact fetching, CLI, global lock, etc, where is the single click install botton, etc ???, if you see what I mean ...)

[bjornregnell]

Ideally there should be a default one-click install for each platform and then you are good to go with scala (and other options discoverable beneath, sdk, brew and what not, similar to how the scala-cli page is organized).

[adpi2]

Well, I'm fine with keeping cs for other stuff, but I don't want beginners having to install more than one thing. So first cs and then scala-cli is not so good IMHO.

As a comparison, there is only one installer for Node but it installs two things node and npm. Beginners first learn to use node, which is the runner and the REPL, and then they learn to use npm to install and manage dependencies.

We can do something similar. There is only one installer for Scala and it installs two things cs and scala-cli (or scala). Beginners would first learn to use scala-cli and they would learn to use cs only when they need it. If they don't need it then fine they won't even know that it exists. But at least there would not be 2 distinct environments for beginners and experts.

So ultimately one could write a Scala programming course without mentioning cs. But cs needs to be available because it manages scala-cli and it opens the door to the entire tooling ecosystem.

That being said, I don't have a strong preference between 1. Install both tools in a single step and 2. Merge cs into scala-cli. But I think that the intermediate scala-cli setup is adding unnecessary complexity for everyone. It makes it harder for beginners to discover more tools of the ecoystem, it makes it harder to manage scala-cli, it makes it harder for tooling authors to write the installation instruction of their tool.

When I am writing the documentation of some tool, I want to assume that cs is available by default because I want the installation instruction to be as simple as:

$ cs install my-tool

Instead of:

If you don't have cs installed you must run
$ scala-cli setup

And then you can use cs to install my-tool
$ cs install my-tool

[bjornregnell]

@adpi2 Aha, yes, similar to Node, if the one-click install installs both cs and scala[-cli] then a beginner needs not to bother about other things than the runner in the beginning, and then eventually cs can be used to install more stuff like sbt. Sounds like a good option.

[alexarchambault]

Thanks for your feedback everyone. So it seems there's a consensus on installing both cs and scala-cli together as much as possible (it's something we had also discussed internally at VirtusLab). @lwronski (and a bit myself) started to think about some practical matters about this. Packaging cs and scala-cli together is fine, but updates can be a problem, as both tools are not released together.

To work around that, a way would be to package cs and scala-cli together in graphical installers (so MSI on Windows, and pkg on macOS), and keep them separate in CLI installation instructions, but suggest users to install both.

Scala CLI can grab the latest cs launcher or the one that Scala CLI is currently using (in its CI say), and put it in Windows MSI and macOS pkg.

For CLI methods, we can make sure that scala-cli and cs both have packages for the same platforms (rpm, deb, sdkman, etc.), and suggest users to install both. For that to work, we need to ensure that the coursier CI builds the same kind of packages as Scala CLI, which could be achieved via scala-packager and maybe some shared Mill plugins too. Then instructions could be updated - the manual ones could look like

$ curl -fL https://github.com/Virtuslab/scala-cli/releases/latest/download/scala-cli-x86_64-pc-linux.gz | gzip -d > scala-cli
$ curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs
$ chmod +x scala-cli cs
$ sudo mv scala-cli cs /usr/local/bin/

This might also require pushing coursier packages to the same RPM or deb repository as Scala CLI.

[bjornregnell]

Having both scala-cli and cs in one MSI for Windows sounds fantastic! Then it will "just work" for the majority. :)

Also pkg om macos is nice! But also sdkman and brew are popular for macos people. And sdkman is increasingly popular för linux people, but deb is of course very popular by many. So it would be nice if all stuff points to both scala-cli and cs together.

See also #981

[lrytz]

To me this sounds more complicated than it should be. The coursier website says:

Coursier is the Scala application and artifact manager. It can install Scala applications and setup your Scala development environment.
These instructions will install the coursier CLI cs itself, as well as a typical Scala development environment. By default, they will install the following applications: scala, sbt, ...

scala-cli is a scala tool / application that should be installed by cs setup (as noted before on this thread). Especially if it will become the default scala at some point. Then there doesn't need to be any packages or separate installation instructions for scala-cli.

What are the issues with this approach?

[bjornregnell]

What are the issues with this approach?

If so, there are still two concepts to understand and deal with by a beginner programmer (coursier and scala-cli).

I'd like a single click download for each platform, preferably defaulting to a platform-specific installer such as msi for windows, etc. (But with other options visible aside.)

And with the approach you suggest, if I understand correctly, there are still two steps if you must first install Coursier and then do cs setup, which is one step too many compared to how it could be.

[sjrd]

And with the approach you suggest, if I understand correctly, there are still two steps if you must first install Coursier and then do cs setup, which is one step too many compared to how it could be.

cs setup is the installation of coursier just as much as the other things it installs. That is the single step. There's no installing coursier before running cs setup.

[lrytz]

+1. If the installation of coursier is considered too complicated that's a separate issue.

[bjornregnell]

There's no installing coursier before running cs setup.

Well, the cs setup command is not available on my student's own windows machine out of the box... :) But I see what you mean as the current getting-stared page is now greatly improved (very nice!! much better now than when this thread started!). There is now a terminal one-liner for non-Windows with a platform tab (very nice) that includes the setup command and you don't have to go to the coursier cli overview page (which, however, is still daunting for those beginners that happen to click that link).

If the installation of coursier is considered too complicated that's a separate issue.

I agree that it is a separate issue. But it is not the only issue:

Assume that you want to install Scala and that you are a beginner programmer. Currently:

1. You go to the Scala home page looking for "Download".
2. You click on "Getting started" there is instead Coursier (a non-obvious name, somewhat difficult to spell).
3. You install Coursier including the cs setup. If you are on windows it is a zip and not an msi.
   [3a.] If you are on Windows: Unpack the zip and execute the exe.
4. Now you can run scala

Compare that to how it could be:

1. You go to the scala home page looking for Download.
2. You click on Download by your platform tab (eg. msi for Windows) and things get installed.
3. Now you can run scala

Even if there is a thing called Coursier, which can do installation and stuff, that does not have to be an upfront exposed concept and an action step for a beginner (who does not initially care about coursier, sbt and what not). I think the Download and install of scala should be one thing and called scala, inline with the beginner naturally is looking for (together with an officially recommend editor with Scala support). This is how it used to be with Scala 2, where there was a Scala msi for Windows.

Anyway, I think the current getting-started-page is much better now ❤️ than when Scala 3 was released. The main thing left as I see it is to consolidate the several different concepts currently available into a single scala install experience, so that the beginner does not have to bother about what those extra -cli things are.

[sjrd]

3. If you are on windows it is a zip and not an msi.
[3a.] If you are on Windows: Unpack the zip and execute the exe.

It used to be directly the exe, rather than a zip with an exe within. I don't know why that changed. It should be reverted.

An exe installer is perfectly fine on Windows. It doesn't have to be an msi. In either case you double-click on it. Many software are distributed as exe installers.

[bjornregnell]

• (1) OK great if the windows thing could be un-wrapped. (msi feels a bit more "official", but exe is perfectly ok by me as well)

I started this issue after discussions with @julienrf on what was neeed to:

• (2) make the Scala 3 getting-started-experience include scala-cli and
• (3) how scala-cli could become scala.

@julienrf suggested a stepwise approach including resolving what installs what :).

If cs can be made to include scala-cli then the second item is "solved". Then the third remains.

[bjornregnell]

I just tested the new https://www.scala-lang.org/download/ on a clean Windows 10 machine and it worked like a charm! ❤️ @bishabosha

I got there by clicking on "Install" on top of the scala-lang home page. I could double click on the zip for Windows and after download and then I could actually double click on the exe without even unpacking the zip.

Now I got scala and scalac on path in windows terminal in powershell and it just works :)

I found these issues:

• I think beginners might be confused by the question if to "add coursier/bin to path Yes/No". What is even a path? Perhaps a clear statement that this is recommended! (As a comparison: In the old Scala 2 msi installer the path adding was included in a pre-ticked tick box in the window presented)

• I cannot uninstall what was installed in one go via Apps & Features in Windows Settings. (If I search for Scala or Coursier under add/remove programs nothing shows up). This is a regression from the scala.msi that enabled removal of Scala via windows. Also the sbt.msi and the scala-cli.msi provides in-windows-removal with a standard windows uninstaller. So that is perhaps an argument for providing a "proper" msi instead of an exe @sjrd

• I did not get scala-cli...

[bjornregnell]

Found another issue with the official install page: @bishabosha @julienrf

• The page heading and the body says that you should use cs setup but for windows you don't see that command, so this is confusing. When should i do cs setup? Answer: you don't need to when on windows.

I propose to change the heading to Install Scala with Coursier (Recommended)" and the body text to :

• To install Scala, it is recommended to use the official installer called Coursier. It installs everything necessary to use the latest Scala release:

I removed "from a command line" as this is not so for Windows with the zip/exe/msi.

(Or do you want me to report these issues of the install page elsewhere?)

[bjornregnell]

Perhaps we should change the topic of this issue to "Make cs setup include scala-cli"? @alexarchambault

Including scala-cli in cs setup can be done prior to the potential/eventual promotion of scala-cli to scala. With both the traditional scala runner and scala-cli on path more people can start to play with scala-cli as soon as the have installed the currently official scala via the Coursier installers, without having to go to the scala-cli install page.

[bjornregnell]

Link to issue now also in the coursier repo:
coursier/coursier#2416

[julienrf]

I think this was fixed by coursier/coursier#2415?

[bjornregnell]

Yes! 🎉

[alexarchambault]

scala-cli is a scala tool / application that should be installed by cs setup (as noted before on this thread). Especially if it will become the default scala at some point. Then there doesn't need to be any packages or separate installation instructions for scala-cli.

What are the issues with this approach?

cs setup is the installation of coursier just as much as the other things it installs. That is the single step. There's no installing coursier before running cs setup.

I agree that users should be given the possibility to install Scala CLI via cs (they now can), and that cs setup should also install scala-cli (it now does).

Yet, should it be the only way of installing it? (This also applies to cs itself: should manual download be the only way to install it?)

It's still quite handy for some users to be able to install scala-cli (for people who just want to give Scala a try) and cs (which is kind of the entrypoint here) via their preferred package manager. Many users are more comfortable installing things via package managers they're used to, rather than manually downloading and running binaries from the internet. I think Scala CLI and cs should have official packages for those users.

For that to work well, we need to be sure that:

• cs setup doesn't install cs itself if it's installed via a package manager, nor scala-cli if it detects it's installed this way too
• scala-cli update should detect that it's installed via a package manager, and suggest users to update it using their package manager
• cs has the same kind of packages as Scala CLI has today

We have some ideas for how to add support for the first two points. For the third one, it should be a matter of moving the packaging logic of Scala CLI to a Mill plugin or Scala scripts living in a separate repository.

[alexarchambault]

We can organize a meeting to discuss that, if that can help settle this.

[bjornregnell]

I'm happy to join a meeting. bjorn.regnell@cs.lth.se

[bishabosha]

I've just merged scala/docs.scala-lang#2403 to list scala-cli as being installed by cs setup in the getting started guide. (no demo yet though)

[julienrf]

Many users are more comfortable installing things via package managers they're used to, rather than manually downloading and running binaries from the internet.

I agree, and I think cs should be installable via package managers, and the “default” apps should be installed along the process. If we have that (and I believe we should), then scala-cli will be installed by package managers as a side-effect of installing “the Scala distribution” (ie, cs + the default apps) via package managers.

[alexarchambault]

I agree, and I think cs should be installable via package managers, and the “default” apps should be installed along the process. If we have that (and I believe we should), then scala-cli will be installed by package managers as a side-effect of installing “the Scala distribution” (ie, cs + the default apps) via package managers.

I agree it would be nice if we were able to automatically run cs setup right after it's installed. Yet, it's not always possible: most package managers run as root, while cs setup installs things for the current user only.

I'm not sure how to reconcile these two points. Maybe we could ensure that cs install is fine installing things in "shared" directories, such as /usr/local/bin. Then users would be required to run cs install and all as root.

But the coursier cache would still be per user at first, so every user on the current machine would download and cache everything for themselves. This might be addressed by… maybe allowing users to pick things from a global cache managed by root. It's a bit uncertain, and I'm not sure what kind of issue could arise from that approach…

[bjornregnell]

Related to #686

[lrytz]

• cs setup doesn't install cs itself if it's installed via a package manager, nor scala-cli if it detects it's installed this way too

• scala-cli update should detect that it's installed via a package manager, and suggest users to update it using their package manager

It might be nice generally to make scala-cli available through native package managers. But having multiple ways to get the same thing comes with a cost (maintenance, troubleshooting). I think it's better to focus on "only way of installing it" for scala-cli, at least initially.

I really don't think apt install coursier; cs setup is too much to ask from someone that wants to learn programming.

[bjornregnell]

Related to: scala/improvement-proposals#46

[bjornregnell]

I guess this can be closed now as cs setup now includes Scala CLI:

$ cs version
2.1.0-M6-53-gb4f448130
$ cs list
amm
coursier
cs
sbt
sbtn
scala
scala-cli
scalac
scalafmt