stack2nix-0.2.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)
[![Hackage](https://img.shields.io/hackage/v/stack2nix.svg)](https://hackage.haskell.org/package/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 two 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 + Nix

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

## 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.