Adobe PDF Library

Installing the Software

Windows

Adobe PDF Library is delivered as a self-extracting executable file (EXE). You can download the latest software release package from your secure FTP user account on the Datalogics FTP site (ftp.datalogics.com).  You can download it to any local or server directory and install it from there.

By default the process will install the files to a series of directories under APDFL15.0.4. You can use “APDFL” or create your own directory name and location. The product installs to five subfolders, CPlusPlus, Documentation, DotNET, Java, and Resources. This applies to both Windows and Linux/Unix machines.

The CPlusPlus directory stores the core library of C language programs for the Adobe PDF Library as well as supporting materials.  The Dynamic Link Library (DLL) files are stored in the Binaries directory, and the C++ sample programs in Sample_Source.  You will also find Header files in the Include directory and a variety of resources in the Resources folder, including fonts and CMap files that you can use for rendering and indexing with PDF files.  You will probably want to distribute these files with any applications you create. The sample programs and library files related to the Java and Microsoft .NET Interfaces are found in the Java and DotNET subfolders.

Running the installation process

If you are already using Adobe PDF Library and decide to install a newer version, plan to install the new software release in a new directory. That is, when you install a new release for APDFL it will not overwrite or otherwise conflict with previous versions of the same product. You will have two complete installations of the product in two different places on your machine, the new version and your original.

After you complete the installation process, the result should look something like this:

Windows install

If you are transitioning from an earlier version of the Adobe PDF Library to the latest release, make sure that any applications that you already built and that rely on the Library point to the correct directories for the latest version of the software.  Also, make sure that you move any font files, CMAP files, or other custom resources from your old APDFL installation directories to the new file folders, if necessary, so that any applications you built using the Library will be able to find these files.

Feel free to delete the files and folders for the earlier installation of the product if you like. It is not necessary to uninstall earlier versions of the software or delete registry keys.

The Folder Structure

Make sure that the files installed properly. You should see five top level directories, for C++, Java, and .NET files, plus a folder for Documentation and another for Resources.

The CPlusPlus directory holds the original C language interface to the Library, including the lib files, header files, and sample program files. For Unix applications, the corresponding .so files are included. For Mac systems, the framework files are included.

The other folders hold the .NET and Java interfaces to the Library. The Java and DotNET folders also hold an independent copy of the core C language DLL files and sample program files.

The Documentation directories each provide a link to the online programming reference for Java or .NET. In the Java or DotNET folder, click Index.html to open an HTML reference for the APIs built using Doxygen.

The Resource folder holds mostly fonts needed by the Library or applications based on the Library, as well as input files used by the sample programs and other items.

Windows install

This folder should be the first location to check if your application encounters problems rendering document text, or any other font issue. This is especially true if the document references fonts but does not include them. The Resource folder is where an Adobe PDF Library application will look to find necessary font information if it is not embedded in the PDF file itself.

Color. A color profile (.icc) file is used to manage colors used in a PDF document, to make sure that the colors for text or graphics in a PDF are the same regardless of the hardware or software used to display, edit, or print that file. The .icc file is normally embedded within the PDF document itself, though color profiles are also provided with software applications and hardware devices, like printers.

joboption. The joboption file is provided by Adobe Systems and is used to define the properties of a PDF document to be generated. It is used with the standard plug-ins provided with the Adobe PDF Library.

CMAP, Font, and Unicode. CMAP refers to a type of font called a Character Map. Some fonts in PDF files use predefined mappings between character encodings and specific, predefined character identifier sets. These mappings (CMaps) are a standard part of the PDF specification. Because of their large size, these character maps are stored in files that are provided with Acrobat and other Adobe Systems products, and are usually referenced by name from PDF files when needed.
Unicode is an international font standard for coding and representing text digitally. The Unicode font set contains all of the characters for most of the alphabets and writing systems in the world, more than 120,000 characters used in 129 modern and historic alphabets and scripts. Besides western alphabets, Unicode contains characters for Multi-byte character sets, including the Chinese, Japanese, Korean, and Vietnamese writing systems.

Managing installed files

The Adobe PDF Library is more of a toolbox than an application, so the installation process does not automatically place DLL files in known locations such as C:\Windows\System32. The installation also does not add or change Windows registry keys.  We assume that when you build your own Library application, you will allocate resources in your own setup procedures, and make their location or locations known to Adobe PDF Library.

You do not need to define any environment variables for Windows before you build your own applications using Adobe PDF Library.

When installing an update to Adobe PDF Library, be sure to propagate the new library and DLL files to any locations where previous copies may be found.  Verify that your application build procedures reference the correct version number as seen in the Adobe PDF Library filenames, such as DL150PDFL.dll.

When you deploy the Adobe PDF Library, the components you need depend on the language interface you use.

Digital signatures in the Dynamic Link Library files

Each DLL file provided with the Adobe PDF Library contains a digital signature. The signature ensures the DLL is authentic; the DLL files were provided by Datalogics and have not been altered. The DLLs for the Java and .NET interface com-datalogics-DL150PDFL.dll, DL150PDFLINVOKE.dll, and Datalogics.PDFL.dll are strong-named assemblies that can be installed in the Global Assembly Cache. Right click on a DLL file, select Properties, and open the Digital Signatures tab to verify that a digital signature is in place for a file.

Max speed libraries

The DLL files contained in the Binaries/MaxSpeedLibs directory trade floating-point strictness and file size in favor of run time performance. They are compiled using settings that favor speed, such as using the SS2 instruction set and the “Fast” floating point model. These libraries perform 15% to 20% faster than the regular libraries. The improvements are most obvious during render and color conversion operations.

