diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/haskell-users-guide.xml | 84 | ||||
| -rw-r--r-- | doc/meta.xml | 2 | ||||
| -rw-r--r-- | doc/quick-start.xml | 2 | ||||
| -rw-r--r-- | doc/stdenv.xml | 28 |
4 files changed, 114 insertions, 2 deletions
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> diff --git a/doc/meta.xml b/doc/meta.xml index b36f3915ec19..98031612523e 100644 --- a/doc/meta.xml +++ b/doc/meta.xml @@ -61,7 +61,7 @@ $ nix-env -qa hello --meta --json "i686-openbsd", "x86_64-openbsd" ], - "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/ex-2/default.nix:14" + "position": "/home/user/dev/nixpkgs/pkgs/applications/misc/hello/default.nix:14" }, "name": "hello-2.9", "system": "x86_64-linux" diff --git a/doc/quick-start.xml b/doc/quick-start.xml index 8d51f4c30e6e..5ed959abacec 100644 --- a/doc/quick-start.xml +++ b/doc/quick-start.xml @@ -56,7 +56,7 @@ $ git add pkgs/development/libraries/libfoo/default.nix</screen> <listitem> <para>GNU Hello: <link - xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/ex-2/default.nix"><filename>pkgs/applications/misc/hello/ex-2/default.nix</filename></link>. + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>. Trivial package, which specifies some <varname>meta</varname> attributes which is good practice.</para> </listitem> diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 1556ffd057f9..7ba24db2e050 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -899,6 +899,34 @@ following: phase.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>separateDebugInfo</varname></term> + <listitem><para>If set to <literal>true</literal>, the standard + environment will enable debug information in C/C++ builds. After + installation, the debug information will be separated from the + executables and stored in the output named + <literal>debug</literal>. (This output is enabled automatically; + you don’t need to set the <varname>outputs</varname> attribute + explicitly.) To be precise, the debug information is stored in + <filename><replaceable>debug</replaceable>/lib/debug/.build-id/<replaceable>XX</replaceable>/<replaceable>YYYY…</replaceable></filename>, + where <replaceable>XXYYYY…</replaceable> is the <replaceable>build + ID</replaceable> of the binary — a SHA-1 hash of the contents of + the binary. Debuggers like GDB use the build ID to look up the + separated debug information.</para> + + <para>For example, with GDB, you can add + +<programlisting> +set debug-file-directory ~/.nix-profile/lib/debug +</programlisting> + + to <filename>~/.gdbinit</filename>. GDB will then be able to find + debug information installed via <literal>nix-env + -i</literal>.</para> + + </listitem> + </varlistentry> + </variablelist> </section> |