Add stack hoogle command (#55)

[chrisdone]

Pinging interested parties: @ndmitchell @borsboom @mgsloan @snoyberg

The feature

This is a regular exec interface to Hoogle, but it adds a --database argument. This saves me from judging a new interface to Hoogle. The basic use-case is self-explanatory:

$ stack hoogle Conduit
module Data.Conduit
type Conduit i m o = ConduitM i o m ()
module Data.CSV.Conduit
[...]

To generate a database, one runs:

$ stack hoogle -- generate --local

If you run stack hoogle foo without a database file present, it will automatically run stack hoogle --generate --local:

$ stack hoogle Conduit
Hoogle database doesn't exist.
Running: stack hoogle -- generate --local
You can re-run this command later to update the database.
Starting generate
Reading ghc-pkg... 0.11s
[1/142] Cabal... 0.42s
[2/142] Glob... 0.01s
[...]

Details & issues

The database argument is set to $PROJECT_ROOT/.stack-work/hoogle as suggested by @ndmitchell in #55 (comment).

The issue is that this support is available in Hoogle 5, which is not released yet. The workaround for users is to run:

$ git clone [email protected]:ndmitchell/hoogle.git
$ cd hoogle
$ stack install

With hoogle version 5 in the ~/.local/bin, the above feature works.

[chrisdone]

Oh, idea: we could have stack haddock automatically update the hoogle database, perhaps with a configuration entry.

[mgsloan]

Awesome!

Why make this part of the exec command? None of the exec options are relevant to hoogle. I can't think of any use for --plain, --no-ghc-package-path, --no-stack-exe, or --package. So, I'd rather keep the codepath separate (though perhaps using Stack.Exec.exec, which is used in a fair number of places).

As for the hoogle version thing, how about when the hoogle invocation fails, run hoogle --numeric-version and giving the user some instructions when it's < 5.

[ndmitchell]

The fact that Hoogle 5 isn't released yet more than a year after I was aiming for does suck, and makes something like this harder, but I'm very grateful to @chrisdone for using the new version in preference (I owe 🍻).

One way to sidestep version issues would have to have stack hoogle install its own version of Hoogle, from git, into somewhere Stack controlled, and then use that - much like it does with GHC.

[mgsloan]

Yep, auto-installing hoogle 5 would be cool!

[chrisdone]

Why make this part of the exec command?

I started a separate codepath but found myself repeating the code in that codepath, and saw that it uses exec to launch GHC specially, so figured it was an okay place to put it. The code is a bit hairy so I didn't feel like refactoring it.

As for the hoogle version thing, how about when the hoogle invocation fails, run hoogle --numeric-version and giving the user some instructions when it's < 5.

That's a nice idea. I'd considered auto-installing but thought that might be a bit invasive.

One way to sidestep version issues would have to have stack hoogle install its own version of Hoogle, from git, into somewhere Stack controlled, and then use that - much like it does with GHC.

Re-considering it, perhaps it could use one of the .tar.gz from Github (avoiding the need for the Git dependency for users who don't have it) and yeah, just install it in Stack's own directory structure. That's consistent with the use of GHC. That gets around the problem of when Hoogle 5 is going to be released. We'd like for this to just work out of the box for newbies and experts alike. We can announce the feature in the next Stack release as simply stack hoogle blah.

One nice part of this feature is that you can hoogle your own codebase.

A separate note: perhaps it should also run stack haddock . automatically before building a new hoogle database, to make sure it's there? I just realised I'd performed this step myself but a user probably won't have done this.

[mgsloan]

I think we're going to a do a release soon, should we add this? TODO as far as I'm concerned:

• Not take the stack exec options.
• Check for hoogle version
• Open an issue about potentially installing hoogle version
• One of:
  • Have it run haddock first
  • Have it detect when haddock needs to run, and tell the user that
  • Create an issue about the need for this, and document it

[chrisdone]

AFK till Monday but I'd like to contribute to getting this in before the
release with auto download of hoogle5. Haddock running as a message sounds
good to me.

[chrisdone]

Working on a new branch with the above things in mind.