Setting up the Java and Microsoft .NET interfaces for Windows

For your convenience, we provide copies of the DLL files for the Adobe PDF Library and for use with the Java and .NET Interfaces when you install the Adobe PDF Library.  That way, when you install this Interface the system is ready for you to get started.  You don’t have to copy these DLL files yourself.

So the DLL files that appear in your Binaries directory for the Adobe PDF Library will match the DLL files that appear in the Binaries directories under Java and DotNET directories for use with the Java and .NET Interface.  But we provide four other DLL files as well.  Two of them are interfaces that allow Java or .NET programs that you create to call the Adobe PDF Library core functions:

  • com-datalogics-DL150PDFL.dll is the interface for Java
  • DL150PDFLPINVOKE.dll is the interface for .NET programs

Both of these DLL files communicate with Datalogics.PDFL.dll, and Datalogics.PDFL.dll in turn communicates with DL150PFL.DLL, which links the Java and .NET Interface to the native Adobe PDF Library DLL files.

Note the reference to “150” in these file names in fact refers to the most recent version of the PDF Library, 15.0.

Macintosh

To work with Adobe PDF Library on Mac32, please note that:

  1. Autorelease pools are the responsibility of the caller.

A set of macros can be used for convenience. Simply use

CREATE_AUTORELEASE_POOL;

At the beginning of the program’s main or thread function, and

RELEASE_AUTORELEASE_POOL;

All Adobe PDF Library v15 samples have been updated to use these convenience macros.

  1. Projects must be set to compile as Objective-C or Objective-C++. To do this, open the Build Settings tab of the project or target, and change the “Compile Sources As” setting to

Objective-C or
Objective-C++

The following environment variables must be defined for Macintosh before you build applications using Adobe PDF Library.

DLE_INSTALL_LOCATION Define this environmental variable to point to the directory where the Java and .NET Interface package, is stored.
DYLD_LIBRARY_PATH A value specifying your library file locations:
export DYLD_LIBRARY_PATH
/Users/datalogics/Desktop/APDFL15.0.1PlusP1f/DLE
DYLD_FRAMEWORK_PATH A value specifying your Java and .NET Interface frameworks location:
export DYLD_FRAMEWORK_PATH
/Users/datalogics/Desktop/APDFL15.0.1PlusP1f/DLE
OS Operating System
setenv OS macintosh

Working with the Java and Microsoft .NET interfaces on a Macintosh platform

Follow these steps to set up the Adobe PDF Library Java and .NET Interface on a Macintosh platform.

  1. Double click on the .dmg file.
  2. You should see a window open that shows an APDFL15.0.1 folder. Copy or drag that folder to the APDFL folder on your desktop.
  3. Rename the folder APDFL15.0.4xxx, where “xxx” is the specific version. Look for the version value in the name of the dmg file that you run to install the product. For example, if the file name is “APDFL15.0.4PlusP2x_MacOSX_32.dmg,” the version is the “P2x” value.
  4. To run the APDFL samples, make sure that you put the frameworks included in the APDFL release, such as “./Binaries” in this system location:
[MacHD]:Library:Frameworks
  1. As an alternative, you can set environment variables for DYLD_LIBRARY_PATH and DYLD_FRAMEWORK_PATH to point to equivalent Library Framework locations.
  2. Then, to run the sample programs, simply double click on the appropriate .xcodeproj file. For APDFL sample programs, select “Build and Go.”
  3. For sample Java programs, click on the Terminal icon on the dock to open a Terminal Session.

Note that you can run Java on a Mac computer from a Terminal Session from the working directory—where the ./APDFL15.0.4/Java files and folders are installed.

  1. The Terminal Session opens. This is effectively a UNIX dialog.  You will be at the Users/your user folder by default.  Change to the installation directory for Java. Use the “cd Desktop” command and then:
    1. cd APDFL
    2. cd P3a release
    3. cd Java

UNIX

UNIX installations will typically contain the Adobe PDF Library files in one .tar file, typically gzipped with the .gz file extension. Unpack the release to the proper directory, such as /var, /opt, /var/Datalogics or /opt/Datalogics. The release will unpack itself into directory trees under the current location.

The following steps demonstrate a typical installation on a Linux machine. Other UNIX platforms will be similar.

  1. Copy the .tar file to your selected location, such as /var/Datalogics.
  2. Issue the unpack command for your release file, such as:

tar xvfz APDFLv15.0.1PlusP1f_i686-linux_rhws4-gcc41.tar.gz

This will unpack the release .tar file into its individual component files and folders.

Subsidiary directories under the top level directories will be created as the unpacking process proceeds. After the system unpacks the last file, the directories and subdirectories should be fully populated.

  1. Under the /var/Datalogics/ branch that was just created, locate the *.mak file (whichever one is appropriate for your platform) within /APDFL/Samples/utils:

Linux-install-1

Note that on the bottom of the screen shown above, we change to the All directory, and list (ls) the files found there. The *.mak file offered in this example is called “Datalogics_Makefile.”

  1.  Update the definitions as needed to point to the correct gcc and g++ locations on your system, to ensure that make procedures will build correctly.
  2. Set the environment variables:

Linux-install-2

  1.  At this point you should be able to build all samples by issuing a gmake command, triggering a build process that will walk through each sample folder in turn.
  2. After the builds have completed, the samples will run automatically as part of the same process.

See the appropriate listings for your platform in Environment Variables.