Cargo extension for compiling Rust to MASM

Cargo.toml

@@ -16,8 +16,9 @@ members = [
   "frontend-wasm",
   "tests/rust-apps/*",
   "tests/integration",
+  "cargo-ext",
 ]
-exclude = ["tests/rust-apps-wasm"]
+exclude = ["tests/rust-apps-wasm", "cargo-ext/tests/data"]
 
 [workspace.package]
 version = "0.1.0"
@@ -77,6 +78,7 @@ midenc-compile = { path = "midenc-compile" }
 midenc-driver = { path = "midenc-driver" }
 midenc-session = { path = "midenc-session" }
 miden-integration-tests = { path = "tests/integration" }
+miden-cargo-extension = { path = "cargo-ext" }
 
 
 [profile.dev]

cargo-ext/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "cargo-miden"
+version.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+categories.workspace = true
+keywords.workspace = true
+license.workspace = true
+readme.workspace = true
+edition.workspace = true
+publish.workspace = true
+autotests = false # disable autodiscovery of tests
+
+[[bin]]
+name = "cargo-miden"
+
+[[test]]
+name = "integration"
+path = "tests/mod.rs"
+
+[dependencies]
+midenc-compile.workspace = true
+midenc-session.workspace = true
+miden-diagnostics.workspace = true
+clap.workspace = true
+anyhow.workspace = true
+cargo_metadata = "0.18"
+cargo-generate = "0.18"
+path-absolutize = "3.1.1"
+
+[dev-dependencies]

cargo-ext/README.md

@@ -0,0 +1,50 @@
+# Miden Cargo Extension
+
+This crate provides a cargo extension that allows you to compile Rust code to Miden VM MASM.
+
+## Installation
+
+To install the extension, run:
+
+```bash
+cargo install cargo-miden
+```
+
+## Requirements
+
+Since Rust is first compiled to Wasm, you'll need to have the `wasm32-unknown-unknown` target installed:
+
+```bash
+rustup target add wasm32-unknown-unknown
+```
+
+## Usage
+
+### Getting help
+To get help with the extension, run:
+
+```bash
+cargo miden
+```
+
+Or for help with a specific command:
+
+```bash
+cargo miden <command> --help
+```
+
+### Creating a new project
+To create a new Miden VM project, run:
+
+```bash
+cargo miden new <project-name>
+```
+
+### Compiling a project
+To compile a Rust crate to Miden VM MASM, run:
+
+```bash
+cargo miden compile -o <output-file>
+```
+
+Without any additional arguments, this will compile the library target of the crate in the current directory.

cargo-ext/src/cli_commands.rs

@@ -0,0 +1,48 @@
+use std::path::PathBuf;
+
+use clap::Parser;
+use clap::Subcommand;
+use midenc_session::TargetEnv;
+
+#[derive(Parser, Debug)]
+#[command(name = "cargo")]
+#[command(bin_name = "cargo")]
+pub enum CargoCli {
+    Miden(MidenArgs),
+}
+
+#[derive(Parser, Debug)]
+#[command(name = "miden")]
+#[command(bin_name = "cargo miden")]
+#[command(about = "Cargo command for developing Miden projects", long_about = None)]
+pub struct MidenArgs {
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum Commands {
+    /// Compile the current project to MASM
+    #[command(next_display_order(10), name = "compile")]
+    Compile {
+        /// The target environment to compile for
+        #[arg(long = "target", value_name = "TARGET", default_value_t = TargetEnv::Base, display_order(2))]
+        target: TargetEnv,
+
+        /// Tells the compiler to produce an executable Miden program from the binary target or a library from the lib target if not specified
+        #[arg(long = "bin-name", display_order(3))]
+        bin_name: Option<String>,
+
+        /// Output directory for the compiled MASM file(s)
+        #[arg(
+            long = "out-dir",
+            value_name = "FOLDER",
+            id = "output-folder",
+            display_order(6)
+        )]
+        output_folder: PathBuf,
+    },
+    /// Scaffold a new Miden project at the given path
+    #[command(next_display_order(10), name = "new")]
+    New { path: PathBuf },
+}

cargo-ext/src/compile.rs

