mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-09-29 07:32:58 +00:00
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:
parent
810695216a
commit
3e4035695c
@ -20,27 +20,39 @@ stdenv.mkDerivation {
|
|||||||
--param callout.graphics.extension '.gif'
|
--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 .
|
ln -s '${sources}/'*.xml .
|
||||||
mkdir ./languages-frameworks
|
mkdir ./languages-frameworks
|
||||||
cp -s '${sources-langs}'/* ./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
|
echo ${nixpkgsVersion} > .version
|
||||||
|
|
||||||
xmllint --noout --nonet --xinclude --noxincludenode \
|
xmllint --noout --nonet --xinclude --noxincludenode \
|
||||||
|
@ -3,8 +3,10 @@ title: User's Guide for Haskell in Nixpkgs
|
|||||||
author: Peter Simons
|
author: Peter Simons
|
||||||
date: 2015-06-01
|
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
|
Nixpkgs distributes build instructions for all Haskell packages registered on
|
||||||
[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
|
[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
|
Also, the attributes `haskell.compiler.ghcXYC` and
|
||||||
`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
|
`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
|
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
|
`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
|
no longer work after garbage collection, then you'll have to re-run `cabal
|
||||||
configure` inside of a new `nix-shell` environment.
|
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.
|
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
|
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)"
|
export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
|
||||||
fi
|
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
|
If you plan to use your environment for interactive programming, not just
|
||||||
compiling random Haskell code, you might want to replace `ghcWithPackages` in
|
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.
|
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
|
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:
|
`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
|
`$PATH` already to use it here --- the `nix-shell` environment does not provide
|
||||||
it.
|
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
|
If your own Haskell packages have build instructions for Cabal, then you can
|
||||||
convert those automatically into build instructions for Nix using the
|
convert those automatically into build instructions for Nix using the
|
||||||
`cabal2nix` utility, which you can install into your profile by running
|
`cabal2nix` utility, which you can install into your profile by running
|
||||||
`nix-env -i cabal2nix`.
|
`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
|
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
|
`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
|
$ 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
|
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
|
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
|
$ 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
|
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
|
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
|
Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
|
||||||
`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
|
`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
|
Nixpkgs provides the latest version of
|
||||||
[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
|
[`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
|
cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
|
||||||
older version might be useful.
|
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:
|
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/manifests/*
|
||||||
rm /nix/var/nix/channel-cache/*
|
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
|
Users of GHC on Darwin have occasionally reported that builds fail, because the
|
||||||
compiler complains about a missing include file:
|
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.
|
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:
|
-- While building package zlib-0.5.4.2 using:
|
||||||
runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
|
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
|
The same thing applies to `cabal configure`, of course, if you're
|
||||||
building with `cabal-install` instead of Stack.
|
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
|
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,
|
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!
|
Cabal could link!
|
||||||
|
|
||||||
|
|
||||||
# Other resources
|
## Other resources
|
||||||
|
|
||||||
- The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
|
- 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
|
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="java.xml" />
|
||||||
<xi:include href="lua.xml" />
|
<xi:include href="lua.xml" />
|
||||||
<xi:include href="coq.xml" />
|
<xi:include href="coq.xml" />
|
||||||
|
<xi:include href="idris.xml" /> <!-- generated from ../../pkgs/development/idris-modules/README.md -->
|
||||||
<xi:include href="qt.xml" />
|
<xi:include href="qt.xml" />
|
||||||
|
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user