How are Hackage package names mapped to 'cabal install' names?

Question

I'm using cabal to download Haskell packages.

The following works:

> cabal install JSON

It gets Text.JSON

However, this fails:

> cabal install Data.List.Key
cabal: "Data.List.Key" is not valid syntax for a package name or package
dependency.

What is the syntax problem here? How do I make cabal get Data.List.Key? In general, for a package of name X.Y, what name does cabal install need in order to find the package? (I'm confused why cabal install JSON gets Text.JSON, and not Foobarbaz.JSON)

Answer 1

The cabal install command uses package names. Package names are different from module names. If you look on the hackage page for the text package, you'll see that the package name is "text", but it exports a module called Data.Text (amongst others). Packages can export any number of modules and there does not have to be any relationship between the name of the package and the name of the modules it exports.

If you know a package you want, but you don't know the exported modules, look on the hackage page for that package. To do this, I go to "http://hackage.haskell.org/package/" in my browser. I've gone there so many times, it auto-completes very quickly, then I add the package name to the end of that url. If I don't know the exact package name, then I just go to that page and search the package list for what I want.

The converse situation where you know what module you want but don't know what package provides it is a little more difficult. In this case, I rely on the wonderful Haskell search engine Hoogle.
(Another one Hayoo, has been offline for a while.)

Answer 2

Packages can include more than one module. There is no rule about how module names map to package names.

If you know the module name and want to find the package it is in, browse it's hackage documentation.

The url of the module description contains the package name after the package part, e.g. the url of Linear.Quaterion is

http://hackage.haskell.org/package/ linear-1.21.1 /docs/Linear-Quaternion.html

On that page the package name is also shown in the top left end.

If you know the package name, you can query which modules are included with

cabal info <package name>.