Skip to content

Better organization of "--help" output #1333

@mgsloan

Description

@mgsloan

This would likely entail changes to optparse-applicative. The idea is that many commands and options aren't needed so commonly, and so it would be helpful to start out the --help output with the common commands and options. I've thought this would be good for a while, particularly in the context of stack help. We might instead have something like:

stack - The Haskell Tool Stack

Usage: stack [--help] [--version] [--numeric-version] [--docker*]
             ([--verbosity VERBOSITY] | [-v|--verbose]) ([--system-ghc] |
             [--no-system-ghc]) ([--install-ghc] | [--no-install-ghc])
             [--arch ARCH] [--os OS] [--ghc-variant VARIANT] [-j|--jobs JOBS]
             [--extra-include-dirs DIR] [--extra-lib-dirs DIR]
             ([--skip-ghc-check] | [--no-skip-ghc-check]) ([--skip-msys] |
             [--no-skip-msys]) [--local-bin-path DIR] ([--modify-code-page] |
             [--no-modify-code-page]) [--resolver RESOLVER]
             [--compiler COMPILER] ([--terminal] | [--no-terminal])
             [--stack-yaml STACK-YAML] COMMAND

Common options:
  --help                   Show this help text
  --version                Show version
  --resolver RESOLVER      Override resolver in project file
  --stack-yaml STACK-YAML  Override project stack.yaml file (overrides any
                           STACK_YAML environment variable)
  -v,--verbose             Enable verbose mode: verbosity level "debug"

Other options:
  --numeric-version        Show only version number
  --docker*                Run 'stack --docker-help' for details
  --verbosity VERBOSITY    Verbosity: silent, error, warn, info, debug
  --system-ghc             Enable using the system installed GHC (on the PATH)
                           if available and a matching version
  --no-system-ghc          Disable using the system installed GHC (on the PATH)
                           if available and a matching version
  --install-ghc            Enable downloading and installing GHC if necessary
                           (can be done manually with stack setup)
  --no-install-ghc         Disable downloading and installing GHC if necessary
                           (can be done manually with stack setup)
  --arch ARCH              System architecture, e.g. i386, x86_64
  --os OS                  Operating system, e.g. linux, windows
  --ghc-variant VARIANT    Specialized GHC variant, e.g. integersimple (implies
                           --no-system-ghc)
  -j,--jobs JOBS           Number of concurrent jobs to run
  --extra-include-dirs DIR Extra directories to check for C header files
  --extra-lib-dirs DIR     Extra directories to check for libraries
  --skip-ghc-check         Enable skipping the GHC version and architecture
                           check
  --no-skip-ghc-check      Disable skipping the GHC version and architecture
                           check
  --skip-msys              Enable skipping the local MSYS installation (Windows
                           only)
  --no-skip-msys           Disable skipping the local MSYS installation (Windows
                           only)
  --local-bin-path DIR     Install binaries to DIR
  --modify-code-page       Enable setting the codepage to support UTF-8 (Windows
                           only)
  --no-modify-code-page    Disable setting the codepage to support UTF-8
                           (Windows only)
  --compiler COMPILER      Use the specified compiler
  --terminal               Enable overriding terminal detection in the case of
                           running in a false terminal
  --no-terminal            Disable overriding terminal detection in the case of
                           running in a false terminal

Common commands:
  build                    Build the package(s) in this directory/configuration
  install                  Shortcut for 'build --copy-bins'
  new                      Create a new project from a template. Run `stack
                           templates' to see available templates.
  init                     Initialize a stack project based on one or more cabal
                           packages
  setup                    Get the appropriate GHC for your project
  exec                     Execute a command

Other commands:
  uninstall                DEPRECATED: This command performs no actions, and is
                           present for documentation only
  test                     Shortcut for 'build --test'
  bench                    Shortcut for 'build --bench'
  haddock                  Shortcut for 'build --haddock'
  templates                List the templates available for `stack new'.
  solver                   Use a dependency solver to try and determine missing
                           extra-deps
  path                     Print out handy path information
  unpack                   Unpack one or more packages locally
  update                   Update the package index
  upgrade                  Upgrade to the latest stack (experimental)
  upload                   Upload a package to Hackage
  sdist                    Create source distribution tarballs
  dot                      Visualize your project's dependency graph using
                           Graphviz dot
  ghc                      Run ghc
  ghci                     Run ghci in the context of package(s) (experimental)
  repl                     Run ghci in the context of package(s) (experimental)
                           (alias for 'ghci')
  runghc                   Run runghc
  runhaskell               Run runghc (alias for 'runghc')
  eval                     Evaluate some haskell code inline. Shortcut for
                           'stack exec ghc -- -e CODE'
  clean                    Clean the local packages
  list-dependencies        List the dependencies
  query                    Query general build information (experimental)
  ide                      IDE-specific commands
  docker                   Subcommands specific to Docker use
  config                   Subcommands specific to modifying stack.yaml files
  image                    Subcommands specific to imaging (EXPERIMENTAL)
  hpc                      Subcommands specific to Haskell Program Coverage

Being able to split up options lists will become particularly relevant for stack ghci once it also takes all of the stack build options (#1186). All of the ghci-specific options get lost in a sea of build options :/

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions