list-bin is missing from user's manual

[Bodigrim]

list-bin command, added in 3.4, is still missing from user's manual as of 3.6: https://cabal.readthedocs.io/en/3.6/cabal-commands.html.

[jneira]

I wonder if this command should be converted ina subcommand or flag in the incoming cabal info command, as it is extracted from plan.json, one of the main sources of cabal info. We could add first level commands for other useful info, like cabal compiler-path but it seems more scalable group all the useful info together.

From that pov i would delay its documentation, to make its migration smoother.

[Bodigrim]

It's not like list-bin is an undocumented feature: cabal --help clearly mentions it. list-bin is already present for two major versions of Cabal, and I have scripts depending on it.

[philderbeast]

From the command line help, list-bin lists the path to a single build product; exe or test suite.

> cabal --help 
Command line interface to the Haskell Cabal infrastructure.

See http://www.haskell.org/cabal/ for more information.

Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]]

Commands:
 [package]
  list-bin          list path to a single executable.

> cabal list-bin --help
list path to a single executable.

Usage: cabal list-bin [FLAGS] TARGET

List path to a build product.

Flags for list-bin:
 -h, --help                     Show this help text
 ...

It won't list multiple paths but knows which build products a package has.

> cabal list-bin cabal-install
cabal: The list-bin command is for finding a single binary at once. The target
'cabal-install' refers to the package cabal-install-3.7.0.0 which includes the
executable 'cabal', the test suite 'unit-tests', the test suite
'memory-usage-tests', the test suite 'long-tests' and the test suite
'integration-tests2'.

For a scope that results in only one item we'll get a path.

> cabal list-bin cabal-install:exes
/.../cabal/dist-newstyle/build/x86_64-osx/ghc-8.10.7/cabal-install-3.7.0.0/x/cabal/build/cabal/cabal

> cabal list-bin cabal-install:cabal
/.../cabal/dist-newstyle/build/x86_64-osx/ghc-8.10.7/cabal-install-3.7.0.0/x/cabal/build/cabal/cabal

We can't scope to all:exes and all is not the same as giving no scope.

> cabal list-bin cabal-install:all:exes
cabal: Unknown target 'cabal-install:all:exes'.
The package cabal-install has no component 'all'.

> cabal list-bin cabal-install:all
cabal: Unknown target 'cabal-install:all'.
The package cabal-install has no component 'all'.

We can scope to tests but as there are more than one of these, I need to ask for them individually to get their paths.

> cabal list-bin cabal-install:tests
cabal: The list-bin command is for finding a single binary at once. The target
'cabal-install:tests' refers to the test suites in the package
cabal-install-3.7.0.0 which includes the test suite 'unit-tests', the test
suite 'memory-usage-tests', the test suite 'long-tests' and the test suite
'integration-tests2'.

> cabal list-bin cabal-install:unit-tests
/.../ghc-8.10.7/cabal-install-3.7.0.0/t/unit-tests/build/unit-tests/unit-tests

> cabal list-bin cabal-install:memory-usage-tests
/.../ghc-8.10.7/cabal-install-3.7.0.0/t/memory-usage-tests/build/memory-usage-tests/memory-usage-tests

> cabal list-bin cabal-install:long-tests
/.../ghc-8.10.7/cabal-install-3.7.0.0/t/long-tests/build/long-tests/long-tests

> cabal list-bin cabal-install:integration-tests2
/.../ghc-8.10.7/cabal-install-3.7.0.0/t/integration-tests2/build/integration-tests2/integration-tests2

[Mikolaj]

@ philderbeast: would you like to turn that summary into a PR? If so, don't worry about how it fits the existing docs too much --- create a new section at a likely place and dump the knowledge.

[philderbeast]

@ philderbeast: would you like to turn that summary into a PR? If so, don't worry about how it fits the existing docs too much --- create a new section at a likely place and dump the knowledge.

Yes, happy to.

[Mikolaj]

Splendid. Thank you.