About
This is the 3rd revision of the framework parser PHP script and a total rewrite of the single file script that was originally designed for the now defunct PasCocoa. Although may times more complicated the new script is well designed and easy to develop upon for future needs, unlike the old design which was nearly impossible to fix when changes needed to be made.
You can use the parser to translate batches of frameworks, entire SDK's, 3rd party frameworks (from non-Apple providers) and single Objective-C headers. For complete usage see the manual in the parser package download.
Getting Started
Each version of the parser has been tested for a specific SDK version and built-in commands can only be guaranteed to work with those SDK's only. In the parser folder open the build commands (.command files) which will start the parser in Terminal.app and output into /Developer/ObjectivePascal by default.
build-cocoaall.command
build-iphoneall.command
If you want to change the output path you can run the parser manually using a built-in command for the SDK you're targeting.
php parser.php -out="/Developer/ObjectivePascal/CocoaAll" -command="@/commands/cocoaall10.8.txt"
Since Xcode 4.3 SDK's are now stored in the Xcode bundle so the parser features a new -xcode option to specify the location of Xcode. The default path is /Applications/Xcode.
To change the location of Xcode you need to edit the command file for the SDK you're targeting (files are in /commands) and change the value of -xcode.
These headers require at least FPC 2.7.1 from March 25th 2012 which contain some bug fixes for formal declarations that exist in 2.6.0.
Important Notes When Upgrading
Possible Inconsistencies With Old Header
Because the parser has been totally rewritten there may be inconsistencies with older versions of the headers you will need to change. Adding extra types to CocoaAll.pas or making categories to correct methods with changed names are two easy solutions.
Some changes include:
- "Pointer" suffixed types like NSStringPointer have been removed in favor of "Ptr". These 2 types were used inconsistently in the old headers and since there is no reason to have both I used the more common Ptr varient used in Carbon frameworks for years.
- Previously conflicts between instance and class methods would overwrite the class method in favor of the instance method. In the new headers both methods are preserved but the class method is prefixed "class". You may need to rename some methods in your code accordingly.
Target and Conditional Macros
Macros for OS and SDK targets that were previously skipped are now included in the headers for most types and methods, however could not be applied in all cases due to exceeding complexity. The "deprecated" keyword is used when appropriate but many other macros are simply preserved as comments which will not trigger compiler errors or warnings.
Cross-SDK Target Compatibility
These headers have not been tested when compiling for older SDKs than the original SDK they were parsed from. I know at least one case of CoreImage for iOS not being available below 5.0 which will cause problems. Until I figure out a solution that can be implemented in the parser you may need to make changes by hand and apply compilers macros yourself.
Stand Alone Framework Units
Now in addition to using group units like CocoaAll and iPhoneAll you can compile using stand alone frameworks like Foundation.pas for making command line programs with no GUI.
More Frameworks
The MacOS and iOS SDKs now contain a more complete set of frameworks however still with various omissions. Frameworks omitted were either: plain-C and too difficult to parse, low level system units (for example in iPhoneOS6.0.sdk/usr/include) or in the case of MacOS legacy Carbon frameworks that are already available in MacOSAll and not likely to change in the future.
iOS Moves Away From Universal Intefaces
The iOS SDK contains a very managable amount of frameworks which could all be parsed so I decided to remove dependancies on the universal interfaces which were used in the past for frameworks like CoreFoundation and CoreGraphics. The choice was made because the universal interfaces are already out of date and likely to be even more so in the future. Additionally instead of adding long list of commonly used units like CFBase, CFString, CFArray etc... you can simply add iPhoneAll to the unit and get all the units for free.
When using the new headers you may need to remove universal interfaces from the uses clause of units which conflict with duplicate types in iPhoneAll and CoreFoundation, CoreGraphics etc...
MacOS Maintains Dependancies On Universal Intefaces
Because the amount of Carbon frameworks for MacOS was so daunting I decided to skip frameworks that didn't contain Objective-C for the time being and rely upong the out of date universal interfaces and MacOSAll for support. In the future I would like to start adding more frameworks that contain Carbon code which is likely to change in future OS X releases. That current list includes: ImageIO, CoreGraphics, CoreFoundation, OpenGL, LaunchServices.
Support Macros:
When compiling using the headers there are some compiler macros you can set on the command line to affect their usage.
- -dMACOSALL: When compiling for MacOS this will use MacOSAll.pas for compatibility with various types across many frameworks instead of using the stand alone unit universal interfaces. The frameworks available for MacOS do not include many older Carbon frameworks which are available in MacOSAll.pas and corrispoding universal interfaces so you should compile using -dMACOSALL if you project uses MacOSAll in other units and you want to maintain type compatibility across your project when using CocoaAll.
- -dNSGEOMETRY_TYPES_SAME_AS_CGGEOMETRY_TYPES: Types such as NSPoint, NSRect, NSSize etc... will use the CoreGraphics equivalents when this macro is enabled (see NSGeometry.inc for more information).
Group Unit Macros
The master "group" units iPhoneAll.pas and CocoaAll.pas require you to set one of the macros below (on the command line) in order to prevent type conflicts when being used in conjunction with other stand alone framework units. For example if you mix CocoaAll and WebKit you would get errors that Foundation.NSString was expected but CocoaAll.NSString was used because if COCOAALL is not enabled WebKit.pas uses Foundation.pas instead of CocoaAll.pas for support types.
- -dCOCOAALL
- -dIPHONEALL
Group Unit Frameworks
The group units were chosen to use the fewest frameworks possible while giving the broad range of basic functionality that the majority of programs need. However for type compatibility and to prevent conflicts extra frameworks had to be added in some cases even though they don't fit the criteria above.
- CocoaAll: Foundation, CoreImage, QuartzCore, CoreData, AppKit.
- iPhoneAll: CoreFoundation, Security, Foundation, CoreGraphics, OpenGLES, CoreImage, CoreText, QuartzCore, UIKit, MobileCoreServices.
Reporting Bugs
The headers are guaranteed to contain bugs! I have no ability to test all these frameworks in actual implementations and the majority are tested simply to compile.
Please report bugs on the Mac Pascal Mail List or to GitHub Issues to improve the robustness of the headers for all users.
Parser Downloads
- Framework Parser on Github (contains the latest development version)
- Parser (MacOS SDK 10.7 and iOS SDK 5.0)
- Parser (MacOS SDK 10.8 and iOS SDK 6.0 from Xcode Developer Preview 4.5)
Framework Downloads