The plugin file and its manifest

The file

A plugin file is the plugin crate built as a C dynamic library, renamed to NAME.oxp. Inside it are the plugin’s code and its manifest, in a section of its own (oxg_manifest; oxgmanif on Windows, whose section names hold eight characters). OxiGuitar reads that section with a parser of library files, so it learns what the plugin adds without running any of its code. Plugin files carry no signature: OxiGuitar checks that the file is whole (a truncated download is refused before it is loaded), that it is a library for this system and processor, and that it asks for an interface version OxiGuitar has.

You never write the section yourself: you write manifest.json beside Cargo.toml, and export_plugin! puts its bytes in the section when the file is built.

manifest.json

The template’s:

{
  "interface": "1.1",
  "id": "yourname.example",
  "name": "Example",
  "version": "0.1.0",
  "description": "Opens Example tab files (.extab), counts the notes on each string of the open score, and names notes for other plugins.",
  "authors": ["Your Name"],
  "license": "MIT OR Apache-2.0",
  "homepage": "https://example.org/your-plugin",
  "formats": [
    {
      "id": "extab",
      "name": "Example tab",
      "extensions": ["extab"],
      "read": true,
      "write": true,
      "signatures": [{ "at": 0, "text": "EXAMPLE TAB" }]
    }
  ],
  "services": [
    { "interface": "note-names", "id": "example", "name": "Example note names" }
  ],
  "tabs": [
    { "id": "statistics", "title": "Statistics", "area": "right" }
  ],
  "events": ["score"]
}

Unknown keys are refused when you build and ignored when OxiGuitar reads. The test export_plugin! adds fails on a key the SDK doesn’t know, so a typing mistake ("servces") shows up in cargo test. An older OxiGuitar reading a newer plugin’s manifest skips keys it doesn’t know, so new keys never stop a plugin from loading.

A manifest is at most 1 MiB. Real ones are a few hundred bytes.

Conditions

"conditions": { "os": ["linux"], "arch": ["x86_64", "aarch64"], "display": ["wayland"] }

Every list given must hold the running system’s value; an empty or missing list allows any.

A plugin whose conditions don’t hold is listed in Tools → Plugins with the reason, and never loaded. A plugin file is already built for one system and processor, so you need os and arch only for a file that would load but can’t work (a universal macOS file that works on Apple Silicon only, say). display matters for plugins that talk to the windowing system. Services have conditions of their own, beside the plugin’s.

cpu lets you ship a faster build beside a plain one. Build the plugin twice, with the same id and version: once plainly, and once with -C target-cpu=x86-64-v3 and "cpu": ["avx2", "fma"] in its manifest. On a processor without those features that file can’t be used and the plain one is; where both can be used, the one needing more features is. A feature name OxiGuitar doesn’t know counts as missing, so a build is never loaded on a guess.

Rules the checks enforce

OxiGuitar refuses a manifest that breaks these, and Tools → Plugins names the first problem; cargo test (through export_plugin!) names them all:

• the ids are valid and unique: the plugin’s; each format’s; each instrument’s; each tab’s; each service’s within its interface;
• names and tab titles aren’t empty;
• a format reads or writes, and one that reads has at least one signature;
• extensions are lowercase and without the dot ("gp5", not ".GP5");
• tabs and events need interface 1.1.

cargo test also checks what only the code can tell:

• the manifest asks for an interface this SDK has (1.0 or 1.1), and its version is the crate’s;
• it has no key the SDK doesn’t know;
• every format, service and tab declared is implemented, and every tab’s contents can be shown.