PDFNet for iOS Static to Dynamic Framework Migration

Starting with version 6.7, PDFNet for iOS ships the main library and open source tools project as dynamic frameworks (called PDFNet.framework and Tools.framework, respectively).

PDFNet

To migrate a project that uses the static framework to the dynamic framework, make the following changes:

  1. In your project’s list of files, find and remove the static version (6.5) of PDFNet.framework. It should no longer appear in the sidebar, or under the projects’ settings in the target’s Linked Frameworks and Libraries listing (found in General) or the Link Binary with Libraries listing (found in Build Phases).
  2. Ensure that Xcode can no longer find the old PDFNet.framework by removing it from any directory pointed to by the Framework Search Paths (found in the project’s settings under Build Settings). Alternatively, the Library Search Paths should be modified to no longer point to the location of the old PDFNet.framework.
  3. In your project’s list of files, find and remove: NSObjectInitWithCptr.h, NSObjectInitWithCptr.m, pdfnet.res, pdftron_layout_resources.plugin and pdftron_smart_substitution.plugin. These files are all bundled and registered automatically.
  4. Remove calls to [PTPDFNet SetResourcesPath:]. The resources are now bundled with the framework and automatically registered during initialization.
  5. In your target’s settings, under General, find the Embedded Binaries section and press the ‘+’. Click “Add Other…”, navigate to the dynamic framework, select it and click “Open”. If you navigate to the Build Phases tab, PDFNet.framework should appear under the Embed Frameworks phase. If it is not done automatically, you may need to add the framework’s directory to the target’s Framework Search Paths.
  6. In your target’s Build Phases panel, add a new “New Run Script Phase”, and add the following script: Bash "$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/PDFNet.framework/strip-framework.sh" This will ensure the simulator slices are striped from the framework before being submitted to the app store.
  7. Remove any import statements such as #import <PDFNet/PDFViewCtrl.h> and #import <PDFNet/Print.h> with a single import call to the new umbrella header, #import <PDFNet/PDFNet.h>.

Tools

To migrate a project that uses the static tools library to the dynamic tools framework, make the following changes:

  1. In your project’s list of files, find and remove libTools.a, tools-strings.bundle, and any Tools project header files.
  2. In your target’s settings, under General, find the Embedded Binaries section and press the ‘+’. Click “Add Other…”, navigate to the tools framework, select it and click “Open”. If you navigate to the Build Phases tab, PDFNet.framework should appear under the Embed Frameworks phase. If it is not done automatically, you may need to add the framework’s directory to the target’s Framework Search Paths.
  3. Replace any import calls to specific header files (e.g. #import "PanTool.h", #import BookmarksViewController.h) with a single import call to the new umbrella header, #import <Tools/Tools.h>.

Troubleshooting (PDFNet):

Problem: Runtime error message:

dyld: Library not loaded: @rpath/PDFNet.framework/PDFNet
  Referenced from: /Users/UserName/Library/Developer/CoreSimulator/Devices/879A4377-0657-4A67-80AD-39775B821404/data/Containers/Bundle/Application/644D296B-ADFC-42D9-8CF7-95A932351924/PDFViewCtrl.app/PDFViewCtrl
  Reason: image not found

Fix:

The framework cannot be found because it is not being copied into the app bundle. Make sure that you added the framework via the Embedded Binaries section as described in step 4.

Problem: Runtime error message:

2016-09-19 10:55:06.627 PDFViewCtrl[73274:1706924] *** Terminating app due to uncaught exception 'NullPointerException', reason: 'null std::string'
*** First throw call stack:
(
    0   CoreFoundation                      0x000000010ca4134b __exceptionPreprocess + 171
    1   libobjc.A.dylib                     0x000000010c3f721e objc_exception_throw + 48
    2   PDFNet                              0x0000000105301c7c ObjCPP_PTPDFNet_SetResourcesPath + 141
    3   PDFViewCtrl                         0x0000000101990c6b -[RootViewController initialSetup] + 347

Fix:

SetResourcesPath is being called, and pointing to a location that does not contain pdfnet.res. Please remove calls to SetResourcesPath, as described in step 3.

Problem: Error message:

In file included from /Users/you/Code/Project/Source/sourcefile.m:7:
/Users/you/Code/Project/Source/sourcefile.h:7:9: fatal error: 'PDFNet/PDFNet.h' file not found
#import <PDFNet/PDFNet.h>
        ^
1 error generated.

Fix:

Xcode can't find the new framework. Add its location to the Framework Search Paths, found in the project’s settings under Build Settings.

Problem:

/Users/you/Code/Project/PDFViewCtrlTools/Tools/ToolManager.h:20:36: error: no type or protocol named 'PTToolDelegate'
@property (nonatomic, weak) UIView<PTToolDelegate>* tool;
                                   ^

Fix:

A small number of APIs changed between 6.5.x and 6.7. Please consult the Migration Guide. In the specific case of the above error, the PTToolDelegate protocol has been renamed PTTool. The included tools project has been updated accordingly.

Problem: Error message:

ld: embedded dylibs/frameworks are only supported on iOS 8.0 and later (@rpath/PDFNet.framework/PDFNet) for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Fix:

Please update your app's deployment target to iOS 9.0 or greater. PDFNet for iOS requires iOS 9 or greater.

Troubleshooting (Tools)

Problem: Error message:

/Users/tempadmin/Desktop/PDFNet_iOS_6.5.4/Samples/PDFViewCtrlDemo/Source/RootViewController.h:10:9: fatal error: 'Tools/Tools.h' file not found
#import <Tools/Tools.h>
        ^

Fix:

Xcode can't find the new framework. Add its location to the Framework Search Paths, found in the project’s settings under Build Settings.

Problem: Runtime error message:

dyld: Library not loaded: @rpath/Tools.framework/Tools
  Referenced from: /Users/tempadmin/Library/Developer/CoreSimulator/Devices/80DC8569-C4B2-4355-8957-51A46571696E/data/Containers/Bundle/Application/5670C035-658D-4B56-971E-8EA858BBF60F/PDFViewCtrl.app/PDFViewCtrl
  Reason: image not found

Fix:

The framework cannot be found because it is not being copied into the app bundle. Make sure that you added the framework via the Embedded Binaries section as described in step 3.