Struct SimulatorBuilder 

pub struct SimulatorBuilder<'a, Target = Simulator> { /* private fields */ }

A fluent builder for configuring and initializing a Simulator or Simulation.

Use Simulator::builder() or Simulation::builder() to obtain the appropriate variant. Both share the same configuration methods; only .build() differs in return type.

Implementations

impl<'a, Target> SimulatorBuilder<'a, Target>

Configuration methods shared by all builder variants.

pub fn sources(&self) -> &[(&'a str, &'a Path)]

Returns the source files passed to this builder.

pub fn top(&self) -> &str

Returns the top module name.

pub fn four_state_enabled(&self) -> bool

Returns whether four-state simulation is enabled for this builder.

pub fn with_metadata(self, metadata: Metadata) -> Self

Supply project metadata (clock/reset settings, etc.) instead of defaults.

pub fn clock_type(self, clock_type: ClockType) -> Self

Override the clock type (posedge/negedge) from metadata or defaults.

pub fn reset_type(self, reset_type: ResetType) -> Self

Override the reset type (async_high/async_low/sync_high/sync_low) from metadata or defaults.

pub fn param(self, name: &str, value: u64) -> Self

Override a top-level module parameter value.

pub fn with_injected_components(self, components: InjectedComponents) -> Self

Make in-process component implementations available as $comp::<name>.

pub fn vcd<P: AsRef<Path>>(self, path: P) -> Self

Enable VCD dumping to the specified file.

pub fn four_state(self, enable: bool) -> Self

Enable 4-state (0, 1, X, Z) simulation mode.

pub fn allow_always_ff_function_effects(self, enable: bool) -> Self

Allow function output and non-local write effects in always_ff.

This opts into Celox-specific lowering for constructs rejected by Veryl’s SystemVerilog compatibility checks. It is primarily useful for testing Celox’s FF lowering semantics.

pub fn native_force_support(self, enable: bool) -> Self

Enable native-image support for foreign force/release operations.

This emits extra combinational entry points, so ordinary simulator builds leave it disabled. Enabling it forces SIR O0 at build time so every store boundary needed to reapply a force remains intact.

pub fn opt_level(self, level: OptLevel) -> Self

Set the overall optimization level. Sets defaults for SIR passes, Cranelift options, and DSE policy. Per-pass overrides can be applied after.

pub fn enable_pass(self, pass: SirPass) -> Self

Enable a specific SIR pass, overriding the OptLevel default.

pub fn disable_pass(self, pass: SirPass) -> Self

Disable a specific SIR pass, overriding the OptLevel default.

pub fn optimize(self, enable: bool) -> Self

Enable or disable all SIRT optimization passes at once. Shorthand: true → OptLevel::O1, false → OptLevel::O0.

pub fn optimize_options(self, options: OptimizeOptions) -> Self

Set per-pass optimizer flags directly.

pub fn x86_slp(self, enable: bool) -> Self

pub fn cranelift_options(self, options: CraneliftOptions) -> Self

Set fine-grained Cranelift backend options.

pub fn regalloc_algorithm(self, algo: RegallocAlgorithm) -> Self

Set the register allocator algorithm.

pub fn enable_alias_analysis(self, enable: bool) -> Self

Enable or disable alias analysis in the Cranelift egraph pass.

pub fn enable_verifier(self, enable: bool) -> Self

Enable or disable the Cranelift IR verifier.

pub fn dead_store_policy(self, policy: DeadStorePolicy) -> Self

Set the dead store elimination policy.

pub fn tier_promotion(self, policy: TierPromotion) -> Self

Set when the tiered backend adopts background-compiled code.

pub fn live_signal( self, instance_path: Vec<(String, usize)>, var_path: Vec<String>, ) -> Self

Mark a signal as externally observable (live) for dead store elimination.

pub fn trace(self, trace: TraceOptions) -> Self

Configure compilation tracing options.

pub fn diagnostics(self, diagnostics: DiagnosticsOptions) -> Self

Configure diagnostics explicitly for this build.

pub fn diagnostics_from_env(self) -> Self

Import legacy CELOX_* diagnostics switches once at the API boundary.

pub fn trace_sim_modules(self) -> Self

pub fn trace_pre_atomized_comb_blocks(self) -> Self

pub fn trace_atomized_comb_blocks(self) -> Self

pub fn trace_flattened_comb_blocks(self) -> Self

pub fn trace_scheduled_units(self) -> Self

pub fn trace_pre_optimized_sir(self) -> Self

pub fn trace_post_optimized_sir(self) -> Self

pub fn trace_analyzer_ir(self) -> Self

pub fn trace_pre_optimized_clif(self) -> Self

pub fn trace_post_optimized_clif(self) -> Self

pub fn trace_native(self) -> Self

pub fn trace_mir(self) -> Self

pub fn trace_native_profile_block( self, function: impl Into<String>, block: u32, samples: u64, ) -> Self

