diff options
Diffstat (limited to 'tvix/eval/README.md')
| -rw-r--r-- | tvix/eval/README.md | 78 |
1 files changed, 70 insertions, 8 deletions
diff --git a/tvix/eval/README.md b/tvix/eval/README.md index 8320aa8ea3..02e2100f59 100644 --- a/tvix/eval/README.md +++ b/tvix/eval/README.md @@ -2,22 +2,83 @@ Tvix Evaluator ============== This project implements an interpreter for the Nix programming -language. +language. You can experiment with an online version of the evaluator: +[tvixbolt][]. The interpreter aims to be compatible with `nixpkgs`, on the foundation of Nix 2.3. -<!-- TODO(tazjin): Remove this note when appropriate --> -Work on this project is *extremely in-progress*, and the state of the -project in the public repository may not necessarily reflect the state -of the private codebase, as we are slowly working on publishing it. - -We expect this to have caught up in a handful of weeks (as of -2022-08-12). +**Important note:** The evaluator is not yet feature-complete, and +while the core mechanisms (compiler, runtime, ...) have stabilised +somewhat, a lot of components are still changing rapidly. Please contact [TVL](https://tvl.fyi) with any questions you might have. +## Building tvix-eval + +Please check the `README.md` one level up for instructions on how to build this. + +The evaluator itself can also be built with standard Rust tooling (i.e. `cargo +build`). + +If you would like to clone **only** the evaluator and build it +directly with Rust tooling, you can do: + +```bash +git clone https://code.tvl.fyi/depot.git:/tvix/eval.git tvix-eval + +cd tvix-eval && cargo build +``` + +## Tests + +Tvix currently has three language test suites for tvix-eval: + +* `nix_tests` and `tvix_tests` are based on the same mechanism + borrowed from the C++ Nix implementation. They consist of + Nix files as well as expected output (if applicable). + The test cases are split into four categories: + `eval-okay` (evaluates successfully with the expected output), + `eval-fail` (fails to evaluate, no expected output), + `parse-okay` (expression parses successfully, no expected output) + and `parse-fail` (expression fails to parse, no expected output). + Tvix currently ignores the last two types of test cases, since + it doesn't implement its own parser. + + Both test suites have a `notyetpassing` directory. All test cases + in here test behavior that is not yet supported by Tvix. They are + considered to be expected failures, so you can't forget to move + them into the test suite proper when fixing the incompatibility. + + Additionally, separate targets in the depot pipeline, under + `//tvix/verify-lang-tests`, check both test suites (including + `notyetpassing` directories) against + C++ Nix 2.3 and the default C++ Nix version in nixpkgs. + This way we can prevent accidentally introducing test cases + for behavior that C++ Nix doesn't exhibit. + + * `nix_tests` has the test cases from C++ Nix's language test + suite and is sporadically updated by manually syncing the + directories. The `notyetpassing` directory shows how far + it is until we pass it completely. + + * `tvix_tests` contains test cases written by the Tvix contributors. + Some more or less duplicate test cases contained in `nix_tests`, + but many cover relevant behavior that isn't by `nix_tests`. + Consequently, it'd be nice to eventually merge the two test + suites into a jointly maintained, common Nix language test suite. + + It also has a `notyetpassing` directory for missing behavior + that is discovered while working on Tvix and isn't covered by the + `nix_tests` suite. + +* `nix_oracle` can evaluate Nix expressions in Tvix and compare the + result against C++ Nix (2.3) directly. Eventually it should gain + the ability to property test generated Nix expressions. + An additional feature is that it can evaluate expressions without + `--strict`, so thunking behavior can be verified more easily. + ## rnix-parser Tvix is written in memory of jD91mZM2, the author of [rnix-parser][] @@ -28,3 +89,4 @@ parser is now maintained by Nix community members. [rnix-parser]: https://github.com/nix-community/rnix-parser [rip]: https://www.redox-os.org/news/open-source-mental-health/ +[tvixbolt]: https://bolt.tvix.dev/ |