# Installing Hoogle locally

The server at [hoogle.haskell.org](https://hoogle.haskell.org) provides a version of Hoogle updated daily that searches all the packages available on [Stackage](https://stackage.org). This document describes how to install and setup your own copy of Hoogle, which is useful if you want to search different packages, use the command line, or use Hoogle offline.

The first step is to obtain Hoogle, currently from the Git repo, then install it using `cabal` or `stack`.

A Hoogle database is a prebuilt index of a set of packages. A database is a single binary file (usually with extension `.hoo`) which is generated once then searched in a read-only manner. By default, Hoogle will generate the default database at `~/.hoogle/default.hoo`, but this can be configured with the `--database` flag. If you pass a custom `--database` flag, make sure to pass a similar flag when running `search` or `server`.

The remainder of this document covers generating Hoogle databases, then searching Hoogle databases.


## Generate a Hoogle database

There are several different use cases for generating databases. All ultimately take text files (usually with extension `.txt`) which are a list of functions and their types, along with information about type synonyms, instances etc. The textual database files can be generated by [Cabal](https://haskell.org/cabal/) with `cabal haddock --hoogle`.

### Index all of Stackage

Run `hoogle generate` to generate an index for the current version of Stackage LTS. This command downloads the necessary inputs from the web as required and caches them (in the same directory as the database). To force redownloading pass `--download`. To demand no downloading, failing if the data cannot be found, pass `--download=no`. Links to the results will point at Hackage.

### Index specific packages

Run `hoogle generate base filepath` to generate an index for only the `base` and `filepath` libraries. Using this command you can chose to index packages not in Stackage. Links to the results will point at Hackage.

### Index all ghc-pkg installed packages

Run `hoogle generate --local` to query `ghc-pkg` and generate links for all packages which have documentation and Hoogle input files generated. By editing your Cabal config file you can have Cabal automatically generate such files when packages are installed. Links to the results will point at your local file system.

### Index a directory

Run `hoogle generate --local=mydir` to generate an index for the packages in `mydir`, which must contain `foo.txt` Hoogle input files. Links to the results will default to Hackage, but if `@url` directives are in the `.txt` files they can override the link destination.

## Searching a Hoogle database

You can run searches on the command line or by spawning a web server.

### Command line

Just be careful not to redirect your output by doing `a -> b` and producing a file called `b`.

### Server

If your database points at the local file system pass `--local` to reserve `file://` links over `http://`, so the documentation works.

## Old usage notes

### GHCi Integration

Ever feel like having access to hoogle whilst messing around in GHCi? It's relatively easy to integrate the two. 

The following will install hoogle as a shell command, and configure GHCi to have a command ":hoogle":

* <tt>cabal install hoogle</tt>
* <tt>echo >> ~/.ghci ':def hoogle \x -> return $ ":!hoogle " ++ x'</tt>

NB. the above wraps the argument in quotes before passing to the shell command, so there is no need to supply quotes; eg.

    :hoogle map
    :hoogle (a -> b) -> [a] -> [b]

Done!

On Windows you should add the same line
 :def hoogle \x -> return $ ":!hoogle \"" ++ x ++ "\""
to file (XP/2003):
 C:\Documents and Settings\[your windows account]\Application Data\ghc\ghci.conf 
or(Windows Vista/7):
 C:\users\[your windows account]\Application Data\ghc\ghci.conf 

#### How it works

Next, we need to integrate it into GHCi. We can execute shell commands with GHCi via <code>:def</code>. Load up GHCi, and type the following:

 :def hoogle \x -> return $ ":!hoogle " ++ x

If this executes cleanly, you should be able to run hoogle commands from GHCi via <code>:hoogle</code>, i.e. <code>:hoogle map</code> or <code>:hoogle "(a -> b) -> [a] -> [b]"</code>. Be careful: you need the extra quotes when hoogling types, at least on my system. <code>:ho</code> works as an abbreviation of <code>:hoogle</code> (just <code>:h</code> clashes with <code>:help</code>).

Finally, we want to make this persist across GHCi sessions. GHCi loads a file called ~/.ghci before running, so simply stick the above <code>:def</code> in that file and all should work.

Contributed by [[User:DavidHouse|DavidHouse]]

### Emacs Integration
[[Haskell_mode_for_Emacs|haskell-mode]] from versions 2.4 onwards have the function haskell-hoogle, which will hoogle the identifier at point. Setup:

```
(require 'haskell-mode)
(define-key haskell-mode-map "\C-ch" 'haskell-hoogle)
;(setq haskell-hoogle-command "hoogle")
```

You will need a web browser configured for best results. Here's an example setup for Safari:

```
(setq browse-url-browser-function 'browse-url-safari)
 (defun browse-url-safari (url &optional new-window)
  "Open URL in a new Safari window."
  (interactive (browse-url-interactive-arg "URL: "))
  (unless
      (string= ""
               (shell-command-to-string
                (concat "open -a Safari " url)))
    (message "Starting Safari...")
    (start-process (concat "open -a Safari " url) nil "open -a Safari " url)
    (message "Starting Safari... done")))
```

Alternately, you can build the command-line hoogle (darcs repo below) and uncomment the third line above, then results will appear in a buffer.