Add one profile-selected native JIT block to state-layout feasibility analysis. The analysis is captured by Self::build_with_trace or Self::compile_native_with_trace from the exact merged SIR passed to native instruction selection.

pub fn trace_on_build(self) -> Self

pub fn false_loop( self, from: (Vec<(String, usize)>, Vec<String>), to: (Vec<(String, usize)>, Vec<String>), ) -> Self

Explicitly ignore a dependency between two signals.

pub fn true_loop( self, from: (Vec<(String, usize)>, Vec<String>), to: (Vec<(String, usize)>, Vec<String>), max_iter: usize, ) -> Self

Mark a dependency as a “true loop” and specify its convergence limit.

impl<'a> SimulatorBuilder<'a, Simulator>

pub fn new(code: &'a str, top: &'a str) -> Self

pub fn from_sources(sources: Vec<(&'a str, &'a Path)>, top: &'a str) -> Self

pub fn from_frontend( artifact: FrontendArtifact, ) -> SimulatorBuilder<'static, Simulator>

Low-level adapter hook for a source-independent frontend artifact.

Frontend crates should wrap this with an artifact-specific public API.

pub fn from_frontend_with_testbench( artifact: FrontendArtifact, sources: Vec<(&'a str, &'a Path)>, top: &'a str, ) -> Self

Low-level adapter hook for a Veryl native testbench whose $sv::Module instances resolve from an external frontend artifact.

pub fn build(self) -> Result<Simulator<DefaultBackend>, SimulatorError>

Compiles the Veryl source and constructs the simulator. Uses a custom native backend when its generated code matches the compilation target, and Cranelift for host-side cross-codegen builds.

pub fn build_cranelift(self) -> Result<Simulator<JitBackend>, SimulatorError>

Compiles using the Cranelift JIT backend.

pub fn build_interpreter( self, ) -> Result<Simulator<InterpBackend>, SimulatorError>

Compiles SIR, finalizes the state layout, and returns a simulator whose execution units run on the Tier-0 SIR interpreter instead of generated machine code.

This is the target of the all_backends! interp test arm. No code generation happens on this path: the simulator is ready as soon as the state layout is finalized, and every execution unit is driven by crate::interpreter::execute_unit against the same memory image ABI the compiled backends use.

pub fn build_tiered(self) -> Result<Simulator<TieredBackend>, SimulatorError>

Compiles SIR, finalizes the state layout, and returns a simulator that starts executing on the Tier-0 interpreter immediately while the host’s default compiled tier (native where available, Cranelift otherwise) is compiled in the background.

The first scheduler safe point after background compilation completes adopts the compiled code and moves the live memory image across without translation. If background compilation fails the simulator keeps running on the interpreter.

pub fn compile_native(self) -> Result<NativeCompilation, SimulatorError>

Compiles using the selected native code-generation architecture.

pub fn compile_native_with_trace( self, ) -> Result<(NativeCompilation, CompilationTrace), SimulatorError>

Compiles using the selected native code-generation architecture and returns the trace captured from the same native compilation.

Unlike Self::build_with_trace, this method never loads or runs the generated machine code, so it is available during cross-codegen.

pub fn build_x86_64(self) -> Result<Simulator<NativeBackend>, SimulatorError>

Compiles for an x86-64 target and initializes the simulator. This includes Cargo cross-builds whose target is x86-64.

pub fn build_native(self) -> Result<Simulator<NativeBackend>, SimulatorError>

Compiles using the native backend selected for the compilation target.

pub fn build_native_from_image( self, image: NativeProgramImage, ) -> Result<Simulator<NativeBackend>, SimulatorError>

Load a previously generated native image without running source parsing, SIR construction, layout, or native machine-code generation here.

This is the execution-side half of the host-codegen/QEMU workflow: source-independent runtime metadata and the semantic testbench are restored from image, while the target machine code is taken entirely from it.

pub fn build_wasm(self) -> Result<Simulator<WasmBackend>, SimulatorError>

Compiles using the Wasmtime WASM backend.

pub fn run_test(self) -> Result<TestResult, SimulatorError>

Compiles and runs a native testbench (#[test] module).

pub fn run_test_cranelift(self) -> Result<TestResult, SimulatorError>

Compiles and runs a testbench using the Cranelift JIT backend.

pub fn run_test_native(self) -> Result<TestResult, SimulatorError>

Compiles and runs a testbench using the custom native backend.

pub fn run_test_detailed(self) -> Result<TestResultDetailed, SimulatorError>

Compiles and runs a native testbench, returning assertion results observed before the test finishes or stops on a fatal failure.

pub fn build_with_trace(self) -> CompilationTraceResult

Compiles the Veryl source and constructs the core logic simulator, while capturing compilation trace data as configured by TraceOptions.

impl<'a> SimulatorBuilder<'a, Simulation>

pub fn build(self) -> Result<Simulation, SimulatorError>

Compiles the Veryl source and constructs the timed simulation wrapper.