Skip to content

Publishing a plugin

There is no plugin store. A plugin is a folder, and sharing it is zipping that folder and sending it, however you like: a download link, a chat, a USB stick.

Before you share it

  • Give every tool examples. They are the only test the person receiving your plugin has. Two or three per tool, including one for the empty or failing case, each pinning its own input so it answers the same everywhere.
  • Write the description for the AI. For a tool it is the only thing the AI reads when deciding whether to call it: what it does, and when to use it.
  • Declare what the code really does. If it reads files outside the project, uses the network, touches hardware or runs other programs, list files, network, hardware or subprocess under permissions. Nothing checks this for you; see below.
  • Set a version. It is shown in the Plugins dialog, so the person you send it to can tell an update from what they have.
  • Choose a license. Your plugin is yours to share or sell under any license you like. Put a LICENSE file in the folder so the person receiving it knows what they may do with it. Nothing from a Whittl template needs crediting: the templates and the plugins that ship with Whittl are MIT No Attribution.

Where the folder is

A plugin you made in a Whittl project was installed into your plugins folder when its Test Run passed: Edit > Plugins > Manage Plugins..., then Open folder. Zip the plugin's folder from there.

Leave out the file called .whittl_project. It links the plugin to the project you built it in, which the person receiving it does not have.

What the person receiving it does

  1. Unzip it into their plugins folder (Manage Plugins..., Open folder) and press Refresh.
  2. Select it and read the details: the description the AI will see, what the plugin contributes, and the access it declares.
  3. Press Run examples to see them pass on their machine.
  4. Tick it on, with Enable plugins ticked as well.

To update, unzip the new version over the old folder. Two folders holding plugins with the same name are both refused (the Plugins dialog says so), so delete or replace the old one rather than keeping both.

Permissions are a promise, not a lock

The access you declare is shown to the person installing your plugin, marked "declared, not enforced". Whittl does not confine a plugin to it. A tool runs in its own process with the same access as the person running Whittl, and a panel, menu action or hook runs inside Whittl itself. The checks Whittl does (running a tool's examples, building a panel in an invisible copy of Qt first, switching off a hook that hangs) protect against a plugin that is broken, not one that was written to do harm.

So the honest rule for both sides: share plugins you would be happy for someone to read, and read a plugin before you enable it. A plugin is exactly as trustworthy as the person who wrote it.