What is a Plugin?

Concept

Sawmill’s core is tool-agnostic. It knows how to display, filter, and triage log messages, but it does not know how to parse any specific tool’s output. Plugins bridge that gap.

A plugin is a separate Python package that teaches sawmill how to read a particular tool’s log format. Each plugin is installed alongside sawmill and discovered automatically at runtime.

What a plugin provides

A plugin implements one or more hooks from the SawmillHookSpec interface:

can_handle(path) -> float

Detection — examine a file and return a confidence score (0.0 to 1.0) indicating how well this plugin can parse it.

load_and_parse(path) -> list[Message]

Parsing — open the file, parse every line, group multi-line messages, extract severity and message IDs, and return a flat list of Message objects.

get_severity_levels() -> list[dict] (required)

Define the tool’s severity levels with id, name, level (int), and style (Rich format string). Levels must be consecutive integers starting at 0 (lowest severity).

get_filters() -> list[dict]

Pre-defined filter categories (e.g. timing, drc, synth) that users can activate with --category.

extract_file_reference(content) -> FileRef | None

Extract source file and line number references from message content.

get_grouping_fields() -> list[dict]

Declare custom grouping dimensions (beyond the defaults of severity, id, file, and category).

Discovery

Plugins are discovered via Python entry points under the sawmill.plugins group. A plugin’s pyproject.toml declares itself like this:

[project.entry-points."sawmill.plugins"]
vivado = "sawmill_plugin_vivado:VivadoPlugin"

After installation (pip install sawmill-plugin-vivado), sawmill finds the plugin automatically.

List installed plugins:

$ sawmill --list-plugins

Show plugin details (severity levels, filters, hooks):

$ sawmill --show-info --plugin vivado

Auto-detection

When you run sawmill logfile.log without --plugin, sawmill asks each installed plugin “can you handle this file?” by calling can_handle(path). The plugin with the highest confidence score (>= 0.5) is selected.

  • If no plugin has confidence >= 0.5, sawmill reports an error.

  • If multiple plugins tie at >= 0.5, sawmill reports a conflict and asks you to use --plugin to disambiguate.