# C++ Plug-ins for Illustrator

A plug-in is native code, built with the Illustrator SDK, that Illustrator loads at startup. It can add tools, menu items, live effects, file formats, and notifiers, and it runs much faster than ExtendScript on large documents. It is also the most work to build, ship, and keep current, because it must be rebuilt for each major Illustrator version and each OS.

Choose a plug-in only when a script or CEP panel cannot do the job: a custom tool that reacts to mouse drags, a live effect, a file format, events scripts cannot see, or performance on thousands of objects.

## Getting the SDK

- Sign in to the Adobe Developer Console (`developer.adobe.com/console`), open the downloads area, and pick the Illustrator SDK for your OS. Use the SDK whose version matches the Illustrator major version you target.
- The download holds headers, documentation (getting started guide, API reference, porting notes), sample plug-ins under `samplecode/`, and build tools.
- The getting started guide lists the supported compiler versions: Visual Studio on Windows, Xcode on macOS. Use those versions; newer ones may need project upgrades.

## Build and Load

1. Open a sample project (for example the Annotator sample) and build it unchanged first to prove the toolchain.
2. The output is an `.aip` file on Windows and an `.aip` bundle on macOS.
3. Load it by copying it into Illustrator's `Plug-ins` folder, or better, point Illustrator at a development folder: Preferences > Plug-ins & Scratch Disks > Additional Plug-ins Folder, then restart Illustrator.
4. Plug-ins load only at startup. Quit Illustrator before replacing the `.aip`.

## PiPL Resources

Every plug-in carries a PiPL (plug-in property list) resource with its name, entry point, and required Illustrator version. Since Illustrator 25.1, PiPL resources are generated by a script in the SDK's tools folder instead of being edited by hand in resource files (Adobe developer blog, "An Illustrator 25.1 Update for Plugin Developers"). Follow the sample projects' build steps, which run the generator.

## Entry Point and Messages

Illustrator calls one exported function with a caller, a selector, and a message pointer. The SDK samples share a `common` folder: `Main.cpp` exports the entry point, and the `Plugin` base class routes caller and selector pairs to virtual methods, so start from a sample rather than writing it yourself:

```cpp
// Shape of the entry point the SDK samples export; the base class routes
// caller/selector pairs to virtual methods such as StartupPlugin, ShutdownPlugin,
// GoMenuItem, Notify, and the tool handlers.
extern "C" ASAPI ASErr PluginMain(char* caller, char* selector, void* message);
```

- **Startup and shutdown**: acquire suites, add menus, tools, and notifiers at startup; release everything at shutdown.
- **Suites**: Illustrator's API is a set of versioned function tables (suites) such as the art, path, document, menu, tool, notifier, and timer suites. Acquire them through the basic suite the host passes in, check the returned error, and release them when done.
- **Notifiers**: subscribe to events such as selection changes or document open and close; keep handlers fast.
- **Timers**: for periodic work; never block the UI thread.

## User Interface

Native plug-ins add tools and menu items directly. For panels with complex controls, a common design pairs the plug-in with a CEP panel that sends it events, so the UI is HTML and the heavy work is native. Check the SDK samples for your version for the supported UI approach, since this has changed across releases.

## Debugging

- Build the Debug configuration and set Illustrator as the program to launch (Visual Studio: project Debugging settings, Command; Xcode: the scheme's Run executable), or attach to a running Illustrator.
- Keep a copy of a test document; native crashes take Illustrator down with them.
- Log to a file in a temp folder rather than showing alerts in loops.

## Versions and Distribution

- Rebuild and retest for each major Illustrator release; read the SDK's porting notes for API changes.
- Ship one build per OS. On macOS, sign and notarize the bundle so Gatekeeper allows it to load. On Windows, sign the binary with a code-signing certificate.
- Document the supported Illustrator versions and OSes in a compatibility table (see publishing-docs.md).
- UXP plugins are coming to Illustrator (public beta by Spring 2027). For new projects that only need panels and scripting, consider a CEP panel now and UXP later; keep native code for what only native code can do.

## Checklist Before Release

- [ ] Builds cleanly in Release for each OS and the targeted Illustrator major version
- [ ] Loads from a clean Additional Plug-ins Folder and from the `Plug-ins` folder
- [ ] Startup and shutdown release every suite and remove every notifier and timer
- [ ] Tested on a copy of a large real document, with undo working after each action
- [ ] Signed (and notarized on macOS)
- [ ] Install, uninstall, and compatibility documented