diff --git a/README.md b/README.md index 12b8305..9fcd27b 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,73 @@ loot-condition-interpreter ========================== -A library for parsing and evaluating LOOT's metadata condition strings. This -library improves upon LOOT's existing implementation in the following ways: +[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/loot/loot-condition-interpreter?branch=master&svg=true)](https://ci.appveyor.com/project/loot/loot-condition-interpreter) +[![Travis Build Status](https://travis-ci.org/loot/loot-condition-interpreter.svg?branch=master)](https://travis-ci.org/loot/loot-condition-interpreter) +[![dependency status](https://deps.rs/repo/github/Ortham/libloadorder/status.svg)](https://deps.rs/repo/github/loot/loot-condition-interpreter) -- Condition expressions are parsed into an intermediate representation instead - of being stringly typed, which allows parsing and evaluation to be separated. -- State is uncoupled by necessity, and Rusts's concurrency guarantees mean it - can be accessed more efficiently. -- Results are cached with more granularity, per function instead of per - expression, improving performance when expressions are not entirely different. -- Result caching is guided by benchmarks, so results aren't cached - unnecessarily. -- Reading executable versions doesn't involve calling out to the shell and - piping several commands together when on Linux. +A library for parsing and evaluating LOOT's metadata condition strings. It +provides: -The code is also not as much of a mess, it's got benchmarks, and probably better -test coverage. +- Condition string parsing without evaluation, for checking syntax. +- Evaluation of parsed condition strings. +- Efficient and safe concurrent condition evaluation thanks to Rust's safety + guarantees. +- Caching of individual function evaluation results and calculated CRCs. +- Executable version parsing without any external runtime dependencies. +- Lots of tests, and benchmarks. +- A C FFI library that wraps the Rust library. -The tests need the [testing-plugins](https://github.com/WrinklyNinja/testing-plugins) +## Build + +Make sure you have [Rust](https://www.rust-lang.org/) installed. + +To build the Rust and C FFI libraries, run: + +``` +cargo build --release --package loot-condition-interpreter-ffi +``` + +To generate a C++ header file as part of the build, instead run: + +``` +cargo build --release --package loot-condition-interpreter-ffi --all-features +``` + +This will create a file at `ffi/include/loot_condition_interpreter.hpp`. +However, this involves building [cbindgen](https://github.com/eqrion/cbindgen) +as a dependency, which is relatively slow. If you have cbindgen installed +separately, it's faster to generate the headers using its CLI: + +``` +cbindgen ffi/ -l c++ -o ffi/include/loot_condition_interpreter.hpp +``` + +## Tests & Benchmarks + +The tests and benchmarks need the [testing-plugins](https://github.com/WrinklyNinja/testing-plugins) and the [LOOT API v0.13.8](https://github.com/loot/loot-api/releases/tag/0.13.8) -Windows archives to be extracted and present in the repo root. +Windows archives to be extracted and present in the repo root. See the AppVeyor +and Travis CI configurations for examples on what should be extracted where. + +To run the Rust tests: + +``` +cargo test --all +``` + +To run the benchmarks: + +``` +cargo bench +``` + +There are also C++ tests for the FFI library, they require a C++ toolchain and +[CMake](https://cmake.org/) to be installed. To run the C++ tests: + +``` +mkdir ffi/build +cd ffi/build +cmake .. +cmake --build . +ctest +```