Struct Assembler 

pub struct Assembler { /* private fields */ }

The Assembler produces a Merkelized Abstract Syntax Tree (MAST) from Miden Assembly sources, as a Package artifact. In general, packages come in three primary varieties:

• A kernel library (i.e. TargetType::Kernel)
• A program (see TargetType::Executable)
• A library (all other target types)

Assembled artifacts can additionally reference or include code from previously assembled libraries.

Usage

Depending on your needs, there are multiple ways of using the assembler, starting with the type of artifact you want to produce:

• If you wish to produce an executable program, you will call Self::assemble_program with the source module which contains the program entrypoint.
• If you wish to produce a library for use in other executables, you will call Self::assemble_library with the source module(s) whose exports form the public API of the library.
• If you wish to produce a kernel library, you will call Self::assemble_kernel with the source module(s) whose exports form the public API of the kernel.

In the case where you are assembling a library or program, you also need to determine if you need to specify a kernel. You will need to do so if any of your code needs to call into the kernel directly.

• If a kernel is needed, you should construct an Assembler using Assembler::with_kernel
• Otherwise, you should construct an Assembler using Assembler::new

Programs compiled with an empty kernel cannot use the `syscall` instruction.

Lastly, you need to provide inputs to the assembler which it will use at link time to resolve references to procedures which are externally-defined (i.e. not defined in any of the modules provided to the assemble_* function you called). There are a few different ways to do this:

• If you have source code, or a ast::Module, see Self::compile_and_statically_link
• If you need to reference procedures from a previously assembled package, but do not want to include the MAST of those procedures in the assembled artifact, you want to dynamically link that library, see Linkage::Dynamic for more.
• If you want to incorporate referenced procedures from a previously assembled package into the assembled artifact, you want to statically link that library, see Linkage::Static for more.

Implementations

impl Assembler

Constructors

pub fn new(source_manager: Arc<dyn SourceManager>) -> Self

Start building an Assembler

pub fn with_kernel( source_manager: Arc<dyn SourceManager>, kernel: Arc<Package>, ) -> Result<Self, Report>

Start building an Assembler with a kernel defined by the provided kernel package.

pub fn with_warnings_as_errors(self, yes: bool) -> Self

Sets the default behavior of this assembler with regard to warning diagnostics.

When true, any warning diagnostics that are emitted will be promoted to errors.

impl Assembler

Dependency Management

pub fn compile_and_statically_link( &mut self, module: impl Parse, ) -> Result<&mut Self, Report>

Ensures module is compiled, and then statically links it into the final artifact.

The given module must be a library module, or an error will be returned.

pub fn compile_and_statically_link_all( &mut self, modules: impl IntoIterator<Item = impl Parse>, ) -> Result<&mut Self, Report>

Ensures every module in modules is compiled, and then statically links them into the final artifact.

All of the given modules must be library modules, or an error will be returned.

pub fn compile_and_statically_link_from_root( &mut self, root: impl AsRef<Path>, namespace: Option<&Path>, ) -> Result<(), Report>

Compiles and statically links all Miden Assembly modules reachable from the provided root module. The namespace of the resulting modules will be derived from an explicit namespace declaration in the root module, or from namespace if provided - if both are present, they must agree.

The module structure is determined by mod declarations reachable from the root module, i.e. if the root module contains the line mod foo, then a submodule foo in the namespace of the root module will be located and parsed.

If provided namespace can be any valid Miden Assembly path, e.g. std is a valid path, as is std::math::u64 - there is no requirement that the namespace be a single identifier. This allows defining multiple projects relative to a common root namespace without conflict.

For example, let’s say I call this function like so:

use miden_assembly::{Assembler, Path};

let mut assembler = Assembler::default();
assembler.compile_and_statically_link_from_root("~/masm/core/lib.masm", None);

And lib.masm contains:

namespace miden::core

pub mod sys;
pub mod math;

Then either of the following directory layouts would be parsed successfully, with the namespacing shown:

Layout 1: Submodules are defined at the same level as the parent, named after their module name:

• ~/masm/core/lib.masm -> Parsed as “miden::core”
• ~/masm/core/sys.masm -> Parsed as “miden::core::sys”
• ~/masm/core/math.masm -> Parsed as “miden::core::math”
• ~/masm/core/math/README.md -> Ignored

Layout 2: Submodules are defined in sub-directories named after their module name:

