From 2ed8a2cb0d955752f2b212b6898ab58ebfb7f220 Mon Sep 17 00:00:00 2001 From: Kamen Mladenov Date: Mon, 10 Feb 2025 15:39:06 +0200 Subject: docs(zkvms_host_io): Add detailed documentation comments --- zkvms_host_io/input_macros/src/lib.rs | 64 +++++++++++++++++++++++++++++++++++ zkvms_host_io/src/lib.rs | 22 +++++++++++- 2 files changed, 85 insertions(+), 1 deletion(-) (limited to 'zkvms_host_io') diff --git a/zkvms_host_io/input_macros/src/lib.rs b/zkvms_host_io/input_macros/src/lib.rs index e2982ca..465a9b4 100644 --- a/zkvms_host_io/input_macros/src/lib.rs +++ b/zkvms_host_io/input_macros/src/lib.rs @@ -4,6 +4,8 @@ use proc_macro::TokenStream; mod parse_fn; use crate::parse_fn::{ args_split, args_split_public, args_divide, args_divide_public, group_streams }; +/// Parses the `guests/type.txt` type note, created from the guest +/// Returns a tuple of the arguments group and the return type fn get_types() -> (TokenStream, TokenStream) { let types: Vec<&str> = include_str!("../../../guests/type.txt") .split('\n') @@ -13,6 +15,54 @@ fn get_types() -> (TokenStream, TokenStream) { static DERIVES: &str = "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]"; +/// Creates an Output type def and three Input structures from the guest +/// type.txt file. +/// +/// # Usage +/// +/// Inside zkvms_host_io: +/// +/// ```rust +/// input_macros::generate_output_type_input_struct!(); +/// ``` +/// +/// # Example output +/// +/// ```rust +/// pub type Output = (... ...); +/// +/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +/// pub struct PublicInput { +/// pub ...: ..., +/// pub ...: ..., +/// ... +/// } +/// +/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +/// pub struct PrivateInput { +/// pub ...: ..., +/// pub ...: ..., +/// ... +/// } +/// +/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +/// pub struct Input { +/// pub ...: ..., +/// pub ...: ..., +/// ... +/// } +/// +/// // Converts Input to a tuple +/// impl From for (...) { +/// fn from(input: Input) -> (...) { +/// ( +/// input...., +/// input...., +/// ... +/// ) +/// } +/// } +/// ``` #[proc_macro] pub fn generate_output_type_input_struct(_: TokenStream) -> TokenStream { let (args, ret) = get_types(); @@ -65,6 +115,8 @@ pub fn generate_output_type_input_struct(_: TokenStream) -> TokenStream { (output_type + &public_input_type + &private_input_type + &struct_def).parse::().unwrap() } +/// Repeats the given item as many times as fields there are, while replacing +/// all `.yield` occurences with the fields value (field name). fn foreach_field(item: TokenStream, fields: Vec) -> TokenStream { let expr = format!("{}", item); let mut out = String::new(); @@ -75,6 +127,9 @@ fn foreach_field(item: TokenStream, fields: Vec) -> TokenStream { out.parse::().unwrap() } +/// Repeats the given code as many times as fields there are in the Input +/// struct, while replacing all `.yield` occurences with the concrete +/// field name. #[proc_macro] pub fn foreach_input_field(item: TokenStream) -> TokenStream { let (args, _) = get_types(); @@ -83,6 +138,9 @@ pub fn foreach_input_field(item: TokenStream) -> TokenStream { foreach_field(item, arg_patterns) } +/// Repeats the given code as many times as fields there are in the +/// PublicInput struct, while replacing all `.yield` occurences with the +/// concrete field name. #[proc_macro] pub fn foreach_public_input_field(item: TokenStream) -> TokenStream { let (args, _) = get_types(); @@ -96,6 +154,9 @@ pub fn foreach_public_input_field(item: TokenStream) -> TokenStream { foreach_field(item, public_patterns) } +/// Repeats the given code as many times as fields there are in the +/// PrivateInput struct, while replacing all `.yield` occurences with the +/// concrete field name. #[proc_macro] pub fn foreach_private_input_field(item: TokenStream) -> TokenStream { let (args, _) = get_types(); @@ -109,6 +170,9 @@ pub fn foreach_private_input_field(item: TokenStream) -> TokenStream { foreach_field(item, private_patterns) } +/// Assuming the `run_info` variable is present, it creates a block with all +/// needed code to properly benchmark the input code, according to all command +/// parameters. #[proc_macro] pub fn benchmarkable(item: TokenStream) -> TokenStream { format!(r#" diff --git a/zkvms_host_io/src/lib.rs b/zkvms_host_io/src/lib.rs index 3de8c5e..9448789 100644 --- a/zkvms_host_io/src/lib.rs +++ b/zkvms_host_io/src/lib.rs @@ -12,25 +12,32 @@ static DEFAULT_ENV: &str = include_str!(concat!(env!("INPUTS_DIR"), "/default.en #[derive(Parser, Debug)] #[command(version, about, long_about = None)] struct Cli { - /// What the ZKVM is going to do + /// ZKVM action (execute, prove, verify) run_type: RunType, + /// Path to private input file in (TOML format) private_input: Option, + /// Path to public input file in (TOML format) public_input: Option, + /// Enable benchmark timer and formatted output #[arg(short, long)] benchmark: bool, + /// Benchmark the given action multiple times #[arg(short, long, requires = "benchmark")] repeat: Option, + /// Output timings as milliseconds instead of seconds #[arg(short, long, requires = "benchmark")] millis: bool, + /// Put the benchmark's formatted output into a file of the given path #[arg(short, long, requires = "benchmark")] metrics_output: Option, + /// Append the benchmark formatted output to the given file, instead of replacing it #[arg(short, long, requires = "benchmark")] append: bool, } @@ -59,6 +66,14 @@ pub struct RunWith { } impl RunWith { + /// Returns a value of the given name from the environment, + /// default environment or the given constant, depending on which + /// one exists. + /// + /// If the variable is from either environments, the `then_apply` + /// function is executed to convert the String value. + /// + /// The default environment is taken from the guest's `default.env` pub fn env_then_or(&self, variable_name: &str, then_apply: fn(String) -> Option, else_const: T) -> T { env::var(variable_name) .ok() @@ -70,6 +85,11 @@ impl RunWith { .unwrap_or(else_const)) } + /// Returns a value of the given name from the environment, + /// default environment or the given constant, depending on which + /// one exists. + /// + /// The default environment is taken from the guest's `default.env` pub fn env_or(&self, variable_name: &str, else_const: &str) -> String { self.env_then_or(variable_name, |x| Some(x), else_const.to_string()) } -- cgit v1.2.3