dart_wellen 0.1.3

Wellen bindings for ROHD with VCD, FST, and GHW reading and VCD writing.

dart_wellen

dart_wellen exposes the Rust Wellen waveform parser to Dart through Flutter Rust Bridge. It reads VCD, FST, and GHW waveforms and adapts them to the shared rohd_hierarchy and rohd_waveform contracts.

Capabilities

Operation	Native	WebAssembly
Read VCD, FST, or GHW from a file path	Yes	No
Read VCD, FST, or GHW from bytes	Yes	Yes
Query hierarchy and selected signal data	Yes	Yes
Write VCD	Yes	No
Write FST or GHW	No	No

Writing is deliberately separated from the cross-platform reader because it uses dart:io.

Installation

Add the package to a Dart or Flutter package:

dependencies:
  dart_wellen: ^0.1.3

The package owns its bridge version and matching artifacts. Prepared local packages and hosted archives include generated Dart bindings and the browser runtime under web/pkg. Git dependencies retrieve those same files from a checksummed release bundle for the selected package version, without compiling dependencies:

python3 <resolved-dart_wellen-root>/tool/bridge_artifacts.py install

Python 3 is required. The installer verifies package/bridge versions and SHA-256 checksums. For Git installs it downloads the selected version's release JSON metadata before its archive, checks the version/profile/inventory, then verifies all downloaded bytes. Hosted and prepared local packages include this metadata as tool/bridge_artifacts.build.json and verify offline. Compiled-binary checksums are generated by the producer, not pinned from a different machine's build in the source contract. Missing metadata or an unavailable versioned bundle fails explicitly. Git dependencies must use a release tag or commit that declares a package version with a matching dart-wellen-<version> GitHub Release. General validates release packaging but does not publish bundles; run Release Checks with publish_bundle enabled to create the versioned bridge release. Pub.dev publication remains a separate maintainer action.

Development consumers can instead select the successful General CI artifact matching their resolved Git commit. General uploads the complete dart-wellen-consumer-artifacts payload with generated bindings, runtime, and build checksum metadata; this ephemeral artifact is not a GitHub Release. Hosts copy web/pkg, including license notices, into ignored web staging output and load its JavaScript/WASM pair. They must not pin a separate bridge version or retain an older runtime when changing dependency sources. The packaged WASM profile is explicitly release, independent of whether the embedding Flutter application runs in debug or release mode.

Native applications additionally need a matching native library. The package requires Dart 3.9.2 or newer. Artifact production belongs to this repository, never an embedding application's build. See the consumer artifact release procedure.

Example

The command-line example reads metadata from a VCD, FST, or GHW file. From a prepared repository checkout, build the matching native bridge and run it from the package directory:

make rust-native
cd packages/dart_wellen
dart run example/main.dart /path/to/waveform.vcd

For other native deployments, provide the matching native library as described above; the published package does not include it.

Reading a Waveform

WellenReader is a convenience API for native, file-backed workflows:

import 'package:dart_wellen/dart_wellen.dart';

Future<void> inspectWaveform(String path) async {
  await WellenReader.init();
  final reader = WellenReader();

  try {
    final metadata = await reader.loadFile(path);
    final structure = await reader.getStructure();
    final signals = await reader.getSignalData(
      ['top.clk', 'top.counter'],
      startTime: 0,
      endTime: metadata.endTime,
    );

    print('${structure.modules.length} top-level modules');
    for (final waveform in signals) {
      print('${waveform.signalId}: ${waveform.data.length} changes');
    }
  } finally {
    await reader.close();
  }
}

WellenSignalWaveformApi implements the SignalWaveformApi contract used by ROHD viewers. Use loadFile on native platforms or loadBytes after the generated Wellen WebAssembly module has been initialized in a browser:

final api = WellenSignalWaveformApi();
await api.loadBytes(bytes, fileName: 'simulation.fst');

final hierarchy = await api.getModuleStructureOnly();
final waveforms = await api.getWaveformData(
  signalIds: ['top.clk'],
);

Only one waveform is held by the Rust bridge at a time. Creating multiple Dart reader or API objects does not create independent Rust waveform stores.

Writing VCD

Native code that writes waveforms must import the IO-specific library:

import 'package:dart_wellen/dart_wellen_io.dart';

• WellenWriter writes registered SignalOccurrence values directly to a VCD file.
• WellenWaveDumper provides a manual adapter that registers signals and records timestamped value changes.

The adapter is not automatically attached to the ROHD simulator. Callers must register signals and forward simulation changes themselves. Selecting WaveFormat.fst currently throws an unsupported-format error.

Repository Development

This package is a member of the ROHD Wave Viewer Pub workspace. From the repository root:

# Resolve the workspace.
flutter pub get

# Generate both Dart and Rust Flutter Rust Bridge bindings.
make dart

# Build native or WebAssembly bridge artifacts.
make rust-native
make wasm

# Run root and workspace-member tests.
make test

The generator configuration is packages/dart_wellen/flutter_rust_bridge.yaml. Generated Dart bindings are written to packages/dart_wellen/lib/src/rust/; the generated Rust counterpart is rust/wellen_bridge/src/frb_generated.rs. Do not invoke the generator with ad hoc output paths.

See ARCHITECTURE.md for package boundaries and the repository build guide for the complete build matrix.

---

Copyright (C) 2024-2026 Intel Corporation SPDX-License-Identifier: BSD-3-Clause