Support or silently warn about legacy-scala-runner-specific options without failing

[Gedochao]

Describe what needs to be done and why
We need to be backwards compatible with all the options available from the old Scala runner.
This doesn't necessarily mean we have to implement any missing functionality (unless it makes sense), but we shouldn't fail builds when they're passed and a meaningful warning explaining what works and why should be given (similarly to how it's done in #1679).
The ones we still have left to handle:

• Scala 2 options:
  • -howtorun
  • -i
  • -I
  • -Dname=prop
  • -J<arg>
  • -nobootcp
• Scala 3 options:
  • -run
  • -with-compiler

We should also add a thorough doc on our docs website explaining which legacy options are supported and how.

Additional context

• Relevant issues:
  • Option -save is not supported #1670
  • scala-cli is missing expression evaluation #1150
  • Consider making Scala CLI backwards compatible with current scala commands #1310
  • java-style -Dproperty=value system properties #1526
• Relevant PRs:
  • Add warnings for -save & -nosave legacy scala runner options instead of failing #1679
  • Fix backwards compat for -e and --scalac-help #1313
  • Make -d and -classpath options backwards compatible with the scala command #1340
  • Add support for running snippets #1166
• Old Scala 2 runner:
  • options reference
  • options implementation
• Old Scala 3 runner:
  • options implementation

[Gedochao]

Regarding Scala 2's exclusive -howtorun (or --how-to-run) option, I wonder if (and if at all, to what degree) should we support it.

As the legacy option is barely documented, let me first explain how it seems to be meant to work.
What it is basically an override switch.
There's 5 available modes (6, if counting the invalid arg): script, object, jar, repl and guess.

• guess is the assumed default and it means the user trusts the runner knows how to run the inputs which have been passed.
• repl means the runner should go straight into the repl, loading the input on classpath.
  • this is an equivalent of Scala CLI's repl sub-command, and thus should be easy to support
• object, script and jar means the runner should not guess and assume the passed inputs are to be run as a Scala object, script or a jar, respectively
  • this allows to ignore the extension of the input, even if it would normally not be assumed a runnable file
  • the legacy scala runner of course fails if anything goes wrong (i.e. a Scala source is passed with --howtorun jar), printing the runner stacktrace
  • this would be quite tedious (although not strictly impossible) to support in Scala CLI, as it'd require us to implement an override for how Inputs are interpreted; not to mention the extra (IMO unnecessary) complexity

TL;DR -howtorun guess is the way Scala CLI works right now, and -howtorun repl is quite easy to deliver. However, the rest of the functionality would require some effort and introduce unnecessary complexity.
I have mixed feelings about supporting the option partially, too.
Should we warn about it being deprecated and ignore it, similarly to how we do with -save and -nosave?
Or should we support it? And then, partially or completely?

cc @julienrf

[julienrf]

A deprecation warning should be the minimal thing to do. There you could explain that -howtorun repl has been replaced by the repl sub-command, for instance, and what is the new way to achieve what was previously achieved via the other options for -howtorun. We probably need to first settle on #466 / #1668?

[Gedochao]

We probably need to first settle on #466 / #1668?

I think those can be done independently.
In case #466 / #1668 change the behaviour, it will be simple enough to adjust the deprecation warning.