2a5ac194b5
Since we are giving basics without much explanation, we should direct people to the main source of information & learning on the topic at hand.
9.3 KiB
hnix
Parser, evaluator and type checker for the Nix language written in Haskell.
Contents
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: Current derivationStrict primOp implementation and so every evaluation of a derivation into a store path currently relies 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.
Getting Started
# Note: --recursive
git clone --recursive 'https://github.com/haskell-nix/hnix.git'
cd hnix
Cachix prebuild binary caches
If you opt in to use of Nix environment, please enable the official HNix Cachix binary cache:
-
Go through https://cachix.org/ and set it up.
-
Run:
cachix use hnix
Using Cabal
Cabal Quickstart.
- (Optional), to enter the projects reproducible Nix environment:
nix-shell
- Building:
cabal v2-configure
cabal v2-build
- Loading the project into
ghciREPL:
cabal v2-repl
- 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-configure --enable-tests --enable-profiling --flags=profiling
cabal v2-run hnix -- <args> +RTS -p
where "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.
Run HNix
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
Run HNix
./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 -E "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
Ot enter REPL:
hnix --repl
Evaluate an expression and load it into REPL:
hnix --eval -E '(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
There is a Wiki article: Design of the HNix code base.
Haskell Language Server & Cabal development. Or development in the Nix shell environment.
-
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.
-
You are free to chat with everyone on Gitter.
-
When the pull request is ready to be submitted, to save time - please, test it with:
git submodule update --init --recursive
cabal v2-test
Please, check that all default tests that were passing prior are still passing for the PR, it is faster to check that locally than through CI. It's OK if no new tests are passing.
(optional) Minimalistic development status loop with amazing ghcid
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 and Project status.