README - Carbon API for perl on Mac OS X
Mac::Carbon is a collection of perl modules for accessing the Carbon API under Mac OS X. It is a port of the Toolbox modules written by Matthias Neeracher for MacPerl.
This is not release-quality software. It is still in development.
Part of the current strategy is to make Mac::Carbon the intersection of the old and new Mac OS APIs. We will not be adding new functionality from Carbon, except as needed, for now. This may change over time as Mac::Carbon stabilizes.
See the documentation in Mac::Carbon for more implementation details, bugs, etc.
This version represents a major step forward for Mac::Carbon, with many of the TODO items checked off, including:
Mac::InternetConfig added
GUSI-emulation API able to handle FSSpecs for files that don't exist
Find apps with LaunchServices by creator, bundle ID, or name, instead of FSpDTGetAPPL
Open resource files in data fork, not just resource fork
Support for Mac::AppleEvents::Simple and Mac::Glue
There are also many bugfixes and other enhancements included. See Changes for details.
There are still some bugs, one unimplemented extension (SpeechRecognition), and a bunch of tests that need to be written before the distribution becomes "release-quality." Help wanted.
There are probably a lot of bugs, especially in Carbon.h. Bugs are listed in "Known Bugs" in Mac::Carbon; please feel free to report more. Patches are welcome, too, of course. For large patches, such as stuff for test suites and building, please do coordinate with me before spending much time on it.
http://projects.pudge.net/
These modules all build under Mac OS, but it is recommended you build them as a part of MacPerl itself, or at least under the MacPerl source (version 5.6.1 or greater). See http://dev.macperl.org/ for more information.
Under Mac OS, extra non-Carbon-compatible routines are available.
To build these modules on Mac OS X, the Developer Tools are required.
The Test::More module is required for running tests.
The separate Mac::Errors module is not required, but is highly recommended.
Building these modules has been tested successfully on Mac OS X 10.1 and 10.2, with perl 5.6.0/5.6.1/5.8.0, with both gcc2 and gcc3. Some tests fail on UFS ([GS]etFileInfo in MacPerl.t). There are a lot of warnings on 10.1, though the tests should all pass.
Don't run the test suite on a remote computer (such as via ssh, instead of via the Terminal). It requires user feedback in some cases, and in general it is best to be there when you run the tests. Maybe in the future this can be addressed (patches welcome).
Matthias added some extensions to XS for his Toolbox modules; they were never fully embraced by p5p, and as a result, we have a separate xsubpp for these additional XS macros. The Makefile.PLs will choose and use the appropriate xsubpp version for your version of perl.
You might want to run the test suite with make test TEST_VERBOSE=1. It's cool.
make test TEST_VERBOSE=1
Currently, only a subset of the modules are supported. The ported modules are:
Mac::AppleEvents Mac::Components Mac::Files Mac::Gestalt Mac::InternetConfig Mac::Memory Mac::MoreFiles Mac::Notification Mac::OSA Mac::Processes Mac::Resources Mac::Sound Mac::Speech Mac::Types MacPerl
Distributed separately on the CPAN and SourceForge.net (either now or soon):
Mac::AppleEvents::Simple Mac::OSA::Simple Mac::Glue
And, coming soon, possibly:
Mac::SpeechRecognition
There are currently no plans for the other (GUI) modules, including:
Mac::Controls Mac::Dialogs Mac::Events Mac::Fonts Mac::Lists Mac::Menus Mac::Movies Mac::Navigation Mac::QDOffScreen Mac::QuickDraw Mac::QuickTimeVR Mac::TextEdit Mac::Windows
We could do these eventually, if there is enough interest. They don't port as easily as some of the others, for many reasons, not the least of which is that we need a framework to handle events etc., which for MacPerl is mostly implemented in macish.c / macish.h.
The Mac Toolbox modules were written by Matthias Neeracher <neeracher@mac.com>. They are currently maintained by Chris Nandor <pudge@pobox.com>.
$Id: README,v 1.8 2003/04/07 01:29:17 pudge Exp $
To install Mac::Carbon, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mac::Carbon
CPAN shell
perl -MCPAN -e shell install Mac::Carbon
For more information on module installation, please visit the detailed CPAN module installation guide.