@@ -0,0 +1,135 @@
+use anyhow::bail;
+use cargo_metadata::Message;
+use std::path::PathBuf;
+use std::process::Command;
+use std::process::Stdio;
+use std::sync::Arc;
+
+use anyhow::Context;
+use miden_diagnostics::Verbosity;
+use midenc_session::InputFile;
+use midenc_session::OutputFile;
+use midenc_session::OutputType;
+use midenc_session::OutputTypeSpec;
+use midenc_session::OutputTypes;
+use midenc_session::ProjectType;
+use midenc_session::Session;
+use midenc_session::TargetEnv;
+
+pub fn compile(
+    target: TargetEnv,
+    bin_name: Option<String>,
+    output_folder: &PathBuf,
+) -> anyhow::Result<()> {
+    // for cargo env var see https://doc.rust-lang.org/cargo/reference/environment-variables.html
+    let mut cargo_build_cmd = Command::new("cargo");
+    cargo_build_cmd
+        .arg("build")
+        .arg("--release")
+        .arg("--target=wasm32-unknown-unknown");
+    let project_type = if let Some(ref bin_name) = bin_name {
+        cargo_build_cmd.arg("--bin").arg(bin_name.clone());
+        ProjectType::Program
+    } else {
+        ProjectType::Library
+    };
+    println!("Compiling Wasm with cargo build ...");
+    let mut child = cargo_build_cmd
+        .arg("--message-format=json-render-diagnostics")
+        .stdout(Stdio::piped())
+        .spawn()
+        .with_context(|| {
+            format!(
+                "Failed to execute cargo build {}.",
+                cargo_build_cmd
+                    .get_args()
+                    .map(|arg| format!("'{}'", arg.to_str().unwrap()))
+                    .collect::<Vec<_>>()
+                    .join(" ")
+            )
+        })?;
+    let reader = std::io::BufReader::new(child.stdout.take().unwrap());
+    let mut wasm_artifacts = Vec::new();
+    for message in cargo_metadata::Message::parse_stream(reader) {
+        match message.context("Failed to parse cargo metadata")? {
+            Message::CompilerArtifact(artifact) => {
+                // find the Wasm artifact in artifact.filenames
+                for filename in artifact.filenames {
+                    if filename.as_str().ends_with(".wasm") {
+                        wasm_artifacts.push(filename.into_std_path_buf());
+                    }
+                }
+            }
+            _ => (),
+        }
+    }
+    let output = child.wait().expect("Couldn't get cargo's exit status");
+    if !output.success() {
+        bail!("Rust to Wasm compilation failed!");
+    }
+
+    if wasm_artifacts.is_empty() {
+        match project_type {
+            ProjectType::Library => bail!("Cargo build failed, no Wasm artifact found. Check if crate-type = [\"cdylib\"] is set in Cargo.toml"),
+            ProjectType::Program => bail!("Cargo build failed, no Wasm artifact found."),
+        }
+    }
+    if wasm_artifacts.len() > 1 {
+        bail!(
+            "Cargo build failed, multiple Wasm artifacts found: {:?}. Only one Wasm artifact is expected.",
+            wasm_artifacts
+        );
+    }
+    let wasm_file_path = wasm_artifacts[0].clone();
+    match project_type {
+        ProjectType::Program => {
+            let bin_name = bin_name.unwrap();
+            if !wasm_file_path.ends_with(format!("{}.wasm", bin_name)) {
+                bail!(
+            "Cargo build failed, Wasm artifact name {} does not match the expected name '{}'.",
+            wasm_file_path.to_str().unwrap(),
+            bin_name
+        );
+            }
+        }
+        ProjectType::Library => (),
+    }
+
+    if !output_folder.exists() {
+        bail!(
+            "Output folder '{}' does not exist.",
+            output_folder.to_str().unwrap()
+        );
+    }
+
+    println!(
+        "Compiling '{}' Wasm to '{}' directory with midenc ...",
+        wasm_file_path.to_str().unwrap(),
+        &output_folder.as_path().to_str().unwrap()
+    );
+    let input = InputFile::from_path(wasm_file_path).context("Invalid input file")?;
+    let output_file_folder = OutputFile::Real(output_folder.clone());
+    let output_types = OutputTypes::new(vec![OutputTypeSpec {
+        output_type: OutputType::Masm,
+        path: Some(output_file_folder.clone()),
+    }]);
+    let cwd = std::env::current_dir().context("Failed to get current working directory")?;
+    let options = midenc_session::Options::new(cwd)
+        // .with_color(color)
+        .with_verbosity(Verbosity::Debug)
+        // .with_warnings(self.warn)
+        .with_output_types(output_types);
+    let session = Arc::new(
+        Session::new(
+            target,
+            input,
+            Some(output_folder.clone()),
+            None,
+            None,
+            options,
+            None,
+        )
+        .with_project_type(project_type),
+    );
+    midenc_compile::compile(session.clone()).context("Wasm to MASM compilation failed!")
+}

