@@ -266,7 +266,7 @@ The easiest way to create an ad hoc development environment is to run
267 nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
267 nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
269−For more sophisticated use-cases, however, it's probably nicer to save the
269+For more sophisticated use-cases, however, it's more convenient to save the
270desired configuration in a file called `shell.nix` that looks like this:
270desired configuration in a file called `shell.nix` that looks like this:
272 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
272 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
@@ -309,54 +309,83 @@ development commands. Note that you need `cabal-install` installed in your
309`$PATH` already to use it here --- the `nix-shell` environment does not provide
309`$PATH` already to use it here --- the `nix-shell` environment does not provide
312−# Adding support for your own packages
312+# How to create Nix builds for your own private Haskell packages
314−## For `nix-shell`
314+If your own Haskell packages have build instructions for Cabal, then you can
315+convert those automatically into build instructions for Nix using the
316+`cabal2nix` utility, which you can install into your profile by running
317+`nix-env -i cabal2nix`.
319+## How to build a stand-alone project
321+For example, let's assume that you're working on a private project called
322+`foo`. To generate a Nix build expression for it, change into the project's
323+top-level directory and run the command:
316− $ nix-env -f "<nixpkgs>" -iA cabal2nix
325+ $ cabal2nix . >foo.nix
327+Then write the following snippet into a file called `default.nix`:
329+ { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
330+ nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
332+Finally, store the following code in a file called `shell.nix`:
334+ { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7101" }:
335+ (import ./default.nix { inherit nixpkgs compiler; }).env
337+At this point, you can run `nix-build` to have Nix compile your project and
338+install it into a Nix store path. The local directory will contain a symlink
339+called `result` after `nix-build` returns that points into that location. Of
340+course, passing the flag `--argstr compiler ghc763` allows switching the build
341+to any version of GHC currently supported.
343+Furthermore, you can call `nix-shell` to enter an interactive development
344+environment in which you can use `cabal configure` and `cabal build` to develop
345+your code. That environment will automatically contain a proper GHC derivation
346+with all the required libraries registered as well as all the system-level
347+libraries your package might need.
349+If your package does not depend on any system-level libraries, then it's
318− $ cabal2nix --shell . >shell.nix
319 $ nix-shell --command "cabal configure"
352 $ nix-shell --command "cabal configure"
321− $ cabal build
354+once to set up your build. `cabal-install` determines the absolute paths to all
322− [...]
355+resources required for the build and writes them into a config file in the
323−
356+`dist/` directory. Once that's done, you can run `cabal build` and any other
324− $ cabal2nix --shell .
357+command for that project even outside of the `nix-shell` environment. This
325− with (import <nixpkgs> {}).pkgs;
358+feature is particularly nice for those of us who like to edit their code with
326− let pkg = haskellPackages.callPackage
359+an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
327− ({ mkDerivation, base, stdenv, transformers }:
360+inside of nix-shell just to make it find out the necessary settings for
328− mkDerivation {
361+building the project; `cabal-install` has already done that for us.
332− buildDepends = [ base transformers ];
333− homepage = "http://github.com/ekmett/mtl";
334− license = stdenv.lib.licenses.bsd3;
339− $ cd ~/src/foo
363+If you want to do some quick-and-dirty hacking and don't want to bother setting
340− $ cabal2nix . > default.nix
364+up a `default.nix` and `shell.nix` file manually, then you can use the
365+`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
366+`nix-shell` environment for you. With that feature, running
342−Now edit `~/.nixpkgs/config.nix`:
368+ $ cabal2nix --shell . >shell.nix
369+ $ nix-shell --command "cabal configure"
344− {
371+is usually enough to set up a build environment for any given Haskell package.
345− packageOverrides = super: let self = super.pkgs; in
372+You can even use that generated file to run `nix-build`, too:
347− foo = self.haskellPackages.callPackage
374+ $ nix-build shell.nix
352−Build it by running "`nix-env -f "<nixpkgs>" -iA foo`".
376+## How to build projects that depend on each other
354−## For `nix-build`
378+If you have multiple private Haskell packages that depend on each other, then
379+you'll have to register those packages in the Nixpkgs set to make them visible
380+for the dependency resolution performed by `callPackage`. First of all, change
381+into each of your projects top-level directories and generate a `default.nix`
382+file with `cabal2nix`:
356−# Create builds for your own packages
384+ $ cd ~/src/foo && cabal2nix . >default.nix
385+ $ cd ~/src/bar && cabal2nix . >default.nix
358−Use this `~/.nixpkgs/config.nix` file to register the build inside of
387+Then edit your `~/.nixpkgs/config.nix` file to register those builds in the
359−`haskellPackages`, so that other libraries may depend on it:
388+default Haskell package set:
362 packageOverrides = super: let self = super.pkgs; in
391 packageOverrides = super: let self = super.pkgs; in
@@ -370,12 +399,43 @@ Use this `~/.nixpkgs/config.nix` file to register the build inside of
402+Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will
403+show your packages like any other package from Hackage, and you can build them
405+ $ nix-build "<nixpkgs>" -A haskellPackages.foo
407+or enter an interactive shell environment suitable for building them:
409+ $ nix-shell "<nixpkgs>" -A haskellPackages.bar.env
411+# Miscellaneous Topics
413+## How to build with profiling enabled
415+Every Haskell package set takes a function called `overrides` that you can use
416+to manipulate the package as much as you please. One useful application of this
417+feature is to replace the default `mkDerivation` function with one that enables
418+library profiling for all packages. To accomplish that, add configure the
419+following snippet in your `~/.nixpkgs/config.nix` file:
422+ packageOverrides = super: let self = super.pkgs; in
424+ profiledHaskellPackages = self.haskellPackages.override {
425+ overrides = self: super: {
426+ mkDerivation = args: super.mkDerivation (args // {
427+ enableLibraryProfiling = true;
373−## GHC's infamous non-deterministic library ID bug
434+## How to recover from GHC's infamous non-deterministic library ID bug
375GHC and distributed build farms don't get along well:
436GHC and distributed build farms don't get along well:
377 https://ghc.haskell.org/trac/ghc/ticket/4012
438 https://ghc.haskell.org/trac/ghc/ticket/4012
378− https://github.com/NixOS/nixpkgs/issues/7792
380When you see an error like this one
440When you see an error like this one