cabal installation failure

[Mats Ahlgren]

Hello,

Thank you for the reply!

> Let us know what you think would have helped you.
I'd be happy to try to help.

[reply inline]
On Fri, May 21, 2010 at 4:35 AM, Duncan Coutts
<duncan.coutts at googlemail.com> wrote:
> On Wed, 2010-05-19 at 01:45 -0400, Mats Ahlgren wrote:
>
>> > I've installed Cabal once in the past with no trouble. However I can
>> > no longer do so.
>> >
>> > I tried to install Cabal on a new computer:
>> > - I visited http://www.haskell.org/cabal/download.html and got the
>> > latest version
>> > - I followed the directions in the README file
>> > - No error messages were thrown, the process was "successful" and I
>> > now have a ~/.cabal directory --but-- it doesn't seem as if I have a
>> > 'cabal' command in /usr/bin or /usr/local/bin or even anywhere in the
>> > ~/.cabal directory.
>
> Ah, I'm guessing you downloaded the Cabal library package, rather than
> the cabal-install command line package.

That's probably the case. I googled for [Haskell Cabal] and ended up
at at a page where the only download link was
http://www.haskell.org/cabal/download.html . Unfortunately the first
link I found was the "Cabal library" and not the "cabal-install tool".
You may wish to have something like:

* Section: Installing Cabal
    There are two Cabals, one is the library and one is the package
    manager tool you can run as "cabal" from the command-line,
    which is called <i>cabal-install</i>. You probably want cabal-install.
    * Subsection: Cabal-install
        For guaranteed current instructions, visit [link to trac]. *
        Otherwise, go to http://www.haskell.org/cabal/release/?C=M;O=A
and download the latest "cabal-install" package. **
    * Subsection: Cabal library
        <b>Warning</b>: You <b>only</b> need this under
[circumstances]. It is used for [...]. ***

* It might be prudent to (as above) remove the cabal-install section
and redirect to
http://hackage.haskell.org/trac/hackage/wiki/CabalInstall , where the
installation instructions are up-to-date.
** Note that this url is *different* than the one on Trac. Furthermore
the URL has both cabal and cabal-install in the same directory.
*** If this library is only used for internal development, consider
perhaps moving it to a different page or perhaps renaming it
cabal-devel?

Please consider encouraging Linux distro package-maintainers to bundle
cabal-install with ghc, or at least provide a package.

I'm a bit confused: I am somewhat under the impression that
cabal-install is just cabal+[cabal-install command]? If so, wouldn't
it be simpler to just distribute the bundled cabal-install+library?
(There are probably good reasons at work here that I'm not aware of,
just thought I'd mention it.)

> The README for the latter involves running the ./bootstrap.sh which is
> included in the cabal-install-x.y.tar.gz package.
>
> The README for the Cabal library mentions at the top that there is also
> the cabal-install package. Perhaps that notice needs to be clearer.
> Maybe the download page needs to be clearer too.
>
> Let us know what you think would have helped you.

I'm certain now I didn't download the cabal-install package. Upon
rereading the README in the cabal(library) package
http://darcs.haskell.org/cabal/README , I do indeed notice the warning
at the top. Despite being at the top, people are probably looking in
the readme for the instructions on how to set up Cabal, and usually
are desensitized to informational preambles. If you do indeed want a
warning (which you perhaps do) I would humbly recommend:

The Cabal library package
=========================

Home page: http://www.haskell.org/cabal/


N O T I C E
=========================

If you also want the `cabal` command line program then you need
the `cabal-install` package in addition to this library.


Installation instructions for the Cabal library
===============================================

Installing as a user (no root or administer access)
---------------------------------------------------

    read notice above

    ghc --make Setup
    ./Setup configure --user
    ./Setup build
    ./Setup install

Installing as root / Administrator
----------------------------------

    read notice above

    ghc --make Setup
    ./Setup configure
    ./Setup build
    sudo ./Setup install

Compiling Setup rather than using `runghc Setup` is much faster and works on
Windows. For all packages other than Cabal itself it is fine to use `runghc`.

This will install into `/usr/local` on unix and on Windows it will
install into `$ProgramFiles/Haskell`. If you want to install
elsewhere use the `--prefix=` flag at the configure step.

>> > - There was no extra information in the README file; no examples of
>> > how to proceed or sample usage
>> > - I then followed the directions to view the user docs online. After
>> > locating them, it seems there are no instructions for end-users, just
>> > for people who wish to submit packages.
>> > - I then looked at
>> > http://hackage.haskell.org/trac/hackage/wiki/CabalInstall and noticed
>> > there was another way to do this -- with a ./bootstrap.sh -- but this
>> > file is missing in the latest version.
>
> I'm guessing you're still looking at the Cabal library package which
> indeed has no bootstrap, it's the cabal-install package which has that.

Indeed, please ignore anything I said here. =)

