stack2nix-0.2: README.md

# stack2nix

[![Build Status](https://travis-ci.org/input-output-hk/stack2nix.svg?branch=master)](https://travis-ci.org/input-output-hk/stack2nix)

## About

`stack2nix` automates conversion from [Stack](https://docs.haskellstack.org/en/stable/README/) configuration file to [Nix](http://nixos.org/nix/) expressions. The purpose is to map stack.yaml one-to-one into Nix expressions.

`stack2nix` high-level workflow:

- Generate stackage snapshot to determine complete fixed version list of packages based on resolver
- apply any additional configuration (local packages, extra dependencies, etc) from `stack.yaml`
- generate complete list of dependencies to Nix expressions, replacing upstream `hackage-packages.nix`

## Installation

There are three options. The first - using Nix is recommended. If there are difficulties please file an issue.

## Nix (recommended)

1. Install [Nix](https://nixos.org/nix/).
2. Clone this repo.
3. Run `nix-build` to build.

### Stack

1. Install [Nix](https://nixos.org/nix/).
2. Clone this repo.
3. Run `stack install --nix` to install.

### Virtual Machine

1. Install [VirtualBox](https://www.virtualbox.org/wiki/VirtualBox) and [Vagrant](https://www.vagrantup.com/).
2. Clone this repo.
3. Run `./scripts/vagrant.sh` and take a coffee break.
4. If there are no errors, log into the VM: `vagrant ssh`.

## Usage

Nix expressions generated by stack2nix require NixOS 17.09 or later.

### Local Packages

Sometimes it's convenient to build local Haskell packages. Assuming the current directory is a locally maintained fork of Pandoc:

```
    $ stack2nix . > default.nix
    $ nix-build -A pandoc
```

### Remote Packages

Stack2nix can generate a nix expressions for Haskell packages hosted in git repositories.

```
    $ stack2nix --revision 242e2a064f6a32b22e1599bbfe72e64d7b6203b8 https://github.com/jgm/pandoc.git > demo.nix
    $ nix-build -A pandoc demo.nix
```

## Testing

Run `./scripts/travis.sh` to build and test.