cabal user's guide comment
djp at arqux.com
Sat May 14 17:22:34 CEST 2011
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.
- Jake -
More information about the cabal-devel