2020-09-29 18:42:00 +03:00
[![Chatroom Gitter ](https://img.shields.io/badge/Chatroom-Gitter-%23753a88 )](https://gitter.im/haskell-nix/Lobby)
[![Hackage ](https://img.shields.io/hackage/v/hnix?color=%235e5086&label=Latest%20release%20on%20Hackage )](https://hackage.haskell.org/package/hnix)
[![Hackage Matrix Builder ](https://img.shields.io/badge/Hackage%20Matrix-Builder-%235e5086 )](https://matrix.hackage.haskell.org/package/hnix)
[![Bounds ](https://img.shields.io/hackage-deps/v/hnix?label=Released%20dep%20bounds )](https://packdeps.haskellers.com/feed?needle=hnix)
[![Hydra CI ](https://img.shields.io/badge/Nixpkgs%20Hydra-CI-%234f72bb )](https://hydra.nixos.org/job/nixpkgs/trunk/haskellPackages.hnix.x86_64-linux#tabs-status)
[![Repology page ](https://img.shields.io/badge/Repology-page-%23005500 )](https://repology.org/project/haskell:hnix/versions)
2016-02-08 02:53:22 +03:00
# hnix
2020-09-30 16:29:22 +03:00
Parser, evaluator and type checker for the Nix language written in Haskell.
2020-09-29 16:55:00 +03:00
2020-09-29 18:42:00 +03:00
2020-09-29 17:48:45 +03:00
## Contents
2020-09-29 16:55:00 +03:00
<!-- TOC generates automatically, do not bother editing any further TOC text -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
2020-09-29 17:57:39 +03:00
<!-- DON'T EDIT THIS SECTION, INSTEAD RE - RUN doctoc TO UPDATE -->
- [Prerequisites ](#prerequisites )
- [Getting Started ](#getting-started )
2020-09-30 17:27:27 +03:00
- [Cachix prebuild binary caches ](#cachix-prebuild-binary-caches )
2021-01-14 16:13:47 +03:00
- [Using Cabal ](#using-cabal )
- [Checking the project ](#checking-the-project )
- [Benchmarks ](#benchmarks )
- [Profiling ](#profiling )
- [Full debug info ](#full-debug-info )
2020-09-30 18:29:38 +03:00
- [Run HNix ](#run-hnix )
2021-01-14 16:13:47 +03:00
- [Using Nix-build ](#using-nix-build )
- [Checking the project ](#checking-the-project-1 )
- [Benchmarks ](#benchmarks-1 )
- [Profiling ](#profiling-1 )
- [Full debug info ](#full-debug-info-1 )
- [Run HNix ](#run-hnix-1 )
- [Using HNix ](#using-hnix )
- [Evaluating Nixpkgs ](#evaluating-nixpkgs )
- [REPL ](#repl )
- [Language laziness ](#language-laziness )
2021-01-14 01:03:36 +03:00
- [Contributing ](#contributing )
- [(optional) Minimalistic development status loop with amazing `ghcid` ](#optional-minimalistic-development-status-loop-with-amazing-ghcid )
2021-01-13 23:24:31 +03:00
- [Current status ](#current-status )
2020-09-29 16:55:00 +03:00
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2020-09-29 04:21:17 +03:00
2016-02-08 02:53:22 +03:00
## Prerequisites
2020-09-29 18:04:24 +03:00
Tooling is WIP, `nix-shell` and `nix-store` are still used for their purpose, so, to access them Nix is required to be installed.
2016-02-08 02:53:22 +03:00
2021-01-04 23:41:29 +03:00
*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.
2016-02-08 02:53:22 +03:00
## Getting Started
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:26:24 +03:00
# Note: --recursive
2021-01-05 01:12:24 +03:00
git clone --recursive 'https://github.com/haskell-nix/hnix.git'
2020-09-28 21:20:40 +03:00
cd hnix
2020-09-28 21:31:22 +03:00
```
2020-09-30 17:11:08 +03:00
### Cachix prebuild binary caches
2020-09-30 21:04:01 +03:00
If you opt in to use of Nix environment, please enable the official HNix Cachix binary cache:
2020-09-30 17:11:08 +03:00
1. Go through https://cachix.org/ and set it up.
2. Run: `cachix use hnix`
2021-01-14 16:11:23 +03:00
### Using Cabal
2020-09-30 16:00:22 +03:00
2020-09-30 16:55:09 +03:00
Cabal [Quickstart ](https://cabal.readthedocs.io/en/3.4/nix-local-build.html ).
2020-09-30 17:24:24 +03:00
1. (Optional), to enter the projects reproducible Nix environment:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:17:34 +03:00
nix-shell
```
2020-09-30 16:00:22 +03:00
2. Building:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:17:34 +03:00
cabal v2-configure
cabal v2-build
```
2020-09-30 16:00:22 +03:00
2020-09-30 17:00:52 +03:00
3. Loading the project into `ghci` REPL:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 17:00:52 +03:00
cabal v2-repl
```
2020-09-30 20:37:59 +03:00
4. Testing:
2020-09-30 16:17:34 +03:00
* Default suite:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:17:34 +03:00
cabal v2-test
```
* All available tests:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:17:34 +03:00
env ALL_TESTS=yes cabal v2-test
```
* Selected (list of tests is in `tests/Main.hs` ):
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 16:17:34 +03:00
env NIXPKGS_TESTS=yes PRETTY_TESTS=1 cabal v2-test
```
2018-05-07 22:45:37 +03:00
2021-01-14 16:11:23 +03:00
#### Checking the project
2020-09-29 01:49:12 +03:00
2021-01-14 16:11:23 +03:00
##### Benchmarks
2020-09-30 17:06:57 +03:00
2020-09-30 16:23:38 +03:00
To run benchmarks:
2020-07-03 18:00:03 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-28 21:20:40 +03:00
cabal v2-bench
2020-07-03 18:00:03 +03:00
```
2021-01-14 16:11:23 +03:00
##### Profiling
2018-04-10 21:49:18 +03:00
To build `hnix` with profiling enabled:
2021-01-05 01:12:24 +03:00
```shell
2020-09-28 21:20:40 +03:00
cabal v2-configure --enable-tests --enable-profiling --flags=profiling
2020-09-29 01:49:55 +03:00
cabal v2-run hnix -- < args > +RTS -p
2020-07-03 18:00:03 +03:00
```
2021-01-14 16:11:23 +03:00
##### Full debug info
2020-07-03 18:00:03 +03:00
2021-01-14 16:11:23 +03:00
To run stack traces & full tracing output on `hnix` :
2020-09-29 17:12:47 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-29 17:14:43 +03:00
cabal v2-configure --enable-tests --enable-profiling --flags=profiling --flags=tracing
cabal v2-run hnix -- -v5 --trace < args > +RTS -xc
```
2018-04-19 02:28:21 +03:00
2021-01-14 16:11:23 +03:00
This would give the most information as to what happens during parsing & evaluation.
2018-04-13 10:06:45 +03:00
2020-09-30 17:52:58 +03:00
#### Run HNix
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 17:35:15 +03:00
cabal v2-run hnix -- --help
2018-04-13 10:06:45 +03:00
```
2020-09-30 17:35:15 +03:00
(`--` is for separation between `cabal` & `hnix` args)
2018-04-13 10:06:45 +03:00
2018-04-10 21:49:18 +03:00
2021-01-14 16:11:23 +03:00
### Using Nix-build
2020-09-30 18:21:43 +03:00
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 ](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/lib.nix ).
Options can be used as:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 18:21:43 +03:00
nix-build \
--arg < option1 > < argument1 > \
--arg < option2 > < argument2 > \
--argstr < option3 > "< strinTypeArg > "
```
2021-01-14 16:11:23 +03:00
#### Checking the project
##### Benchmarks
2020-09-30 18:21:43 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 18:21:43 +03:00
nix-build \
--arg disableOptimization false \
--arg enableDeadCodeElimination true \
--arg doStrip true \
--arg doBenchmark true
```
2021-01-14 16:11:23 +03:00
##### Profiling
2020-09-30 18:21:43 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 18:21:43 +03:00
nix-build \
--arg disableOptimization false \
--arg enableDeadCodeElimination true \
--arg enableLibraryProfiling true \
--arg enableExecutableProfiling true
2021-01-14 16:11:23 +03:00
./result/bin/hnix < args > +RTS -p
2020-09-30 18:21:43 +03:00
```
2021-01-14 16:11:23 +03:00
##### Full debug info
2020-09-30 18:21:43 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 18:21:43 +03:00
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
2021-01-14 16:11:23 +03:00
./result/bin/hnix -v5 --trace < args > +RTS -xc
2020-09-30 18:21:43 +03:00
```
2021-01-14 16:11:23 +03:00
#### Run HNix
2020-09-30 18:25:39 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 18:25:39 +03:00
./result/bin/hnix
```
2021-01-14 16:11:23 +03:00
## Using HNix
2021-01-14 15:53:45 +03:00
2021-01-14 16:11:23 +03:00
### Evaluating Nixpkgs
2021-01-14 15:53:45 +03:00
Currently, the main high-level goal is to be able to evaluate all of Nixpkgs:
2018-04-10 21:49:18 +03:00
2021-01-14 15:53:45 +03:00
```shell
hnix --eval -E "import < nixpkgs > {}" --find
```
### REPL
Ot enter REPL:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 17:35:51 +03:00
hnix --repl
2018-04-10 21:49:18 +03:00
```
2021-01-14 15:53:45 +03:00
Evaluate an expression and load it into REPL:
2021-01-05 01:12:24 +03:00
```shell
2020-09-30 17:35:51 +03:00
hnix --eval -E '(import < nixpkgs > {}).pkgs.hello' --repl
2020-09-29 17:14:43 +03:00
```
2021-01-14 15:53:45 +03:00
This binds the evaluated expression result to the `input` variable, so that variable can be inspected.
2020-09-29 17:14:43 +03:00
2020-09-30 17:35:51 +03:00
Use the `:help` command for a list of all available REPL commands.
2020-09-29 17:14:43 +03:00
2021-01-14 15:53:45 +03:00
#### Language laziness
2020-10-04 17:29:50 +03:00
Nix is a lazy language with the ability of recursion, so by default REPL and eval prints are lazy:
2021-01-05 01:12:24 +03:00
```shell
2020-10-04 17:29:50 +03:00
hnix \
--eval \
--expr '{ x = true; }'
{ x = "< CYCLE > "; }
```
To disable laziness add the `--strict` to commands or `:set strict` in the REPL.
2021-01-05 01:12:24 +03:00
```shell
2020-10-04 17:29:50 +03:00
hnix \
--eval \
--strict \
--expr '{ x = true; }'
{ x = true; }
```
2020-09-29 17:14:43 +03:00
2021-01-14 01:00:52 +03:00
2020-09-29 03:07:07 +03:00
## Contributing
2018-04-04 08:57:23 +03:00
2021-01-14 15:53:45 +03:00
Haskell Language Server & Cabal development. Or development in the Nix shell environment.
2021-01-14 01:01:09 +03:00
2020-09-29 03:19:10 +03:00
1. If something in the [quests ](https://github.com/haskell-nix/hnix/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee ) looks interesting, look through the thread and leave a comment taking it, to let others know you're working on it.
2020-09-29 03:17:20 +03:00
2020-09-29 03:19:10 +03:00
2. You are free to chat with everyone on [Gitter ](https://gitter.im/haskell-nix/Lobby ).
2018-04-04 08:57:23 +03:00
2020-09-30 17:23:18 +03:00
3. When the pull request is ready to be submitted, to save time - please, test it with:
2020-04-18 11:59:05 +03:00
2021-01-05 01:12:24 +03:00
```shell
2020-09-28 21:20:40 +03:00
git submodule update --init --recursive
2021-01-14 01:01:09 +03:00
cabal v2-test
2018-04-04 08:57:23 +03:00
```
2021-01-14 16:11:23 +03:00
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.
2018-11-18 19:44:52 +03:00
2021-01-14 01:01:09 +03:00
### (optional) Minimalistic development status loop with amazing [`ghcid`](https://github.com/ndmitchell/ghcid)
2018-11-18 19:44:52 +03:00
2021-01-05 01:12:24 +03:00
```shell
2021-01-14 01:00:52 +03:00
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"
2018-11-18 19:44:52 +03:00
```
2021-01-14 01:00:52 +03:00
(optional) To use projects reproducible environment, wrap `ghcid ...` command into a `nix-shell --command ' '` .
For simplicity `alias` the command in your shell.
2021-01-13 22:39:23 +03:00
2021-01-14 01:01:09 +03:00
2021-01-13 22:39:23 +03:00
## Current status
To understand the project implementation state see [Changelog ](https://github.com/haskell-nix/hnix/blob/master/CHANGELOG.md ), [opened reports ](https://github.com/haskell-nix/hnix/issues ) and [Project status ](https://github.com/haskell-nix/hnix/wiki/Project-status ).