Hey! My plug-in won’t load in Adobe Reader

| No Comments

You completed your Integration Key License Agreement for Adobe Reader, you got your certificate, followed all of the steps exactly and your plug-in still won’t load. Why?

Richard Relph, a Senior Computer Scientist at Adobe, has compiled a list of the four common issues that result in a plug-in failing to load and forcing Reader to quit.

1: User error – Signing the plug-in

Signing the plug-in with the tools we have in the field can be an error-prone process. It is absolutely essential that the instructions be followed very carefully. The most common mistake is to "rebuild" instead of "build" the plug-in after computing the signature value, but other mistakes are certainly possible.


The most common problem is a plug-in not being compiled for Reader. Reader does not support the full set of APIs that Acrobat does. The compile-time switch forces the plug-in loading code to NOT fetch certain "HFTs" (an HFT is a table of pointers to APIs) that aren’t available in Reader. If the plug-in loading code (which is a part of the plug-in) wasn’t compiled with READER_PLUGIN, it will attempt to fetch an HFT that Reader doesn’t support, the loading code will return an error, and loading will stop.


Unfortunately, in the samples that ship with the Acrobat SDK for Acrobat 8, we didn’t correctly deal with one particular HFT when READER_PLUGIN is defined. If the developer is attempting to compile or modify a sample we shipped with the Acrobat 8 SDK, besides setting READER_PLUGIN, they will have to modify AcroDspOptions.rsp, which is located in the Samples folder of the SDK. In that file is a /D that assigns a specific version to the ACRO_COLOR HFT. That forces the loading of the HFT, even in the presence of READER_PLUGIN, which will prevent the plug-in from working in Reader. Delete the line in the RSP file.

4: DLL Hell

Some developers have a development machine with Acrobat and Visual Studio and another machine that has just Reader. The problem is that the machine with just Reader doesn’t have all the C Run-time DLLs that are installed "for free" when Visual Studio is installed. The solution to this is to either build the plug-in such that the C Run-time libraries are statically linked in to the plug-in (my preferred solution), or to ensure that the necessary DLLs are loaded on to the target machine with the plug-in. (Yes, this would have to be done as part of the plug-in installation process for end-user machines.) Sometimes this isn’t an issue, because Reader itself installs some of the C Run-time DLLs. Other times, it is because the plug-in was built using a newer or slightly different variation (debug vs. release or multi-threaded vs. single-threaded) of the run-time libraries.

Richard recommends that new Reader developers use the Visual Studio Plug-in Wizard to create a "trivial" Reader plug-in (say with a help item and nothing else). By clicking on the "Reader" check box at the appropriate step in the wizard, problems #2 and #3 and #4 above are avoided. That only leaves problem #1. Once the developer is successful in building a trivial plug-in that works with Reader, especially including the signing process, they have the confidence and experience necessary to move on to signing their own "real" plug-ins and knowing that whatever problems remain aren’t due to any "issues" with the key we’ve sent them or the tools they’ve never used before.