Merge pull request #1048 from powdr-labs/library-docs

docs about powdr as library

.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:

Cargo.toml

@@ -4,6 +4,7 @@ resolver = "2"
 
 members = [
     "powdr",
+    "powdr-test",
     "number",
     "parser",
     "cli",

book/book.toml

@@ -1,5 +1,5 @@
 [book]
-authors = ["schaeff"]
+authors = ["powdr labs"]
 language = "en"
 multilingual = false
 src = "src"

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
 <!-- markdown-link-check-disable-next-line -->

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}}
+```

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"

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::<Bn254Field>::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::<Bn254Field>()
+            .generate_setup(8, writer)
+            .unwrap()
+    });
+
+    // Configure a pipeline
+    let mut pipeline = Pipeline::<Bn254Field>::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();
+}