From 4be3d9d2bc548b6fc5ef731505fe78fed98c7bb6 Mon Sep 17 00:00:00 2001 From: Leo Alt Date: Mon, 12 Feb 2024 15:30:16 +0100 Subject: [PATCH] docs about powdr as library --- .github/workflows/pr-tests.yml | 2 ++ Cargo.toml | 1 + book/book.toml | 2 +- book/src/SUMMARY.md | 3 +- book/src/powdr_crate.md | 33 +++++++++++++++++ powdr-test/Cargo.toml | 14 ++++++++ powdr-test/examples/hello_world.rs | 58 ++++++++++++++++++++++++++++++ 7 files changed, 111 insertions(+), 2 deletions(-) create mode 100644 book/src/powdr_crate.md create mode 100644 powdr-test/Cargo.toml create mode 100644 powdr-test/examples/hello_world.rs diff --git a/.github/workflows/pr-tests.yml b/.github/workflows/pr-tests.yml index a040c4baf..13ab20e3b 100644 --- a/.github/workflows/pr-tests.yml +++ b/.github/workflows/pr-tests.yml @@ -84,6 +84,8 @@ jobs: - uses: taiki-e/install-action@nextest - name: Run default tests run: PILCOM=$(pwd)/pilcom/ cargo nextest run --archive-file tests.tar.zst --verbose + - name: Run examples + run: cargo run --example hello_world test_slow: strategy: diff --git a/Cargo.toml b/Cargo.toml index d9e1672b6..77af2584f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,6 +4,7 @@ resolver = "2" members = [ "powdr", + "powdr-test", "number", "parser", "cli", diff --git a/book/book.toml b/book/book.toml index 6803379f8..4049107e2 100644 --- a/book/book.toml +++ b/book/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["schaeff"] +authors = ["powdr labs"] language = "en" multilingual = false src = "src" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index a900f5c97..300f448d6 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -4,7 +4,8 @@ # Getting Started - [Installation](./installation.md) -- [Hello World](./hello_world.md) +- [Hello World using the CLI](./hello_world.md) +- [Hello World using powdr as a library](./powdr_crate.md) # Reference Guide diff --git a/book/src/powdr_crate.md b/book/src/powdr_crate.md new file mode 100644 index 000000000..01809d7b1 --- /dev/null +++ b/book/src/powdr_crate.md @@ -0,0 +1,33 @@ +# Using powdr as a library + +Besides the CLI, powdr can also be used as a Rust library. +The [powdr crate](https://github.com/powdr-labs/powdr/tree/main/powdr) +exposes internal crates and data structures needed to compile code, +generate witnesses, and compute proofs. + +Add `powdr` to your crate's dependencies: + +```toml +[dependencies] +powdr = { git = "https://github.com/powdr-labs/powdr", branch = "main" } +``` + +The following Rust code has the same workflow as our previous "Hello World" +example. The full project can be found +[here](https://github.com/powdr-labs/powdr-hello-world), and as an example in +the powdr crate. To run the example in the [powdr +repository](https://github.com/powdr-labs/powdr), run: + +```bash +cargo run --example powdr_crate_usage +``` + +You can also enable logs to know what is happening internally: + +```bash +RUST_LOG=info cargo run --example powdr_crate_usage +``` + +```rust +{{#include ../../powdr-test/examples/hello_world.rs}} +``` diff --git a/powdr-test/Cargo.toml b/powdr-test/Cargo.toml new file mode 100644 index 000000000..68cececd0 --- /dev/null +++ b/powdr-test/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "powdr-test" +description = "Tests and examples for the powdr crate" +version.workspace = true +edition.workspace = true +license.workspace = true +homepage.workspace = true +repository.workspace = true + +[dependencies] +powdr = { path = "../powdr" } + +[dev-dependencies] +env_logger = "0.10.2" diff --git a/powdr-test/examples/hello_world.rs b/powdr-test/examples/hello_world.rs new file mode 100644 index 000000000..aaa9181ad --- /dev/null +++ b/powdr-test/examples/hello_world.rs @@ -0,0 +1,58 @@ +use powdr::backend::BackendType; +use powdr::pipeline::util::write_or_panic; +use powdr::Bn254Field; +use powdr::Pipeline; + +use std::fs; +use std::io::BufWriter; + +fn main() { + env_logger::init(); + + // Straightforward case + let _proof = Pipeline::::default() + .from_file("test_data/asm/book/hello_world.asm".into()) + .with_prover_inputs(vec![0.into()]) + .with_backend(BackendType::Halo2) + .proof() + .unwrap(); + + // Step-by-step case + + // First we create the universal setup of size 8 + let params_file = BufWriter::new(fs::File::create("params.bin").unwrap()); + write_or_panic(params_file, |writer| { + BackendType::Halo2 + .factory::() + .generate_setup(8, writer) + .unwrap() + }); + + // Configure a pipeline + let mut pipeline = Pipeline::::default() + .from_file("test_data/asm/book/hello_world.asm".into()) + .with_prover_inputs(vec![0.into()]) + .with_backend(BackendType::Halo2) + .with_setup_file(Some("params.bin".into())); + + // Create the verification key + let vkey_file = BufWriter::new(fs::File::create("vkey.bin").unwrap()); + write_or_panic(vkey_file, |w| pipeline.export_verification_key(w)).unwrap(); + + // Add the verification key and create a proof + let proof = pipeline + .clone() + .with_vkey_file(Some("vkey.bin".into())) + .proof() + .unwrap() + .proof + .unwrap(); + + // Create a fresh pipeline for proof verification + let mut pipeline = pipeline + .with_backend(BackendType::Halo2) + .with_setup_file(Some("params.bin".into())) + .with_vkey_file(Some("vkey.bin".into())); + + pipeline.verify(proof, &[vec![]]).unwrap(); +}