cabal install of library behavior does not match documentation

[joeyh]

Describe the bug

cabal install, run in a package that is a library, complains that it "does
not contain any executables". I expected the old cabal behavior of installing it to the global library directory.

cabal install --lib works. However, cabal install --help says, at the top:
"If TARGET is a library, it will be added to the global environment."

it took me some hunting to realize that was wrong and that I now need --lib.

To Reproduce

cabal unpack Cabal-3.2.0.0
cd Cabal-3.2.0.0
cabal install 

System information

cabal-install version 3.0.0.0
compiled using version 3.0.1.0 of the Cabal library 

[yaxu]

I'd argue that it's the behaviour that is wrong, rather than the documentation, ref #6481

[gbaz]

relatedly, the cabal manual still has the wrong info at https://cabal.readthedocs.io/en/3.6/installing-packages.html#building-and-installing-packages even though nearly everywhere else is cleaned up.

[Mikolaj]

Well spotted. Volunteers welcome.

[ulysses4ever]

The problematic wording from OP ("If TARGET is a library") has been fixed in b0e88b1 (by adding "and --lib is used").

The problematic docs mentioned by @gbaz have been purged in aa3d66d.

Should this be closed? I think that cabal install docs could be (even) more clear that installing a library into the global env is a bad idea, and teach about --package-env more eagerly. But this current ticket seems to have been well served.

[Mikolaj]

I think you are right. If nobody objects, let's close in favour of a more up to date or more detailed ticket (probably a new one, but who knows what we already have).

[Mikolaj]

Thank you; closing.