Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shorter options help #1872

Merged
merged 35 commits into from Feb 21, 2023
Merged

Shorter options help #1872

merged 35 commits into from Feb 21, 2023

Conversation

Gedochao
Copy link
Contributor

Fixes #1669

  • bump scala-cli-signing and case-app
  • only show tags.important or tags.must help options in the short help (sub-command --help)
  • example output:
$ scala-cli fmt -h
Usage: scala-cli fmt [options]
Formats Scala code.

You are currently viewing the basic help for the fmt sub-command. You can view the full help by running: 
   scala-cli fmt --help-full
For detailed documentation refer to our website: https://scala-cli.virtuslab.org/docs/commands/fmt

Format options:
  --check                                     Check if sources are well formatted
  --save-scalafmt-conf                        Saves .scalafmt.conf file if it was created or overwritten
  -F, --scalafmt-arg string*                  Pass an argument to scalafmt.
  --scalafmt-conf, --scalafmt-config string?  Custom path to the scalafmt configuration file.
  --dialect, --scalafmt-dialect string?       Pass a global dialect for scalafmt. This overrides whatever value is configured in the .scalafmt.conf file or inferred based on Scala version used.
  --fmt-version, --scalafmt-version string?   Pass scalafmt version before running it (3.6.1 by default). If passed, this overrides whatever value is configured in the .scalafmt.conf file.

Help options:
  --help-js                                      Show options for ScalaJS
  --help-native                                  Show options for ScalaNative
  --help-doc, --doc-help, --help-scaladoc, --scaladoc-help  Show options for Scaladoc
  --help-repl, --repl-help                       Show options for Scala REPL
  --help-fmt, --fmt-help, --help-scalafmt, --scalafmt-help  Show options for Scalafmt

