cabal user's guide comment

[Duncan Coutts]

On Sat, 2011-05-28 at 10:55 -0400, Jake Penton wrote:
> On 2011-05-17, at 7:09 PM, Duncan Coutts wrote:
> 
> > On Sat, 2011-05-14 at 11:22 -0400, Jake Penton wrote:
> >> Greetings. 
> >> 
> >> What is a package?
> >> 
> >> The reason I ask this question is stated below. If I am posting to the
> >> wrong list, let me know. Also, my tone by be slightly abrasive: I am
> >> rather frustrated. If I have misread the Cabal user's guide, or am
> >> otherwise have my head up my butt, feel free to let me know. Also if I
> >> can help (which I doubt, as a beginner) tell me how.
> > 
> > This is very timely. I'm currently rewriting the user guide.
> > 
> Ok, great. Thanks for your work.
> 
> I have been away for two weeks, and so have only just been able to follow up on the answers to my post
> 
> > 
> > Here's my current introduction, let me know what you think:
> > 
> > http://code.haskell.org/~duncan/cabal/user-guide/#introduction
> > 
> 
> I took a look at it the link.
> 
> I seem to be having some trouble communicating what is puzzling me.
> Again, the fault may be my own. At my level of knowledge I am often
> unable to discern what is part of haskell proper, what is just ghc (or
> another implementation), and what is a Cabal convention.

Right, and new users shouldn't need to already know exactly where these
boundaries are.

> I have only skimmed the haskell 98 and 2010 reports; I should probably
> read them in detail to begin to sort this stuff out. I do not see
> anything in these documents that specifies how compilation units are
> organized, or whether the hierarchical module namespace in haskell
> somehow relates to a directory hierarchy. This is probably
> implementation dependent.

Yeah, strictly speaking the Haskell spec does not require modules to
exist in files, so it doesn't give any file name mapping. Of course all
the common implementations follow the same convention.

The Haskell spec of course isn't a tutorial.

What I'm thinking of is adding a bit to the beginning of quickstart that
links to a section with tips on how to organise the files in a project
dir, and in that section we can explain the standard convention that
Foo.Bar maps to Foo/Bar.hs or .lhs. 

http://code.haskell.org/~duncan/cabal/user-guide/developing-packages.html#quickstart

Or perhaps it's best to link to one of the basic tutorials

http://www.haskell.org/haskellwiki/Tutorials

> In reply to my original post David Peixotto pointed to the ghc user's
> guide, which states that  "A package is a library of Haskell modules
> known to the compiler".  May I take it, then, that on my Mac a cabal
> package is an static archive file, i.e. 'some-package.a'? I doubt it.
> The term "library" is pretty overloaded, so this description seems too
> vague to be helpful.

The definition there is an abstract definition, and it is referring to
ghc's notion of a compiled and registered package. The actual
representation of a compiled & registered package is not interesting or
useful. You want to know how to make a package, and specifically what
the source layout for one of these should be.

> In another reply Antoine Latter stated that "A cabal package is a set
> of files along with a package description file (named *.cabal)".

So he's referring to a Cabal package, which is the source
representation, as opposed to the compiled & registered ghc package that
David mentioned.

I'll add something to the package concepts section to describe the
distinction and the relationship between the two. It's basically just
the source vs binary versions of the same thing.

> Ok, but I assume that the collection of files that make up a cabal
> package are meant to be organized some way or other. The information
> on this may be in the Cabal user guide somewhere, but it does not jump
> out at me. May I conclude that I can have one of the files on the
> flash drive in my pocket, another on a web server somewhere, and a
> third one in my home directory on my Mac, and that these can
> constitute a Cabal package?

In the beginning of my new quickstart section I say that all these files
need to live under one common project root directory.

http://code.haskell.org/~duncan/cabal/user-guide/developing-packages.html#quickstart

> What I believe is missing in the Cabal user guide is something like
> what appears in the documentation on java packages. I am not really a
> java programmer - my reference to it is only to clarify my point. Take
> a look at the third paragraph of this page:
> http://java.sun.com/docs/books/jls/third_edition/html/packages.html.
> The paragraph begins thusly: "A package can be stored in a file
> system...." The document then provides internal links to describe how
> the various files that make up a java package might be organized. The
> information appears very early in the document, which I would like to
> see in the Cabal user guide.

Right, so in Java packages are really part of the language whereas we
have bolted them on the side which means we've ended up documenting
packages in isolation and assuming people already know how a simple
multi-module program is organised as files. But of course that division
isn't known or useful to new users.

> Thanks again. If I am being dense, kindly be patient. I'll get there
> eventually!

No, it's useful to be reminded that we already know this stuff already
but that the path to getting there is surprisingly unclear.

Duncan