Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@hamishmack
hamishmack committed Nov 19, 2020
1 parent f2f1815 commit e3f0899
Show file tree
Hide file tree
Showing 3 changed files with 103 additions and 40 deletions.
5 changes: 3 additions & 2 deletions docs/reference/library.md
View file
Expand Up @@ -167,7 +167,7 @@ Then feeding its result into [mkCabalProjectPkgSet](#mkcabalprojectpkgset) passi
| `shellFor` | Function | [`shellFor`](#shellfor) |
| `ghcWithHoogle` | Function | [`ghcWithHoogle`](#ghcwithhoogle) |
| `ghcWithPackages` | Function | [`ghcWithPackages`](#ghcwithpackages) |

| `cross` | Attrset | Like `pkgs.pkgsCross.X` from nixpkgs `cross.X` returns the project results for cross compilation to X. So `cross.ghcjs.hsPkgs` is the same as `hsPkgs` but compiled with ghcjs |


## mkStackPkgSet
Expand Down Expand Up @@ -427,7 +427,8 @@ shellFor =
| `additional` | Function | Similar to `packages`, but the selected packages are built and included in `ghc-pkg list` (not just their dependencies). |
| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
| `exactDeps` | Boolean | Prevents the Cabal solver from choosing any package dependency other than what are in the package set. |
| `tools` | Function | AttrSet of tools to make available e.g. `{ cabal = "3.2.0.0"; }` or `{ cabal = { version = "3.2.0.0"; }; }`. If an AttrSet is provided for a tool, the additional arguments will be passed to the function creating the derivation for that tool. So you can provide an `index-state` or a `materialized` argument like that `{ cabal = { version = "3.2.0.0"; index-state = "2020-10-30T00:00:00Z"; materialized = ./cabal.materialized; }; }` for example. You can specify and materialize the version of hoogle used to construct the hoogle index by including something like `{ hoogle = { version = "5.0.17.15"; index-state = "2020-05-31T00:00:00Z"; materialized = ./hoogle.materialized; }`. Uses a default version of hoogle if omitted. |
| `tools` | Attrset | Tools to make available e.g. `{ cabal = "3.2.0.0"; }` or `{ cabal = { version = "3.2.0.0"; }; }`. If an AttrSet is provided for a tool, the additional arguments will be passed to the function creating the derivation for that tool. So you can provide an `index-state` or a `materialized` argument like that `{ cabal = { version = "3.2.0.0"; index-state = "2020-10-30T00:00:00Z"; materialized = ./cabal.materialized; }; }` for example. You can specify and materialize the version of hoogle used to construct the hoogle index by including something like `{ hoogle = { version = "5.0.17.15"; index-state = "2020-05-31T00:00:00Z"; materialized = ./hoogle.materialized; }`. Uses a default version of hoogle if omitted. |
| `cross` | Function | Platform selection function for cross compilation targets to support eg. `p: with p; [ghcjs mingwW64]`. |
| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |

**Return value**: a derivation
Expand Down
36 changes: 22 additions & 14 deletions docs/tutorials/development.md
View file
Expand Up @@ -34,13 +34,14 @@ themselves. This is what the [`shellFor`][shellFor] function does.

```nix
# shell.nix
{ pkgs ? import <nixpkgs> {} }:
let
hsPkgs = import ./default.nix { inherit pkgs; };
project = import ./default.nix;
in
hsPkgs.shellFor {
# Include only the *local* packages of your project.
project.shellFor {
# ALL of these arguments are optional.
# List of packages from the project you want to work on in
# the shell (default is all the projects local packages).
packages = ps: with ps; [
pkga
pkgb
Expand All @@ -50,15 +51,22 @@ in
# and provides a "hoogle" command to search the index.
withHoogle = true;
# You might want some extra tools in the shell (optional).
# Some common tools can be added with the `tools` argument
tools = { cabal = "3.2.0.0"; hlint = "2.2.11"; };
tools = {
cabal = "3.2.0.0";
hlint = "3.2.2";
haskell-language-server = "0.5.1";
};
# See overlays/tools.nix for more details
# Some you may need to get some other way.
buildInputs = with pkgs.haskellPackages;
[ ghcid ];
buildInputs = [ (import <nixpkgs> {}).git ];
# Sellect cross compilers to include.
cross = pkgsCross: with pkgsCross; [
ghcjs # Adds support for `js-unknown-ghcjs-cabal build` in the shell
# mingwW64 # Adds support for `x86_64-W64-mingw32-cabal build` in the shell
];
# Prevents cabal from choosing alternate plans, so that
# *all* dependencies are provided by Nix.
Expand All @@ -77,15 +85,15 @@ If you need a local Hoogle for all the dependencies of your project create this
```nix
# shell-hoogle.nix
let
hsPkgs = import ./default.nix {};
project = import ./default.nix {};
in
hsPkgs.shellFor {
project.shellFor {
packages = ps: [ps.my-package];
withHoogle = true;
}
```

and run `nix-shell shell-hoogle.nix --run "hoogle server --local"`.
and run `nix-shell shell-hoogle.nix --run "hoogle server --local"`.
This will open a local Hoogle server at `http://127.0.0.1:8080`.


Expand All @@ -100,7 +108,7 @@ selects packages from the larger package set.
# shell.nix
let
haskellNix = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {};
nixpkgs = import haskellNix.sources.nixpkgs-1909 haskellNix.nixpkgsArgs;
nixpkgs = import haskellNix.sources.nixpkgs-2003 haskellNix.nixpkgsArgs;
haskell = nixpkgs.haskell-nix;
in
haskell.haskellPackages.ghcWithPackages (ps: with ps;
Expand Down
102 changes: 78 additions & 24 deletions docs/tutorials/getting-started.md
View file
Expand Up @@ -23,6 +23,24 @@ substituters = [...] https://hydra.iohk.io [...]

This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../reference/troubleshooting#why-am-i-building-ghc).

## Niv

[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.

After installing niv you can initialize niv and pin the latest haskell.nix
commit by running the following in the root directory of the project:

```
niv init
niv add input-output-hk/haskell.nix -n haskellNix
```

Then when you want to update to the latest version of haskellNix use:

```
niv update haskellNix
```

## Scaffolding

The following work with `stack.yaml` and `cabal.project` based
Expand All @@ -31,28 +49,35 @@ projects.
Add `default.nix`:

```nix
{ # Fetch the latest haskell.nix and import its default.nix
haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
# haskell.nix provides access to the nixpkgs pins which are used by our CI,
# hence you will be more likely to get cache hits when using these.
# But you can also just use your own, e.g. '<nixpkgs>'.
, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
# haskell.nix provides some arguments to be passed to nixpkgs, including some
# patches and also the haskell.nix functionality itself as an overlay.
, nixpkgsArgs ? haskellNix.nixpkgsArgs
# import nixpkgs with overlays
, pkgs ? import nixpkgsSrc nixpkgsArgs
}: pkgs.haskell-nix.project {
let
# Read in the Niv sources
sources = import ./nix/sources.nix {};
# If ./nix/sources.nix file is not found run:
# niv init
# niv add input-output-hk/haskell.nix -n haskellNix
# Fetch the haskell.nix commit we have pinned with Niv
haskellNix = import sources.haskellNix {};
# If haskellNix is not found run:
# niv add input-output-hk/haskell.nix -n haskellNix
# Import nixpkgs and pass the haskell.nix provided nixpkgsArgs
pkgs = import
# haskell.nix provides access to the nixpkgs pins which are used by our CI,
# hence you will be more likely to get cache hits when using these.
# But you can also just use your own, e.g. '<nixpkgs>'.
haskellNix.sources.nixpkgs-2003
# These arguments passed to nixpkgs, include some patches and also
# the haskell.nix functionality itself as an overlay.
haskellNix.nixpkgsArgs;
in pkgs.haskell-nix.project {
# 'cleanGit' cleans a source directory based on the files known by git
src = pkgs.haskell-nix.haskellLib.cleanGit {
name = "haskell-nix-project";
src = ./.;
};
# Specify the GHC version to use.
compiler-nix-name = "ghc8102"; # Not required for `stack.yaml` based projects.
compiler-nix-name = "ghc884"; # Not required for `stack.yaml` based projects.
}
```

Expand All @@ -77,20 +102,49 @@ To build an executable:
nix-build -A your-package-name.components.exes.your-exe-name
```

To open a shell for use with `cabal` run:
To cross compile use the `cross` attribute:

```
nix-build -A cross.ghcjs.hsPkgs.your-package-name.components.exes.your-exe-name
nix-build -A cross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name
```

To open a shell for use with `cabal`, `hlint` and `haskell-language-server` add `shell.nix`:

```nix
(import ./default.nix).shellFor {
tools = {
cabal = "3.2.0.0";
hlint = "3.2.2";
haskell-language-server = "0.5.1";
};
}
```

Then run:

```shell
nix-shell -A shellFor
nix-shell
cabal new-repl your-package-name:library:your-package-name
cabal new-build your-package-name
```

To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).

## Using haskell.nix without niv

If you would prefer not to use niv you can replace
`sources = import ./nix/sources.nix {};` in the examples with:

```
sources = {
haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz";
};
```

### Pinning the [haskell.nix][] version

For simplicity's sake we will use `fetchTarball` for the examples in
this documentation. This will always get the latest version, and is
The `fetchTarball` call above will always get the latest version, and is
similar to an auto-updating Nix channel.

However, in your own project, you may wish to pin [haskell.nix][] (as
Expand All @@ -100,10 +154,10 @@ predictable, and faster (because the fixed version is cached).
Straightforward way of doing this is to change the branch name to a revision.

```nix
{ # Fetch a specific haskell.nix and import its default.nix
haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
...
# Fetch a specific haskell.nix and import its default.nix
sources = {
haskellNix = import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {};
};
```

There are other possible schemes for pinning. See
Expand Down

0 comments on commit e3f0899

Please sign in to comment.