Struct Assembler 

pub struct Assembler { /* private fields */ }

The Assembler produces a Merkelized Abstract Syntax Tree (MAST) from Miden Assembly sources, as an artifact of one of three types:

• A kernel library (see KernelLibrary)
• A library (see Library)
• A program (see Program)

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 Library, but do not want to include the MAST of those procedures in the assembled artifact, you want to dynamically link that library, see Self::link_dynamic_library for more.
• If you want to incorporate referenced procedures from a previously assembled Library into the assembled artifact, you want to statically link that library, see Self::link_static_library 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_lib: KernelLibrary, ) -> Self

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

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_dir( &mut self, dir: impl AsRef<Path>, namespace: impl AsRef<Path>, ) -> Result<(), Report>

Compiles and statically links all Miden Assembly modules in the provided directory, using the provided Path as the root namespace for the compiled modules.

When compiling each module, its Miden Assembly path is derived by appending path components corresponding to the relative path of the module in dir, to namespace. If a source file named mod.masm is found, the resulting module will derive its path using the path components of the parent directory, rather than the file name.

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

This function recursively parses the entire directory structure under dir, ignoring any files which do not have the .masm extension.

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_dir("~/masm/core", "miden::core::foo");

Here’s how we would handle various files under this path:

• ~/masm/core/sys.masm -> Parsed as “miden::core::foo::sys”
• ~/masm/core/crypto/hash.masm -> Parsed as “miden::core::foo::crypto::hash”
• ~/masm/core/math/u32.masm -> Parsed as “miden::core::foo::math::u32”
• ~/masm/core/math/u64.masm -> Parsed as “miden::core::foo::math::u64”
• ~/masm/core/math/README.md -> Ignored

pub fn link_library( &mut self, library: impl AsRef<Library>, kind: LinkLibraryKind, ) -> Result<(), Report>

Links the final artifact against library.

The way in which procedures referenced in library will be linked by the final artifact is determined by kind:

• LinkLibraryKind::Dynamic inserts a reference to the procedure in the assembled MAST, but not the MAST of the procedure itself. Consequently, it is necessary to provide both the assembled artifact and library to the VM when executing the program, otherwise the procedure reference will not be resolvable at runtime.
• LinkLibraryKind::Static includes the MAST of the referenced procedure in the final artifact, including any code reachable from that procedure contained in library. The resulting artifact does not require library to be provided to the VM when executing it, as all procedure references were resolved ahead of time.

pub fn link_dynamic_library( &mut self, library: impl AsRef<Library>, ) -> Result<(), Report>

Dynamically link against library during assembly.

This makes it possible to resolve references to procedures exported by the library during assembly, without including code from the library into the assembled artifact.

Dynamic linking produces smaller binaries, but requires you to provide library to the VM at runtime when executing the assembled artifact.

Internally, calls to procedures exported from library will be lowered to a miden_core::mast::ExternalNode in the resulting MAST. These nodes represent an indirect reference to the root MAST node of the referenced procedure. These indirect references are resolved at runtime by the processor when executed.

One consequence of these types of references, is that in the case where multiple procedures have the same MAST root, but different decorators, it is not (currently) possible for the processor to distinguish between which specific procedure (and its resulting decorators) the caller intended to reference, and so any of them might be chosen.

In order to reduce the chance of this producing confusing diagnostics or debugger output, it is not recommended to export multiple procedures with the same MAST root, but differing decorators, from a library. There are scenarios where this might be necessary, such as when renaming a procedure, or moving it between modules, while keeping the original definition around during a deprecation period. It is just something to be aware of if you notice, for example, unexpected procedure paths or source locations in diagnostics - it could be due to this edge case.

pub fn with_dynamic_library( self, library: impl AsRef<Library>, ) -> Result<Self, Report>

Dynamically link against library during assembly.

See Self::link_dynamic_library for more details.

pub fn link_static_library( &mut self, library: impl AsRef<Library>, ) -> Result<(), Report>

Statically link against library during assembly.

This makes it possible to resolve references to procedures exported by the library during assembly, and ensure that the referenced procedure and any code reachable from it in that library, are included in the assembled artifact.

Static linking produces larger binaries, but allows you to produce self-contained artifacts that avoid the requirement that you provide library to the VM at runtime.

pub fn with_static_library( self, library: impl AsRef<Library>, ) -> Result<Self, Report>

Statically link against library during assembly.

See Self::link_static_library

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, modules: impl IntoIterator<Item = impl Parse>, ) -> Result<Library, Report>

Assembles a set of modules into a Library.

Errors

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

pub fn assemble_library_from_dir( self, dir: impl AsRef<Path>, namespace: impl AsRef<Path>, ) -> Result<Library, Report>

Assemble a Library from a standard Miden Assembly project layout, using the provided Path as the root under which the project is rooted.

The standard layout assumes that the given filesystem path corresponds to the root of namespace. Modules will be parsed with their path made relative to namespace according to their location in the directory structure with respect to path. See below for an example of what this looks like in practice.

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

NOTE: You must ensure there is no conflict in namespace between projects, e.g. two projects both assembled with namespace set to std::math would conflict with each other in a way that would prevent them from being used at the same time.

This function recursively parses the entire directory structure under path, ignoring any files which do not have the .masm extension.

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

use miden_assembly::{Assembler, Path};

Assembler::default().assemble_library_from_dir("~/masm/core", "miden::core::foo");

Here’s how we would handle various files under this path:

• ~/masm/core/sys.masm -> Parsed as “miden::core::foo::sys”
• ~/masm/core/crypto/hash.masm -> Parsed as “miden::core::foo::crypto::hash”
• ~/masm/core/math/u32.masm -> Parsed as “miden::core::foo::math::u32”
• ~/masm/core/math/u64.masm -> Parsed as “miden::core::foo::math::u64”
• ~/masm/core/math/README.md -> Ignored

pub fn assemble_kernel( self, module: impl Parse, ) -> Result<KernelLibrary, Report>

Assembles the provided module into a KernelLibrary intended to be used as a Kernel.

Errors

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

pub fn assemble_kernel_from_dir( self, sys_module_path: impl AsRef<Path>, lib_dir: Option<impl AsRef<Path>>, ) -> Result<KernelLibrary, Report>

Assemble a KernelLibrary 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, source: impl Parse) -> Result<Program, Report>

Compiles the provided module into a Program. 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.

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.