• ~/masm/core/lib.masm -> Parsed as “miden::core”
• ~/masm/core/sys/mod.masm -> Parsed as “miden::core::sys”
• ~/masm/core/math/mod.masm -> Parsed as “miden::core::math”
• ~/masm/core/math/README.md -> Ignored

pub fn with_package( self, package: Arc<Package>, linkage: Linkage, ) -> Result<Self, Report>

Link against package with the specified linkage mode during assembly.

pub fn link_package( &mut self, package: Arc<Package>, linkage: Linkage, ) -> Result<(), Report>

Link against package with the specified linkage mode during assembly.

impl Assembler

Public Accessors

pub fn warnings_as_errors(&self) -> bool

Returns true if this assembler promotes warning diagnostics as errors by default.

pub fn kernel(&self) -> &Kernel

Returns a reference to the kernel for this assembler.

If the assembler was instantiated without a kernel, the internal kernel will be empty.

impl Assembler

Compilation/Assembly

pub fn assemble_library( self, name: impl Into<PackageId>, root: impl Parse, support: impl IntoIterator<Item = impl Parse>, ) -> Result<Box<Package>, Report>

Assembles a root module, and its supporting submodules into a library Package.

Errors

Returns an error if parsing or compilation of the specified modules fails.

pub fn assemble_library_from_root( self, root: impl AsRef<Path>, namespace: Option<&Path>, ) -> Result<Box<Package>, Report>

Assemble a library Package from the set of modules reachable from root.

See Assembler::compile_and_statically_link_from_root for details on how modules are discovered and linked from root.

pub fn assemble_kernel( self, name: impl Into<PackageId>, root: Box<Module>, support: impl IntoIterator<Item = Box<Module>>, ) -> Result<Box<Package>, Report>

Assembles the provided module into a kernel package.

Errors

Returns an error if parsing or compilation of the specified modules fails.

pub fn assemble_kernel_from_root( self, name: impl Into<PackageId>, sys_module_path: impl AsRef<Path>, ) -> Result<Box<Package>, Report>

Assemble a kernel Package from a standard Miden Assembly kernel project layout.

The kernel library will export procedures defined by the module at sys_module_path.

If the optional lib_dir is provided, all modules under this directory will be available from the kernel module under the $kernel namespace. For example, if lib_dir is set to “~/masm/lib”, the files will be accessible in the kernel module as follows:

• ~/masm/lib/foo.masm -> Can be imported as “$kernel::foo”
• ~/masm/lib/bar/baz.masm -> Can be imported as “$kernel::bar::baz”

Note: this is a temporary structure which will likely change once https://github.com/0xMiden/miden-vm/issues/1436 is implemented.

pub fn assemble_program( self, name: impl Into<PackageId>, source: impl Parse, ) -> Result<Box<Package>, Report>

Compiles the provided module into an executable package.

The resulting program can be executed on Miden VM.

Errors

Returns an error if parsing or compilation of the specified program fails, or if the source doesn’t have an entrypoint.

impl Assembler

pub fn for_project_at_path<'a, S>( self, manifest_path: impl AsRef<FsPath>, store: &'a mut S, ) -> Result<ProjectAssembler<'a, S>, Report>

where S: PackageCache + ?Sized,

Get a ProjectAssembler configured for the project whose manifest is at manifest_path.

pub fn for_project_at_path_with_providers<'a, S>( self, manifest_path: impl AsRef<FsPath>, store: &'a mut S, providers: impl IntoIterator<Item = Box<dyn ProjectSourceProvider>>, ) -> Result<ProjectAssembler<'a, S>, Report>

where S: PackageCache + ?Sized,

Get a ProjectAssembler configured for the project whose manifest is at manifest_path.

pub fn for_project<'a, S>( self, project: Arc<ProjectPackage>, store: &'a mut S, ) -> Result<ProjectAssembler<'a, S>, Report>

where S: PackageCache + ?Sized,

Get a ProjectAssembler configured for project

pub fn for_project_with_providers<'a, S>( self, project: Arc<ProjectPackage>, store: &'a mut S, providers: impl IntoIterator<Item = Box<dyn ProjectSourceProvider>>, ) -> Result<ProjectAssembler<'a, S>, Report>

where S: PackageCache + ?Sized,

Get a ProjectAssembler configured for project

Trait Implementations

impl Clone for Assembler

fn clone(&self) -> Assembler

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Assembler

fn default() -> Self

Returns the “default value” for a type.