The GHC users guide has some more info on packages that may help: http://www.haskell.org/ghc/docs/latest/html/users_guide/packages.html In answer to your question "what is a package?", it says "A package is a library of Haskell modules known to the compiler". -David On May 14, 2011, at 10:22 AM, 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.

My work involves becoming reasonably accomplished in haskell, at which I am a relative beginner. As it is important to be able to use a language in its natural ecosystem, I sat down yesterday to study packages, Cabal, and ghc-pkg. I found this to be rather hard going, mostly because of the documentation - particularly the Cabal user's guide. I appreciate the fact that one of more people went to considerable effort to compose the user's guide, which I get for free. However, I feel that editorial improvements are in order.

I find the user's guide unhelpful for several reasons, but I shall only point out one thing in this post: The user's guide fails to provide, early on, information that is IMHO essential to a clear understanding of cabal: What IS a package, i.e. what does the physical implementation of a package look like?

The user's guide dances all around this. It mentions the "aims" of cabal, that it provides interfaces, that "developers write packages", that "users install Cabal packages", etc. Under the subheading "Packages" the user's guide says that a "package is the unit of distribution", etc. Ok....

The first hint that a package might possibly be implemented as a hierarchy of directories/files is under the subheading "Creating a package", which makes reference to adding files to the root directory of a package. If that is what a package is (which I remain unsure about) this is too little information, and far too late. To add to the confusion, the examples of packages given in this subsection are NOT examples of packages. They are displays of some kind of file or other - a package description file, or something - whatever a .cabal file might be.

In summary, I think the user's guide stands in need of a substantial rewrite.

Thanks.

- Jake -

_______________________________________________ cabal-devel mailing list cabal-devel@haskell.org http://www.haskell.org/mailman/listinfo/cabal-devel

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.

My work involves becoming reasonably accomplished in haskell, at which I am a relative beginner. As it is important to be able to use a language in its natural ecosystem, I sat down yesterday to study packages, Cabal, and ghc-pkg. I found this to be rather hard going, mostly because of the documentation - particularly the Cabal user's guide. I appreciate the fact that one of more people went to considerable effort to compose the user's guide, which I get for free. However, I feel that editorial improvements are in order.

You're right, it's very dated and presents info in an unhelpful order.

I find the user's guide unhelpful for several reasons, but I shall only point out one thing in this post: The user's guide fails to provide, early on, information that is IMHO essential to a clear understanding of cabal: What IS a package, i.e. what does the physical implementation of a package look like?

Here's my current introduction, let me know what you think: http://code.haskell.org/~duncan/cabal/user-guide/#introduction I've also got a quickstart for creating packages, which is not quite done but here it is anyway: http://code.haskell.org/~duncan/cabal/user-guide/developing-packages.html#qu... (down to but not yet including the bit on package dependencies) I'll post updates to to this list when it's ready for some feedback. Particularly as a beginner and with strong opinions on the current state of the user guide I'd most appreciate your feedback. Any more notes or comments on what you would like, or woulh have liked to know would be helpful to me as I work on the new introductory sections.

The user's guide dances all around this. It mentions the "aims" of cabal, that it provides interfaces, that "developers write packages", that "users install Cabal packages", etc. Under the subheading "Packages" the user's guide says that a "package is the unit of distribution", etc. Ok....

The first hint that a package might possibly be implemented as a hierarchy of directories/files is under the subheading "Creating a package", which makes reference to adding files to the root directory of a package. If that is what a package is (which I remain unsure about) this is too little information, and far too late. To add to the confusion, the examples of packages given in this subsection are NOT examples of packages. They are displays of some kind of file or other - a package description file, or something - whatever a .cabal file might be.

So you mean in the sense that the implementation of a package consists of a bunch of files, .hs source files etc + these special packaging files (the .cabal and Setup.hs). So you want to know what the layout of these should be, or how module names match file names etc? It's certainly true that we don't talk about that, partly because there are not many restrictions, though there is the assumption that apart from package dependencies all the files are self-contained and live under one package root directory. Is it enough just to say this an give an example?

In summary, I think the user's guide stands in need of a substantial rewrite.

Yes, that was my analysis too. That and that I/we have all been putting it off for too long. Duncan