nixpkgs manual: add idris docs generated from *.md

I also modified the nesting approach in haskell docs
to allow more uniform handling of markdown -> docbook conversions.
/cc #11308.
This commit is contained in:
Vladimír Čunát 2015-12-21 10:50:37 +01:00
parent 810695216a
commit 3e4035695c
3 changed files with 49 additions and 34 deletions

View file

@ -20,27 +20,39 @@ stdenv.mkDerivation {
--param callout.graphics.extension '.gif'
'';
buildCommand = ''
{
echo "<chapter xmlns=\"http://docbook.org/ns/docbook\""
echo " xmlns:xlink=\"http://www.w3.org/1999/xlink\""
echo " xml:id=\"users-guide-to-the-haskell-infrastructure\">"
echo ""
echo "<title>User's Guide to the Haskell Infrastructure</title>"
echo ""
pandoc ${./haskell-users-guide.md} -w docbook | \
sed -e 's|<ulink url=|<link xlink:href=|' \
-e 's|</ulink>|</link>|' \
-e 's|<sect. id=|<section xml:id=|' \
-e 's|</sect[0-9]>|</section>|'
echo ""
echo "</chapter>"
} >haskell-users-guide.xml
buildCommand = let toDocbook = { useChapters ? false, inputFile, outputFile }:
let
extraHeader = ''xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" '';
in ''
{
pandoc '${inputFile}' -w docbook ${optionalString useChapters "--chapters"} \
| sed -e 's|<ulink url=|<link xlink:href=|' \
-e 's|</ulink>|</link>|' \
-e 's|<sect. id=|<section xml:id=|' \
-e 's|</sect[0-9]>|</section>|' \
-e '1s| id=| xml:id=|' \
-e '1s|\(<[^ ]* \)|\1${extraHeader}|'
} > '${outputFile}'
'';
in
''
ln -s '${sources}/'*.xml .
mkdir ./languages-frameworks
cp -s '${sources-langs}'/* ./languages-frameworks
''
+ toDocbook {
inputFile = ./haskell-users-guide.md;
outputFile = "haskell-users-guide.xml";
useChapters = true;
}
+ toDocbook {
inputFile = ./../pkgs/development/idris-modules/README.md;
outputFile = "languages-frameworks/idris.xml";
}
+ ''
cat languages-frameworks/idris.xml
echo ${nixpkgsVersion} > .version
xmllint --noout --nonet --xinclude --noxincludenode \

View file

@ -3,8 +3,10 @@ title: User's Guide for Haskell in Nixpkgs
author: Peter Simons
date: 2015-06-01
---
# User's Guide to the Haskell Infrastructure
# How to install Haskell packages
## How to install Haskell packages
Nixpkgs distributes build instructions for all Haskell packages registered on
[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
@ -111,9 +113,9 @@ version of GHC listed above, there exists a package set based on that compiler.
Also, the attributes `haskell.compiler.ghcXYC` and
`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
# How to create a development environment
## How to create a development environment
## How to install a compiler
### How to install a compiler
A simple development environment consists of a Haskell compiler and the tool
`cabal-install`, and we saw in section [How to install Haskell packages] how
@ -162,7 +164,7 @@ anymore once `nix-shell` has terminated. If you find that your Haskell builds
no longer work after garbage collection, then you'll have to re-run `cabal
configure` inside of a new `nix-shell` environment.
## How to install a compiler with libraries
### How to install a compiler with libraries
GHC expects to find all installed libraries inside of its own `lib` directory.
This approach works fine on traditional Unix systems, but it doesn't work for
@ -257,7 +259,7 @@ environment in your profile:
export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
fi
## How to install a compiler with libraries, hoogle and documentation indexes
### How to install a compiler with libraries, hoogle and documentation indexes
If you plan to use your environment for interactive programming, not just
compiling random Haskell code, you might want to replace `ghcWithPackages` in
@ -319,7 +321,7 @@ page](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) for
workarounds.
## How to create ad hoc environments for `nix-shell`
### How to create ad hoc environments for `nix-shell`
The easiest way to create an ad hoc development environment is to run
`nix-shell` with the appropriate GHC environment given on the command-line:
@ -369,14 +371,14 @@ development commands. Note that you need `cabal-install` installed in your
`$PATH` already to use it here --- the `nix-shell` environment does not provide
it.
# How to create Nix builds for your own private Haskell packages
## How to create Nix builds for your own private Haskell packages
If your own Haskell packages have build instructions for Cabal, then you can
convert those automatically into build instructions for Nix using the
`cabal2nix` utility, which you can install into your profile by running
`nix-env -i cabal2nix`.
## How to build a stand-alone project
### How to build a stand-alone project
For example, let's assume that you're working on a private project called
`foo`. To generate a Nix build expression for it, change into the project's
@ -433,7 +435,7 @@ You can even use that generated file to run `nix-build`, too:
$ nix-build shell.nix
## How to build projects that depend on each other
### How to build projects that depend on each other
If you have multiple private Haskell packages that depend on each other, then
you'll have to register those packages in the Nixpkgs set to make them visible
@ -468,9 +470,9 @@ or enter an interactive shell environment suitable for building them:
$ nix-shell "<nixpkgs>" -A haskellPackages.bar.env
# Miscellaneous Topics
## Miscellaneous Topics
## How to build with profiling enabled
### How to build with profiling enabled
Every Haskell package set takes a function called `overrides` that you can use
to manipulate the package as much as you please. One useful application of this
@ -494,7 +496,7 @@ following snippet in your `~/.nixpkgs/config.nix` file:
Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
## How to override package versions in a compiler-specific package set
### How to override package versions in a compiler-specific package set
Nixpkgs provides the latest version of
[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
@ -560,7 +562,7 @@ prefer one built with GHC 7.8.x in the first place. However, for users who
cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
older version might be useful.
## How to recover from GHC's infamous non-deterministic library ID bug
### How to recover from GHC's infamous non-deterministic library ID bug
GHC and distributed build farms don't get along well:
@ -586,7 +588,7 @@ command, i.e. by running:
rm /nix/var/nix/manifests/*
rm /nix/var/nix/channel-cache/*
## Builds on Darwin fail with `math.h` not found
### Builds on Darwin fail with `math.h` not found
Users of GHC on Darwin have occasionally reported that builds fail, because the
compiler complains about a missing include file:
@ -603,7 +605,7 @@ can configure the environment variables
in their `~/.bashrc` file to avoid the compiler error.
## Using Stack together with Nix
### Using Stack together with Nix
-- While building package zlib-0.5.4.2 using:
runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
@ -666,7 +668,7 @@ to find out the store path of the system's zlib library. Now, you can
The same thing applies to `cabal configure`, of course, if you're
building with `cabal-install` instead of Stack.
## Creating statically linked binaries
### Creating statically linked binaries
There are two levels of static linking. The first option is to configure the
build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
@ -688,7 +690,7 @@ as shared libraries only, i.e. there is just no static library available that
Cabal could link!
# Other resources
## Other resources
- The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
provides an introduction into Haskell NG aimed at beginners. The slides are

View file

@ -20,6 +20,7 @@ such as Perl or Haskell. These are described in this chapter.</para>
<xi:include href="java.xml" />
<xi:include href="lua.xml" />
<xi:include href="coq.xml" />
<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md -->
<xi:include href="qt.xml" />