Hack 97 Tool Up for Acrobat Plug-In Development

Compile Acrobat plug-ins on Windows using GCC .

The Acrobat API gives you the most powerful tools for accessing and modifying PDF data. The typical way to access the API is with an Acrobat plug-in.

A plug-in is a DLL (on Windows), and it is created from C or C++ source code using a compiler such as Microsoft's Visual C++ or the GNU Compiler Collection (GCC). In this hack, we'll explain how to install the free (and fabulous) GCC compiler on Windows. Then, we'll install the Acrobat SDK. Finally, we'll build a sample plug-in using GCC.

You can also compile Acrobat plug-ins for Macintosh and Unix. Adobe provides separate SDKs for each platform. Typically, you compile Macintosh Acrobat plug-ins using Metrowerks CodeWarrior.

7.6.1 Install GCC on Windows with MinGW and MSYS

You can get GCC on your Windows machine using a couple of different methods . I prefer using the packages provided by the MinGW (http://www.mingw.org) folks. They provide a set of installers that you can choose from according to your needs. They also provide software updates that you can unpack and copy on top of the original installation.

Visit http://www.mingw.org/download.shtml and download the following packages. Each file is named according to its version. If newer versions are available under the Current section of the web page, use those instead. For example, download MSYS-1.0.10.exe instead of MSYS-1.0.9.exe .

MSYS-1.0.10.exe

MinGW-3.1.0-1.exe

gcc- core -3.3.1-20030804-1.tar.gz

gcc-g++-3.3.1-20030804-1.tar.gz

First, install MinGW. Throughout this discussion, I'll assume you installed MinGW on the C : drive so that you ended up with C:\MinGW\ .

Next, install MSYS. Throughout this discussion, I'll assume you installed MSYS on the C : drive so that you ended up with C:\msys\1.0\ . The MSYS post-install script will configure MSYS to your environment. When it asks where MinGW is installed, tell it C:/MinGW (note the forward slash).

MSYS gives you many of the GNU (http://www.gnu.org) tools that are common on Linux systems, such as grep, less, and diff. MSYS also gives you a Bourne shell (a.k.a. command prompt ) environment that makes a Linux user feel more at home. In fact, it creates a home directory for you; in my case it is C:\msys\1.0\home\Sid Steward\ . When you run MSYS (Start Programs MinGW MSYS msys), a colorful command prompt opens, and it opens in your home directory by default. It is like a little slice of Linux, right there on your Windows machine. Run dir and it doesn't understand. Use ls instead. Run pwd and you'll see that even the filesystem looks different. Your current directory is /home/Sid Steward/ , not C:\msys\1.0\home\Sid Steward\ . You can access the traditional DOS drive names like so:

  cd "/c/Program Files  " 

Test whether MSYS can find MinGW by running:

  $ gcc --version  

If it replies command not found , MSYS can't see MinGW. In that case, you will need to edit the text file C:\msys\1.0\etc\fstab so that it includes the line:

   c:/MinGW   /mingw 

Note the forward slashes , and replace c:/MinGW with the location of MinGW on your machine.

To access the MSYS and MinGW tools from the Windows command prompt, you will need to add C:\msys\1.0\bin and C:\MinGW\bin to your Windows Path environment variable. Access environment variables by selecting Start Settings Control Panel System Advanced Environment Variables.

Finally, we'll apply the 3.3.1 updates to the installation. Copy the *.tar.gz files to your MinGW directory (e.g., C:\MinGW\ ). Open the MSYS shell ( Start Programs MinGW MSYS msys ) and then change into the /mingw directory ( cd /mingw ). Unpack the *.tar.gz archives like so:

 Sid Steward@GIZMO /mingw $  tar -xzf gcc-core-3.3.1-20030804-1.tar.gz  Sid Steward@GIZMO /mingw $  tar -xzf gcc-g++-3.3.1-20030804-1.tar.gz  

Now, test to make sure the upgrades worked by checking the versions. For example:

 Sid Steward@GIZMO /mingw $  gcc --version  gcc.exe (GCC) 3.3.1 (mingw special 20030804-1) 

Success!

7.6.2 Download and Install the Acrobat SDK

The full Acrobat SDK from Adobe includes documentation, samples, and API header files. Presently, only (fee-paying) ASN Developer members can download the full Acrobat 6 SDK. So, we'll download the freely available Acrobat 5 SDK instead. This free download does require that you sign up for a (free) ASN Web Account.

Visit http:// partners .adobe.com/asn/acrobat/download.jsp, and download the Acrobat 5.0 Full SDK Installation. For Windows, it is a zipped -up installer named acro5sdkr4.zip .

In addition to the Acrobat SDK documentation, you should also download the latest PDF Reference from http://partners.adobe.com/asn/tech/pdf/specifications.jsp.

Unzip, and then run the installer. Throughout this discussion, I'll assume you installed the SDK in a directory named C:\acro5sdkr4\ .

Open C:\msys\1.0\etc\fstab in a text editor and add this line (note the forward slashes):

   C:/acro5sdkr4   /acro5sdkr4 

Mapping Windows directories to MSYS directories like this makes life easier in MSYS. Regardless of where you installed the SDK, its location in MSYS is always /acro5sdkr4 . We'll take advantage of this fact in our plug-in sample project. It expects to find the Acrobat API headers at /acro5sdkr4/PluginSupport/Headers/Headers/ .

7.6.3 Download and Install Our Sample Plug-In

The Acrobat SDK Windows installer comes with many sample plug-in projects, but they all use Visual C++ project files. Visit http://www.pdfhacks.com/jumpsection/ and download jumpsection-1.0.tar.gz , which is the source code for our jumpsection Acrobat plug-in [Hack #13] . It demonstrates the basic elements of an Acrobat plug-in project built using MinGW.

Move jumpsection-1.0.tar.gz to your MSYS home directory and unpack it in MSYS like so:

 Sid Steward@GIZMO ~ $  tar -xzf jumpsection-1.0.tar.gz  

This creates a directory named jumpsection-1.0 . Change into this directory and compile jumpsection using make :

 Sid Steward@GIZMO ~ $  cd jumpsection-1.0  Sid Steward@GIZMO ~/jumpsection-1.0 $  make  

make will use the instructions in Makefile to create the Acrobat plug-in jumpsection.api . When it is done, copy jumpsection.api to the Acrobat plug_ins directory [Hack #4] and restart Acrobat to test it. It works in both Acrobat 5 and Acrobat 6. It won't load in Reader.

This toolset is the bare minimum you will need to build Acrobat plug-ins. To develop plug-ins, you will also need a good text editor such as vim [Hack #82] or Emacs (http://www.gnu.org/software/emacs/windows/ntemacs.html). Or, you might prefer a GUI environment such as Dev-C++ (http://www. bloodshed .net/devcpp.html).