cargo-ext/src/lib.rs

@@ -0,0 +1,5 @@
+mod compile;
+mod new_project;
+
+pub use compile::compile;
+pub use new_project::new_project;

cargo-ext/src/main.rs

@@ -0,0 +1,24 @@
+use anyhow::Context;
+use cargo_miden::compile;
+use cargo_miden::new_project;
+use clap::Parser;
+use cli_commands::CargoCli;
+use cli_commands::Commands;
+
+mod cli_commands;
+
+fn main() -> anyhow::Result<()> {
+    let args = match CargoCli::parse() {
+        CargoCli::Miden(args) => args,
+    };
+
+    match args.command {
+        Commands::Compile {
+            target,
+            bin_name,
+            output_folder,
+        } => compile(target, bin_name, &output_folder)
+            .context(format!("Failed to compile {}", target)),
+        Commands::New { path } => new_project(path).context("Failed to scaffold a new project"),
+    }
+}

cargo-ext/src/new_project.rs

@@ -0,0 +1,41 @@
+use std::path::PathBuf;
+
+use anyhow::Context;
+use cargo_generate::GenerateArgs;
+use cargo_generate::TemplatePath;
+
+pub fn new_project(path: PathBuf) -> anyhow::Result<()> {
+    let name = path
+        .file_name()
+        .ok_or_else(|| {
+            anyhow::anyhow!("Failed to get the last segment of the provided path for the project name")
+        })?
+        .to_str()
+        .ok_or_else(|| {
+            anyhow::anyhow!("The last segment of the provided path must be valid UTF8 to generate a valid project name")
+        })?
+        .to_string();
+
+    let generate_args = GenerateArgs {
+        template_path: TemplatePath {
+            git: Some("https://github.com/0xPolygonMiden/rust-templates".into()),
+            auto_path: Some("library".into()),
+            ..Default::default()
+        },
+        destination: path
+            .parent()
+            .map(|p| {
+                use path_absolutize::Absolutize;
+                p.absolutize().map(|p| p.to_path_buf())
+            })
+            .transpose()
+            .context("Failed to convert destination path to an absolute path")?,
+        name: Some(name),
+        force_git_init: true,
+        verbose: true,
+        ..Default::default()
+    };
+    cargo_generate::generate(generate_args)
+        .context("Failed to scaffold new Miden project from the template")?;
+    return Ok(());
+}

cargo-ext/tests/compile.rs

@@ -0,0 +1,24 @@
+use crate::utils::get_test_path;
+use cargo_miden::compile;
+use midenc_session::TargetEnv;
+use std::env;
+use std::fs;
+
+#[test]
+fn compile_template() {
+    let restore_dir = env::current_dir().unwrap();
+    let test_dir = get_test_path("template");
+    // dbg!(&test_dir);
+    env::set_current_dir(&test_dir).unwrap();
+    let masm_path_rel = "target";
+    let output_folder = test_dir.join(masm_path_rel);
+    if !output_folder.exists() {
+        fs::create_dir_all(&output_folder).unwrap();
+    }
+    compile(TargetEnv::Base, None, &output_folder).expect("Failed to compile");
+    env::set_current_dir(restore_dir).unwrap();
+    let expected_masm_path = output_folder.join("miden_wallet_lib.masm");
+    assert!(expected_masm_path.exists());
+    assert!(expected_masm_path.metadata().unwrap().len() > 0);
+    fs::remove_file(expected_masm_path).unwrap();
+}