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 )
- [Development using Cabal ](#development-using-cabal )
2020-09-30 17:48:47 +03:00
- [Building the project ](#building-the-project )
- [With benchmarks ](#with-benchmarks )
- [With profiling ](#with-profiling )
- [With full debug info ](#with-full-debug-info )
- [Run HNix: ](#run-hnix )
2020-09-30 17:27:27 +03:00
- [Entering the HNix REPL ](#entering-the-hnix-repl )
2020-09-29 17:57:39 +03:00
- [Contributing ](#contributing )
2020-09-30 17:48:47 +03:00
- [Evaluating Nixpkgs with HNix ](#evaluating-nixpkgs-with-hnix )
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
## Getting Started
2020-04-18 11:59:05 +03:00
```
2020-09-30 16:26:24 +03:00
# Note: --recursive
2020-09-28 21:20:40 +03:00
git clone --recursive https://github.com/haskell-nix/hnix.git
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 17:23:18 +03:00
If you opt in to use of Nix environment, to accelerate processes, 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`
2020-09-30 16:40:47 +03:00
### Development 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:
2020-09-30 16:17:34 +03:00
```
nix-shell
```
2020-09-30 16:00:22 +03:00
2. Building:
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:
```
cabal v2-repl
```
2020-09-30 17:01:23 +03:00
4. Development status loop with amazing [`ghcid` ](https://github.com/ndmitchell/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 ' '` .
2020-09-30 17:40:06 +03:00
For simplicity alias it in your shell.
2020-09-30 17:01:23 +03:00
2020-09-30 16:00:22 +03:00
3. Testing:
2020-09-30 16:17:34 +03:00
* 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
```
2018-05-07 22:45:37 +03:00
2020-09-30 17:52:58 +03:00
#### Building the project
2020-09-29 01:49:12 +03:00
2020-09-30 17:52:58 +03:00
##### With 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
```
2020-09-28 21:20:40 +03:00
cabal v2-bench
2020-07-03 18:00:03 +03:00
```
2020-09-30 17:52:58 +03:00
##### With profiling
2018-04-10 21:49:18 +03:00
To build `hnix` with profiling enabled:
2020-07-03 18:00:03 +03:00
```
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
```
2020-09-30 17:52:58 +03:00
##### With full debug info
2020-07-03 18:00:03 +03:00
2020-09-29 17:14:43 +03:00
To build `hnix` for debugging, with full tracing output and stack traces:
2020-09-29 17:12:47 +03:00
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
2020-09-30 17:38:53 +03:00
Note that this going to run quite slowly, but 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
2018-04-13 10:06:45 +03:00
```
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
2020-09-30 17:56:16 +03:00
## Using the HNix REPL
2018-04-10 21:49:18 +03:00
2020-09-30 17:56:16 +03:00
To enter in:
2018-04-10 21:49:18 +03:00
```
2020-09-30 17:35:51 +03:00
hnix --repl
2018-04-10 21:49:18 +03:00
```
2020-09-30 17:35:51 +03:00
To evaluate an expression and make it available in the REPL as the `input` variable use:
2020-09-29 17:14:43 +03:00
```
2020-09-30 17:35:51 +03:00
hnix --eval -E '(import < nixpkgs > {}).pkgs.hello' --repl
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
2020-09-29 03:07:07 +03:00
## Contributing
2018-04-04 08:57:23 +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
2018-04-04 08:57:23 +03:00
```
2020-09-28 21:20:40 +03:00
git submodule update --init --recursive
nix-shell --run "LANGUAGE_TESTS=yes cabal v2-test"
2018-04-04 08:57:23 +03:00
```
2020-09-30 17:23:18 +03:00
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 check that locally than through CI. It's OK if no new tests are passing.
2018-11-18 19:44:52 +03:00
2020-09-30 17:40:06 +03:00
## Evaluating Nixpkgs with HNix
2018-11-18 19:44:52 +03:00
2020-09-30 17:23:18 +03:00
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:
2018-11-18 19:44:52 +03:00
```
2020-09-28 21:20:40 +03:00
./result/bin/hnix --eval -E "import < nixpkgs > {}" --find
2018-11-18 19:44:52 +03:00
```