From 8358272046196003f9b6c2cdfb2bf698cdddef91 Mon Sep 17 00:00:00 2001 From: Jan Malakhovski <oxij@oxij.org> Date: Fri, 18 Sep 2015 22:08:31 +0000 Subject: [PATCH] doc: update haskell-users-guide.xml with ghcWithHoogle stuff --- doc/haskell-users-guide.xml | 84 +++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/doc/haskell-users-guide.xml b/doc/haskell-users-guide.xml index 87c8e1b92ddb..2f3b1eabb11d 100644 --- a/doc/haskell-users-guide.xml +++ b/doc/haskell-users-guide.xml @@ -354,6 +354,90 @@ if [ -e ~/.nix-profile/bin/ghc ]; then fi </programlisting> </section> + <section xml:id="how-to-install-a-compiler-with-indexes"> + <title>How to install a compiler with libraries, hoogle and documentation indexes</title> + <para> + If you plan to use your environment for interactive programming, + not just compiling random Haskell code, you might want to + replace <literal>ghcWithPackages</literal> in all the listings + above with <literal>ghcWithHoogle</literal>. + </para> + <para> + This environment generator not only produces an environment with + GHC and all the specified libraries, but also generates a + <literal>hoogle</literal> and <literal>haddock</literal> indexes + for all the packages, and provides a wrapper script around + <literal>hoogle</literal> binary that uses all those things. A + precise name for this thing would be + "<literal>ghcWithPackagesAndHoogleAndDocumentationIndexes</literal>", + which is, regrettably, too long and scary. + </para> + <para> + For example, installing the following environment + </para> + <programlisting> +{ + packageOverrides = super: let self = super.pkgs; in + { + myHaskellEnv = self.haskellPackages.ghcWithHoogle + (haskellPackages: with haskellPackages; [ + # libraries + arrows async cgi criterion + # tools + cabal-install haskintex + ]); + }; +} +</programlisting> + <para> + allows one to browse module documentation index <link + xlink:href="https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html">not + too dissimilar to this</link> for all the specified packages and + their dependencies by directing a browser of choice to + <literal>~/.nix-profiles/share/doc/hoogle/index.html</literal> + (or + <literal>/run/current-system/sw/share/doc/hoogle/index.html</literal> + in case you put it in + <literal>environment.systemPackages</literal> in NixOS). + </para> + <para> + After you've marveled enough at that try adding the following to + your <literal>~/.ghc/ghci.conf</literal> + </para> + <programlisting> +:def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\"" +:def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\"" +</programlisting> + <para> + and test it by typing into <literal>ghci</literal>: + </para> + <programlisting> +:hoogle a -> a +:doc a -> a +</programlisting> + <para> + Be sure to note the links to <literal>haddock</literal> files in + the output. With any modern and properly configured terminal + emulator you can just click those links to navigate there. + </para> + <para> + Finally, you can run + </para> + <programlisting> +hoogle server -p 8080 +</programlisting> + <para> + and navigate to <link xlink:href="http://localhost:8080/"/> for + your own local <link + xlink:href="https://www.haskell.org/hoogle/">Hoogle</link>. + Note, however, that Firefox and possibly other browsers disallow + navigation from <literal>http:</literal> to + <literal>file:</literal> URIs for security reasons, which might + be quite an inconvenience. See <link + xlink:href="http://kb.mozillazine.org/Links_to_local_pages_do_not_work">this + page</link> for workarounds. + </para> + </section> <section xml:id="how-to-create-ad-hoc-environments-for-nix-shell"> <title>How to create ad hoc environments for <literal>nix-shell</literal></title>