hnix/README.md

hnix

Parser, evaluator and type checker for the Nix language written in Haskell.

Contents

• Prerequisites
• Getting Started
• Using the REPL
• Cachix prebuild binary caches
• Building
  • With benchmarks
  • With profiling
  • With full debug info
• Contributing
  • Evaluating Nixpkgs with HNix

Prerequisites

Tooling is WIP, nix-shell and nix-store are still used for their purpose, so, to access them Nix is required to be installed.

Getting Started

# Note: --recursive
git clone --recursive https://github.com/haskell-nix/hnix.git
cd hnix

Development using Cabal

1. (Optional), to enter and work in the reproducible Nix environemt:

nix-shell

Nix environment currenly defaults to the GHC 8.8, which is the default in Nixpkgs, drawback of it - compilation of hnix executable is enabled only for GHC 8.10.

2. Building:

cabal v2-configure
cabal v2-build

3. Testing:

• Default suite:

cabal v2-test

• All available tests:

env ALL_TESTS=yes cabal v2-test

• Selected (list of tests is in tests/Main.hs):

env NIXPKGS_TESTS=yes PRETTY_TESTS=1 cabal v2-test

Run built binary with Cabal (-- is for separation between cabal & hnix args):

cabal v2-run hnix -- --help

Using the REPL

Enter REPL:

hnix --repl

To evaluate an expression and make it available in the REPL as the input variable use:

hnix --eval -E '(import <nixpkgs> {}).pkgs.hello' --repl

Use the :help command for a list of all available REPL commands.

Cachix prebuild binary caches

To autoload prebuild project dependencies - please, enable the official HNix Cachix binary cache:

1. Go through https://cachix.org/ and set it up.

2. Run: cachix use hnix

Building

With benchmarks

To run benchmarks:

cabal v2-bench

With profiling

To build hnix with profiling enabled:

cabal v2-configure --enable-tests --enable-profiling --flags=profiling
cabal v2-run hnix -- <args> +RTS -p

With full debug info

To build hnix for debugging, with full tracing output and stack traces:

cabal v2-configure --enable-tests --enable-profiling --flags=profiling --flags=tracing
cabal v2-run hnix -- -v5 --trace <args> +RTS -xc

Note that this will run quite slowly, but will give the most information as to what might potentially be going wrong during parsing or evaluation.

Contributing

1. If something in the quests looks interesting, look through the thread and leave a comment taking it, to let others know you're working on it.

2. You are free to chat with everyone on Gitter.

3. When pull request is ready to be submitted, to save time - please, test it with:

git submodule update --init --recursive
nix-shell --run "LANGUAGE_TESTS=yes cabal v2-test"

Please, check that all tests that were passing prior (most probably all tests mentioned in the command) are still passing for the PR, it is faster to chech that locally then through CI. It's OK if no new tests are passing.

Evaluating Nixpkgs with HNix

Currently the main high-level goal is to be able to evaluate all of Nixpkgs. To run this yourself, first build hnix with nix-build, then run the following command:

./result/bin/hnix --eval -E "import <nixpkgs> {}" --find