# cabal-hoogle ![GitHub Action Badge](https://github.com/kokobd/cabal-hoogle/actions/workflows/test.yml/badge.svg?branch=main) Like `stack hoogle`, but works for cabal projects. Generates hoogle database of your local packages and all dependencies. ## Installation Compiling from source requires a minimum GHC version of 8.10. Having `cabal-hoogle` installed, you may use it on a wider range of GHC, as long as the `Cabal` used to build `cabal-hoogle` and `cabal-install` match. Step 1, run `cabal update` to make sure you are using the latest hackage index Step 2, check the `Cabal` library version used by your cabal ``` cabal --version ``` It shows my cabal is using `3.6.3.0` of Cabal library. **`cabal-hoogle` requires at least Cabal 3.2**. Update it before continue. ``` cabal-install version 3.6.2.0 compiled using version 3.6.3.0 of the Cabal library ``` Step 3, use `cabal install` to install `cabal-hoogle` from Hackage, specifying the `Cabal` library version you fetched above. ``` cabal install --constraint="Cabal == 3.6.3.0" cabal-hoogle ``` ## Usage ### Prerequisite #### Install Hoogle Make sure `hoogle` is installed in your `$PATH`. You can do this by running `cabal install hoogle` #### Enable Hoogle for Cabal Make sure your `~/.cabal/config` has the following entries. (DON'T remove existing entries!) [Check the official docs](https://cabal.readthedocs.io/en/3.6/installing-packages.html) if you don't know where is your cabal's global configuration file ``` documentation: True haddock hoogle: True html: True ``` Or, run this command in bash: ``` cabal user-config update -a "documentation: True haddock hoogle: True html: True" ``` #### Build Project with Cabal Then, run `cabal build all` on your project, so that cabal will build haddock and hoogle files for your local packages and dependencies. > NOTE: Adding `--enable-documentation --haddock-hoogle --haddock-html` to your build command won't work for dependencies as I tried. ### Generate ``` cabal-hoogle generate ``` This generates the hoogle database. You will see logs very similar to `stack hoogle --rebuild` ### Run Hoogle With `cabal-hoogle run --`, extra arguments are passed directly to `hoogle`. You may start a server like this: ``` cabal-hoogle run -- server --local --port 9000 ``` Or directly search in command line like this: ``` cabal-hoogle run -- search catMaybes ``` ### More Options Run `cabal-hoogle --help` to see more options. For example if you are using a non-default build dir (not `dist-newstyle`), or you have multiple GHC verisons on the same project. Below is a complex example: ``` cabal-hoogle --compiler ghc-9.2.3 --platform "x86_64-linux" --builddir mydist generate ``` ## FAQ ### Many packages missing documentation If you see output like this when running `cabal-hoogle generate` ``` Packages missing documentation: ansi-terminal ansi-wl-pprint async base-orphans base16-bytestring base64-bytestring Cabal cabal-hoogle clock colour extra hashable haskell-src-exts haskell-src-meta optparse-applicative primitive regex-base regex-tdfa safe split string-interpolate syb text-conversions th-abstraction th-compat th-expand-syns th-lift th-lift-instances th-orphans th-reify-many transformers-compat typed-process unliftio-core utf8-string vector vector-stream Found 27 warnings when processing items ``` Probably you haven't built dependencies with hoogle enabled. Check [prerequisites](#prerequisite) more carefully. ### Cabal version mismatch Make sure to build `cabal-hoogle` with the exact same `Cabal` library as your `cabal-install`. You can use `cabal --version` to check the version of `Cabal` library. See [Installation](#installation). ### Core libraries missing documentation If you are on macOS or Windows, and using `ghcup`, your `ghc` probably doesn't come with docs. See [this](https://gitlab.haskell.org/ghc/ghc/-/issues/20903) and [this](https://github.com/haskell/haskell-language-server/issues/208#issuecomment-1162169087) for details of the upstream issue.