Merge pull request #391 from 0xPolygonMiden/greenhat/i390-add-fib-exa…

…mple

chore: add fibonacci sequence example

Cargo.toml

@@ -26,6 +26,7 @@ exclude = [
     "tests/rust-apps/fib",
     "tests/rust-apps-wasm",
     "cargo-ext/tests/data",
+    "examples",
 ]
 
 [workspace.package]

docs/usage/cargo-miden.md

@@ -58,7 +58,7 @@ As there is no panic infrastructure, `panic = "abort"` is set, and the panic han
 to use the native WebAssembly `unreachable` intrinsic, so the compiler will strip out all of the
 usual panic formatting code.
 
-### Compiling to Miden package
+## Compiling to Miden package
 
 Now that you've created your project, compiling it to Miden package is as easy as running the
 following command from the root of the project directory:
@@ -70,7 +70,7 @@ cargo miden build --release
 This will emit the compiled artifacts to `target/miden/release/foo.masp`.
 
 
-### Running a compiled Miden VM program
+## Running a compiled Miden VM program
 
 
 !!! warning
@@ -88,4 +88,6 @@ See `midenc run --help` for the inputs file format.
 
 
 
+## Examples
 
+Check out the [examples](https://github.com/0xPolygonMiden/compiler/tree/next/examples) for some `cargo-miden` project examples.

examples/README.md

@@ -0,0 +1,6 @@
+# Rust program examples
+
+These examples are built using `cargo-miden`.
+
+`cargo miden` is a `cargo` cargo extension. Check out its [documentation](https://0xpolygonmiden.github.io/compiler/usage/cargo-miden/#compiling-to-miden-assembly)
+for more details on how to build and run the compiled programs.

examples/fibonacci/.gitignore

@@ -0,0 +1 @@
+/target

examples/fibonacci/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name = "fibonacci"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+# Build this crate as a self-contained, C-style dynamic library
+# This is required to emit the proper Wasm module type
+crate-type = ["cdylib"]
+
+[dependencies]
+# Miden SDK consists of a stdlib (intrinsic functions for VM ops, stdlib functions and types)
+# and transaction kernel API for the Miden rollup
+
+miden = { git = "https://github.com/0xPolygonMiden/compiler" }
+
+
+[profile.release]
+# optimize the output for size
+opt-level = "z"
+# Explicitly disable panic infrastructure on Wasm, as
+# there is no proper support for them anyway, and it
+# ensures that panics do not pull in a bunch of standard
+# library code unintentionally
+panic = "abort"
+
+[profile.dev]
+# Explicitly disable panic infrastructure on Wasm, as
+# there is no proper support for them anyway, and it
+# ensures that panics do not pull in a bunch of standard
+# library code unintentionally
+panic = "abort"
+opt-level = 1
+debug-assertions = false
+overflow-checks = false
+debug = true

examples/fibonacci/README.md

@@ -0,0 +1,21 @@
+# fibonacci
+
+## Useful commands
+
+`fibonacci` is built using the [Miden compiler](https://github.com/0xPolygonMiden/compiler).
+
+`cargo miden` is a `cargo` cargo extension. Check out its [documentation](https://0xpolygonmiden.github.io/compiler/usage/cargo-miden/#compiling-to-miden-assembly)
+for more details on how to build and run the compiled programs.
+
+## Compile
+
+```bash
+cargo miden build --release
+```
+
+## Run
+
+```bash
+midenc run target/miden/release/fibonacci.masp --inputs inputs.toml
+```
+

examples/fibonacci/inputs.toml

@@ -0,0 +1,2 @@
+[inputs]
+stack = [25]

examples/fibonacci/rust-toolchain.toml

@@ -0,0 +1,5 @@
+[toolchain]
+channel = "nightly-2025-01-16"
+components = ["rustfmt", "rust-src"]
+targets = ["wasm32-wasi"]
+profile = "minimal"

examples/fibonacci/src/lib.rs

@@ -0,0 +1,37 @@
+// Do not link against libstd (i.e. anything defined in `std::`)
+#![no_std]
+
+// However, we could still use some standard library types while
+// remaining no-std compatible, if we uncommented the following lines:
+//
+// extern crate alloc;
+// use alloc::vec::Vec;
+
+// // Global allocator to use heap memory in no-std environment
+// #[global_allocator]
+// static ALLOC: BumpAlloc = miden::BumpAlloc::new();
+
+// Required for no-std crates
+#[panic_handler]
+fn my_panic(_info: &core::panic::PanicInfo) -> ! {
+    loop {}
+}
+
+// Pass up to 16 u32 inputs as entrypoint function parameters.
+// The output is temporarely limited to 1 u32 value
+//
+// NOTE:
+// The name of the entrypoint function is expected to be `entrypoint`. Do not remove the
+// `#[no_mangle]` attribute, otherwise, the rustc will mangle the name and it'll not be recognized
+// by the Miden compiler.
+#[no_mangle]
+pub fn entrypoint(n: u32) -> u32 {
+    let mut a = 0;
+    let mut b = 1;
+    for _ in 0..n {
+        let c = a + b;
+        a = b;
+        b = c;
+    }
+    a
+}

tests/integration/Cargo.toml

@@ -45,4 +45,3 @@ blake3.workspace = true
 concat-idents = "1.1"
 env_logger.workspace = true
 miden-core.workspace = true
-miden-integration-tests-rust-fib = { path = "../rust-apps/fib" }

tests/integration/expected/examples/fib.hir

@@ -0,0 +1,32 @@
+builtin.component  #[name = #root] #[namespace = #root_ns] #[version = 1.0.0] #[visibility = public] {
+
+    builtin.module  #[name = #fibonacci] #[visibility = public] {
+
+        builtin.function public @entrypoint(v0: i32) -> i32 {
+        ^block3(v0: i32):
+            v2 = hir.constant 0 : i32;
+            v3 = hir.constant 0 : i32;
+            v4 = hir.constant 1 : i32;
+            hir.br block5 v4, v0, v3;
+        ^block4(v1: i32):
+
+        ^block5(v6: i32, v7: i32, v10: i32):
+            v8 = hir.constant 0 : i32;
+            v9 = hir.neq v7, v8 : i1;
+            hir.cond_br block7, block8 v9;
+        ^block6(v5: i32):
+
+        ^block7:
+            v11 = hir.constant -1 : i32;
+            v12 = hir.add v7, v11 : i32 #[overflow = wrapping];
+            v13 = hir.add v10, v6 : i32 #[overflow = wrapping];
+            hir.br block5 v13, v12, v6;
+        ^block8:
+            hir.ret v10;
+        };
+        builtin.global_variable  #[name = #__stack_pointer] #[ty = i32] #[visibility = private] {
+
+            hir.ret_imm  #[value = 1048576];
+        };
+    };
+};

tests/integration/expected/fib.masm → tests/integration/expected/examples/fib.masm

@@ -1,6 +1,6 @@
-# mod miden_integration_tests_rust_fib_wasm
+# mod fibonacci
 
-export.fib
+export.entrypoint
     push.0
     push.1
     movup.2

tests/integration/expected/fib.wat → tests/integration/expected/examples/fib.wat

@@ -1,6 +1,6 @@
-(module $miden_integration_tests_rust_fib_wasm.wasm
+(module $fibonacci.wasm
   (type (;0;) (func (param i32) (result i32)))
-  (func $fib (;0;) (type 0) (param i32) (result i32)
+  (func $entrypoint (;0;) (type 0) (param i32) (result i32)
     (local i32 i32 i32)
     i32.const 0
     local.set 1
@@ -30,10 +30,6 @@
   )
   (memory (;0;) 16)
   (global $__stack_pointer (;0;) (mut i32) i32.const 1048576)
-  (global (;1;) i32 i32.const 1048576)
-  (global (;2;) i32 i32.const 1048576)
   (export "memory" (memory 0))
-  (export "fib" (func $fib))
-  (export "__data_end" (global 1))
-  (export "__heap_base" (global 2))
+  (export "entrypoint" (func $entrypoint))
 )