#!perl -w
# run this document through perl to check its syntax
use Pod::Checker;
podchecker(\*DATA);
__END__

=head1 NAME

README - Carbon API for perl on Mac OS X

=head1 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.

This is B<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 L<Mac::Carbon> for more implementation details,
bugs, etc.

=head1 DESCRIPTION

This version represents a major step forward for Mac::Carbon, with many of
the TODO items checked off, including:

=over 4

=item *

Mac::InternetConfig added

=item *

GUSI-emulation API able to handle FSSpecs for files that don't exist

=item *

Find apps with LaunchServices by creator, bundle ID, or name, instead
of FSpDTGetAPPL

=item *

Open resource files in data fork, not just resource fork

=item *

Support for Mac::AppleEvents::Simple and Mac::Glue

=back

There are also many bugfixes and other enhancements included.  See F<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.


=head1 HELP ME

There are probably a lot of bugs, especially in F<Carbon.h>.  Bugs are listed
in L<Mac::Carbon/"Known Bugs">; 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/


=head1 REQUIREMENTS

=head2 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.

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

A few things fail on the current release of Panther, developer preview releases
of what will become Mac OS X 10.3.  These will be addressed as the release of Mac
OS X 10.3 draws nearer, but until then, ignore test errors for CountVoices()
in Mac::Speech (a voice file in the Panther Preview was broken), along 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).


=head1 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 C<make test TEST_VERBOSE=1>.
It's cool.


=head1 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 F<macish.c> / F<macish.h>.


=head1 AUTHOR

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


=head1 VERSION

$Id: README,v 1.9 2003/08/13 21:42:40 pudge Exp $
