HNix

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

Contents

• Prerequisites
• Getting Started
  • Git clone
  • (optional) Cachix prebuild binary caches
  • Using Cabal
    • Checking the project
      • Benchmarks
      • Profiling
      • Full debug info
    • Runing executable
  • Using Nix-build
    • Checking the project
      • Benchmarks
      • Profiling
      • Full debug info
    • Runing executable
• Using HNix
  • Parse & print
  • Evaluating and printing the resulting value
  • Evaluating Nixpkgs
  • Options supported only by HNix
  • REPL
    • Language laziness
• Contributing
  • (optional) Minimalistic development status loop with amazing ghcid
• Current status

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.

Disclaimer: Since still using Nix for some operations, current derivationStrict primOp implementation and so evaluations of a derivation into a store path currently rely on the hnix-store-remote, which for those operations relies on the running nix-daemon, and so operations use/produce effects into the /nix/store. Be cautious - it is effectful (produces /nix/store entries).

Getting Started

Git clone

git clone --recursive 'https://github.com/haskell-nix/hnix.git' && cd hnix

(optional) Cachix prebuild binary caches

If you would use our Nix-shell environment for development, you can connect to our Cachix HNix build caches:

1. Run:

   nix-env -iA cachix -f https://cachix.org/api/v1/install

2. Run: cachix use hnix

Using Cabal

Cabal Quickstart.

1. (Optional), to enter the projects reproducible Nix environment:

   nix-shell

2. Building:

   cabal v2-configure
   cabal v2-build

3. Loading the project into ghci REPL:

   cabal v2-repl

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

Checking the project

Benchmarks

To run benchmarks:

cabal v2-bench

Profiling

GHC User Manual has a full "Profiling" section of relevant info.

To build hnix with profiling enabled:

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

Or to put simply:

# Run profiling for evaluation of a Firefox package.
# Generate:
#  * for all functions
#  * time profiling data
#  * memory allocation profiling data
#  * in the JSON profiling format
cabal v2-run --enable-profiling --flags=profiling --enable-library-profiling --profiling-detail='all-functions' hnix -- --eval --expr '(import <nixpkgs> {}).firefox.outPath' +RTS -Pj

# Then, upload the `hnix.prof` to the https://www.speedscope.app/ to analyze it.

"RTS" stands for "RunTime System" and has a lot of options, GHC User Manual has "Running a compiled program"/"Setting RTS options" sections describing them.

Full debug info

To run stack traces & full tracing output on hnix:

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

This would give the most information as to what happens during parsing & evaluation.

Runing executable

cabal v2-run hnix -- --help

(-- is for separation between cabal & hnix args)

Using Nix-build

There is a number of build options to use with nix-build, documentation of them is in: ./default.nix, keys essentially pass-through the Nixpkgs Haskell Lib API.

Options can be used as:

nix-build \
  --arg <option1> <argument1> \
  --arg <option2> <argument2> \
  --argstr <option3> "<strinTypeArg>"

Checking the project

Benchmarks

nix-build \
  --arg disableOptimization false \
  --arg enableDeadCodeElimination true \
  --arg doStrip true \
  --arg doBenchmark true

Profiling

nix-build \
  --arg disableOptimization false \
  --arg enableDeadCodeElimination true \
  --arg enableLibraryProfiling true \
  --arg enableExecutableProfiling true

./result/bin/hnix <args> +RTS -p

Full debug info

nix-build \
  --arg disableOptimization false \
  --arg enableDeadCodeElimination true \
  --arg doBenchmark true \
  --arg doStrip false \
  --arg enableLibraryProfiling true \
  --arg enableExecutableProfiling true \
  --arg doTracing true \
  --arg enableDWARFDebugging true

./result/bin/hnix -v5 --trace <args> +RTS -xc

Runing executable

./result/bin/hnix

Using HNix

See:

hnix --help

It has a pretty full/good description of the current options.

Parse & print

To parse a file with hnix and pretty print the result:

hnix file.nix

Evaluating and printing the resulting value

Expression from a file:

hnix --eval file.nix

Expression:

hnix --eval --expr 'import <nixpkgs> {}'

Evaluating Nixpkgs

Currently, the main high-level goal is to be able to evaluate all of Nixpkgs:

hnix --eval --expr "import <nixpkgs> {}" --find

Options supported only by HNix

To see value provenance and thunk context:

hnix -v2 --values --thunk --eval --expr 'import <nixpkgs> {}'

To see tracing as the evaluator runs (note that building with cabal configure --flags=tracing will produce much more output than this):

hnix --trace --eval --expr 'import <nixpkgs> {}'

To attempt to generate a reduced test case demonstrating an error:

hnix --reduce bug.nix --eval --expr 'import <nixpkgs> {}'

REPL

To enter REPL:

hnix --repl

Evaluate an expression and load it into REPL:

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

This binds the evaluated expression result to the input variable, so that variable can be inspected.

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

Language laziness

Nix is a lazy language with the ability of recursion, so by default REPL and eval prints are lazy:

hnix \
  --eval \
  --expr '{ x = true; }'
  
{ x = "<expr>"; }

To disable laziness add the --strict to commands or :set strict in the REPL.

hnix \
  --eval \
  --strict \
  --expr '{ x = true; }'
  
{ x = true; }

Contributing

• The Haskell Language Server (HLS) works great with our project.

• Design of the HNix code base Wiki article.

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 the pull request is ready to be submitted, to save time - please, test it with:

   cabal v2-test
   
   # If forgot to clone recursively, run:
   # git submodule update --init --recursive

   Please, check that all default tests that were passing prior are still passing. It's OK if no new tests are passing.

(optional) Minimalistic development status loop with amazing ghcid

If HLS is not your cup of yea:

ghcid --command="cabal v2-repl --repl-options=-fno-code --repl-options=-fno-break-on-exception --repl-options=-fno-break-on-error --repl-options=-v1 --repl-options=-ferror-spans --repl-options=-j"

(optional) To use projects reproducible environment, wrap ghcid ... command into a nix-shell --command ' '.

For simplicity alias the command in your shell.

Current status

To understand the project implementation state see:

• ChangeLog
• Opened reports
• Project status
• Design of the HNix code base