The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

README - Carbon API for perl on Mac OS X

SYNOPSIS

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.

See the documentation in Mac::Carbon for more implementation details, bugs, etc.

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 ME

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/

REQUIREMENTS

Mac OS

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.

Mac OS X

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 through 10.3, with perl 5.6.0/5.6.1/5.8.0/5.8.1, with gcc2, gcc3.1, and gcc3.3. There are a lot of warnings on 10.1, though the tests should all pass.

Last I checked, a few things failed on the development release of Panther. These will be addressed once I install Panther and get to it (any day now?). Specifically, there were some problems with the Mac::Notification tests (which expose problems/changes with the Notification Manager and LaunchApplication()).

If you run the test suite on a remote computer (such as via ssh, instead of via the Terminal), note that 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).

BUILDING

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.

SUPPORTED MODULES

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:

        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.

AUTHOR

The Mac Toolbox modules were written by Matthias Neeracher <neeracher@mac.com>. They are currently maintained by Chris Nandor <pudge@pobox.com>.

VERSION

$Id: README,v 1.10 2003/10/28 05:54:34 pudge Exp $