@Gedochao Gedochao marked this pull request as ready for review February 20, 2023 15:07
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks
…blish`, `publish local` and `publish setup` sub-commands
- temporarily remove console-specific characters from help messages to fix the reference doc website
- remove redundant tags for options already tagged as `SpecificationLevel.MUST`
- rename `tags.important` to `tags.inShortHelp`
@Gedochao
Copy link
Contributor Author

Btw. as a side effect of these changes, I had to adjust the behaviour of --help-js and --help-native as well.
Previously, they simply ran the default --help with Scala.js or Scala Native options' sections included (alongside others).
Now, I instead run --help-full for just those help options groups.

old output:

▶ scala-cli --help-native
Usage: default [options]

Scala options:
  --js                                           Enable Scala.js. To show more options for Scala.js pass `--help-js`
  --native                                       Enable Scala Native. To show more options for Scala Native pass `--help-native`
  -P, --plugin, --compiler-plugin string*        Add compiler plugin dependencies
  -O, --scala-opt, --scala-option, --scalac-option option  Add a `scalac` option. Note that options starting with `-g`, `-language`, `-opt`, `-P`, `-target`, `-V`, `-W`, `-X`, and `-Y` are assumed to be Scala compiler options and don't require to be passed after `-O` or `--scalac-option`.
  -S, --scala, --scala-version version           Set the Scala version (3.2.2 by default)
  --scalac-help, --help-scalac                   Show help for scalac. This is an alias for --scalac-option -help
  --scalac-verbose, --verbose-scalac             Turn verbosity on for scalac. This is an alias for --scalac-option -verbose
  --script-snippet string*                       Allows to execute a passed string as a Scala script
  --scala-snippet string*                        Allows to execute a passed string as Scala code
  -with-compiler, --with-compiler, --with-scala-compiler  Allows to include the Scala compiler artifacts on the classpath.

Java options:
  --java-home path                               Set the Java home directory
  -j, --jvm jvm-name                             Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
  --java-snippet string*                         Allows to execute a passed string as Java code
  --execute-java string*                         A synonym to --scala-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
  -cp, --jar, --jars, --class, --classes, -classpath, --classpath, --extra-jar, --extra-jars, --class-path, --extra-class, --extra-classes, --extra-class-path paths  Add extra JARs and compiled classes to the class path
  --compile-only-jar, --compile-only-jars, --extra-compile-only-jar, --extra-compile-only-jars paths  Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
  --source-jar, --source-jars, --extra-source-jar, --extra-source-jars paths  Add extra source JARs
  --resource-dir, --resource-dirs paths          Add a resource directory
  -J, --java-opt java-options                    Set Java options, such as `-Xmx1g`
  --java-prop, --java-prop-option key=value|key  Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.
  -J, --java-opt java-options                    Set Java options, such as `-Xmx1g`
  --java-prop, --java-prop-option key=value|key  Add java properties. Note that options equal `-Dproperty=value` are assumed to be java properties and don't require to be passed after `--java-prop`.

Repl options:
  -A, --amm, --ammonite                       Use Ammonite (instead of the default Scala REPL)
  --ammonite-ver, --ammonite-version string?  Set the Ammonite version (2.5.6-1-f8bff243 by default)

Logging options:
  -v, -verbose, --verbose  Increase verbosity (can be specified multiple times)
  -i, --interactive        Interactive mode
  --actions                Enable actionable diagnostics
  -q, --quiet              Decrease verbosity
  --progress               Use progress bars

Entrypoint options:
  -M, --main-class main-class                    Specify which main class to run
  --main-class-ls, --list-main-class, --main-class-list, --list-main-classes  List main classes available in the current context

Debug options:
  --debug                         Turn debugging on
  --debug-port string?            Debug port (5005 by default)
  --debug-mode attach|a|listen|l  Debug mode (attach by default)

Compilation server options:
  --server  Enable / disable usage of Bloop compilation server. Bloop is used by default so use `--server=false` to disable it. Disabling compilation server allows to test compilation in more controlled mannter (no caching or incremental compiler) but has a detrimental effect of performance.

Run options:
  --standalone-spark, --spark-standalone  Run as a Spark job, using a vanilla Spark distribution downloaded by Scala CLI
  --hadoop, --hadoop-jar                  Run as a Hadoop job, using the "hadoop jar" command
  --command                               Print the command that would have been run (one argument per line), rather than running it
  --scratch-dir string?                   Temporary / working directory where to write generated launchers

Benchmarking options:
  --jmh                  Run JMH benchmarks
  --jmh-version version  Set JMH version

Markdown options:
  --md-snippet, --markdown-snippet string*  [experimental] Allows to execute a passed string as Markdown code
  --md, --markdown, --enable-markdown       Enable markdown support.

Scala Native options:
  --native-version string?  Set the Scala Native version (0.4.9 by default).
  --native-mode string?     Set Scala Native compilation mode
  --native-gc string?       Set the Scala Native garbage collector
  --native-clang string?    Path to the Clang command
  --native-clangpp string?  Path to the Clang++ command
  --native-linking string*  Extra options passed to `clang` verbatim during linking
  --native-compile string*  List of compile options
  --embed-resources         Embed resources into the Scala Native binary (can be read with the Java resources API)

Dependency options:
  --dep, --dependency string*       Add dependencies
  -r, --repo, --repository string*  Add repositories

Other options:
  --suppress-directives-in-multiple-files-warning, --suppress-warning-directives-in-multiple-files  Suppress warnings about using directives in multiple files
  --home, --home-directory string?               Override the path to user's home directory
  --python-setup                                 Set Java options so that Python can be loaded
  --py, --python                                 Enable Python support via ScalaPy
  --scalapy-version, --scala-py-version string?  [experimental] Set ScalaPy version (0.5.3 by default)
  --platform scala-js|scala-native|jvm           Specify platform
  --help-js                                      Show options for ScalaJS
  --help-native                                  Show options for ScalaNative
  --help-doc, --doc-help, --help-scaladoc, --scaladoc-help  Show options for Scaladoc
  --help-repl, --repl-help                       Show options for Scala REPL
  --help-fmt, --fmt-help, --help-scalafmt, --scalafmt-help  Show options for Scalafmt
  -d, --compile-out, --destination, --compile-output, --output-directory, --compilation-output /example/path  Copy compilation results to output directory using either relative or absolute path
  --toolkit, --with-toolkit version|latest       Add toolkit to classPath
  -w, --watch                                    Watch source files for changes
  --restart, --revolver                          Run your application in background and automatically restart if sources have been changed
  --cross                                        Run given command against all provided Scala versions and/or platforms
  -w, --watch                                    Watch source files for changes
  --restart, --revolver                          Run your application in background and automatically restart if sources have been changed
  --cross                                        Run given command against all provided Scala versions and/or platforms
  -version, --version

new output:

Usage: default [options]

Scala Native options:
  --native-version string?   Set the Scala Native version (0.4.9 by default).
  --native-mode string?      Set Scala Native compilation mode
  --native-gc string?        Set the Scala Native garbage collector
  --native-clang string?     Path to the Clang command
  --native-clangpp string?   Path to the Clang++ command
  --native-linking string*   Extra options passed to `clang` verbatim during linking
  --native-linking-defaults  (hidden) Use default linking settings
  --native-compile string*   List of compile options
  --native-compile-defaults  (hidden) Use default compile options
  --embed-resources          Embed resources into the Scala Native binary (can be read with the Java resources API)

Other options:
  --suppress-directives-in-multiple-files-warning, --suppress-warning-directives-in-multiple-files  Suppress warnings about using directives in multiple files
  --suppress-outdated-dependency-warning         Suppress warnings about outdated dependencies in project
  --workspace path                               (hidden) Directory where .scala-build is written
  --runner                                       (hidden) Should include Scala CLI runner on the runtime ClassPath. Runner is added by default for application running on JVM using standard Scala versions. Runner is used to make stack traces more readable in case of application failure.
  --semantic-db                                  (hidden) Generate SemanticDBs
  --add-stubs                                    (hidden) Add dependency for stubs needed to make $ivy and $dep imports to work.
  --default-forbidden-directories                (hidden)
  --forbid string*                               (hidden)
  --strict-bloop-json-check                      (hidden)
  -version, --version

This probably should be tweaked further separately at a later date.
case-app currently doesn't seem to support filtering out Other options, for example

Copy link
Contributor

@lwronski lwronski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Copy link
Member

@tgodzik tgodzik left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work! I left a very minor comment for a future refactor

@Gedochao Gedochao merged commit d79446b into VirtusLab:main Feb 21, 2023
@Gedochao Gedochao deleted the shorter-options-help branch February 21, 2023 14:15
@Gedochao Gedochao added enhancement New feature or request SIP-46 All the issues related to SIP-46 to turn Scala CLI into the official scala runner command. labels Feb 22, 2023
@Gedochao Gedochao mentioned this pull request Mar 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request SIP-46 All the issues related to SIP-46 to turn Scala CLI into the official scala runner command.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Output of scala run --help is unclear
4 participants