>> > The end result is that even after 2 hours, I am unable to figure out
>> > why Cabal is not working. If I was a new user, I wouldn't even know
>> > what Cabal does.
>> >
>> > I attempted to file a bug, but then saw I was unable to because the
>> > Trac installation is protected with basic http authentication.
>
> It gives the guest account username and password on the main front page
> of the trac.

In my humble opinion, important pieces of information should be found
very close to the place they're needed (relatively close to anything
which might be confusing). For example, the knowledge that there
existed a cabal-install vs. a normal cabal package, or the warning in
the README file. Furthermore, I think this breaks people's normal
expectations if they've seen Trac before and are used to making a new
account.

It seems that the only reason this username and password exists is to
prevent spam from untargetted botnet attacks? If so, it may be a bit
ironic, but there is no reason not to put it as a message in the HTTP
auth popup.

e.g.

The username/password is guest/haskell (more info on front page).
Username: ________
Password: ________

>> > I write this out of concern, because these issues with documentation
>> > (and what may be a critical bug) may make people shy away from Haskell
>> > as a platform.
>> > Also if anyone might have insight into how to fix this, it would be
>> > much appreciated; thank you.
>
> Thanks for your report. I'd welcome your suggestions on what bits of
> documentation should be clarified. It's not always obvious to us since
> we're too familiar with it all.
>
> One thing that's particularly confusing is simply the package naming.
> The original package was simply called "Cabal" and then later when we
> added a separate command line program we had to give that a different
> name. The plan in future is to reorganise the packages a bit and we'll
> take the opportunity to call the main user package simply "cabal".

I think that would help a lot -- perhaps even more if it was
integrated with GHC and other distributions so an installation is not
necessary.

sidenote 1:
Mention of Cabal could be included in popular Haskell tutorials. This
might help in terms of "discoverability".

sidenote 2:
Today I downloaded cabal-install from hackage, per the instructions on
the front page of trac. You may wish to nuke the ~/.cabal and ~/.ghc
directories before an install (warning/prompting the user and telling
them a backup is being made). Attempting to ./bootstrap.sh while those
directories existed resulted in a corrupt install. Mainly it was the
~/.ghc directory that was problematic. (sub-sidenote: I was given
instructions to run ghc-pkg -v check without knowing why I was running
the command. Furthermore, the -v flag does not exist.)

sidenote 3:
I might further suggest that the haskell-devel-moderator/admin/? email
address be listened to; alternatively (in case it is full of spam like
most mailman addresses are) perhaps the "your message has bounced"
mail could read "Please click the link sent in your registration mail
and follow the instructions on the page. You will be required to
[...]. Wait until the final confirmation page has loaded. If this
fails, please try re-registering." Sorry, that probably sounds like an
incredibly silly suggestion and should not be implemented. It's just
that I've registered on mailman lists so many times I must have either
overlooked that, or closed the tab after confirming (before the final
confirmation http request could be sent). This is a major usability
bug in Mailman (error messages which tell you you are wrong, not why
you are wrong, nor how to fix it) and unrelated to Cabal in any way.

> Duncan

Thanks.

Hope this helps,
Mats