forked from mirrors/nixpkgs
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
parent
810695216a
commit
3e4035695c
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" />
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue