Exporting coverage

At the end of a simulation, coverage should be exported for later viewing or merging. Bucket supports several on-disk formats:

Format	Extension	Typical use
Archive	.bktgz	Primary format for the viewer
SQL	.db	Legacy storage and regression databases
JSON	.json	Human-readable interchange and debugging

From Python

    # In your testbench — MyCvg is your Covertop subclass (NAME/DESCRIPTION set on the class)
    self.my_cvg = MyCvg(log=self.log)

    def export_coverage(self):
        # Context hash is stored with the coverage and used to validate merges.
        # An empty string can be provided instead.
        context_hash = Repo().head.object.hexsha

        readout = PointReader(context_hash).read(self.my_cvg)

        # Preferred: write a viewer archive
        ArchiveAccessor("test_2356.bktgz").write(readout)

        # Or write SQL / JSON
        SQLAccessor.File("test_2356.db").write(readout)
        JSONAccessor("test_2356.json").write(readout)

See example/example.py for a complete export and merge workflow.

From the command line

Readout sources are specified with -r / --read (repeatable). If the record index is omitted, all records from the source are read. If the type is omitted, it is inferred from the file extension (.db → sql, .json → json, .bktgz → archive).

Valid read forms:

• <record>@<type>:<URI>
• <record>@:<URI>
• <type>:<URI>
• <URI>

Examples:

# Export a simulation database to a viewer archive
python -m bucket write -r sql:./test_2356.db archive -o test_2356.bktgz

# Export to JSON
python -m bucket write -r archive:./run.bktgz json -o run.json

# Print a summary to the terminal
python -m bucket write -r archive:./run.bktgz console --summary

# Generate standalone HTML with the embedded viewer
# (needs a source checkout and Node.js; not available from a pip install)
python -m bucket write -r archive:./run.bktgz html -o index.html

# Generate a human-readable HTML coverage report
# (same checkout/Node.js requirement as `html`)
python -m bucket write -r archive:./run.bktgz report -o report.html

---

Merging coverage

After a regression, coverage from separate simulations can be merged before viewing. At present a simple merge is performed, producing one combined readout. Records must be compatible (same covertree definition) to merge successfully.

From Python

from bucket.rw import ArchiveAccessor
from bucket.rw.common import MergeReadout

readout_a = next(ArchiveAccessor("test_a.bktgz").reader().read_all())
readout_b = next(ArchiveAccessor("test_b.bktgz").reader().read_all())
merged = MergeReadout(readout_a, readout_b)
ArchiveAccessor("merged.bktgz").write(merged)

ArchiveAccessor.merge_files() provides a convenience wrapper for merging multiple archives on disk.

From the command line

Use --merge / -m to merge all read sources before writing:

python -m bucket write -r sql:./test_2356.db -r sql:./test_87263.db -m archive -o merged.bktgz
python -m bucket write -r archive:./a.bktgz -r archive:./b.bktgz -m sql -o merged.db

In the viewer

You can also merge without writing a file first:

• Load multiple archives and choose Merge into one in the load dialog, or
• Use Edit → select two or more records → Merge Selected

Merged results exist only for the current session. Use Export in the viewer to save the merged record as .bktgz or JSON, or as an HTML coverage report.

---

Prev: Adding coverage to the testbench
Next: Reading and Writing