=head1 NAME cpan-mac - Tools for using CPAN with MacPerl =head1 SYNOPSIS This package includes five programs. One droplet for creating tar.gz archives (targzipme), one for unpacking them (untargzipme), one for unpacking and installing, or just installing (installme), one for accessing CPAN using the CPAN.pm module (CPAN-shell), and one for installing all of the above, including the many modules for supporting these programs (INSTALL). =head1 DESCRIPTION =head2 Requirements =over 4 =item PPC or CFM68K versions of the MacPerl distribution =item 10MB of RAM for targzipme and untargzipme =item 30MB of RAM for CPAN-shell =back =head2 Installation Run the INSTALL.plx program. It will copy all the needed modules and shared libraries to your :site_perl directory, run autosplit on the module files, and create directories as needed. Then it will prompt for copying the droplets to the MacPerl folder and creating aliases on the desktop. Finally, it will prompt the user to increase the memory partition of the MacPerl application to a suitable amount. For configuring CPAN.pm for the first time, see L<"CPAN-shell"> below. NOTE: if you already have everything else installed, just make sure you get CPAN and CPAN::FirstTime (if you have less than version 1.46 of CPAN.pm) and ExtUtils::MM_MacOS. Every other module can be gotten apart from this package, from CPAN or Paul Schinder's FTP site, though for the XS modules (MIME::Base64, Digest::MD5, Compress::Zlib, Data::Dumper) the binary builds for MacPerl are required (which are in the authors/id/CNANDOR/ directory on CPAN). http://www.perl.com/CPAN-local/ http://www.pobox.com/~schinder/MacPerl.html If any of the above is confusing, just run the INSTALL.plx program, which will install everything you need. =head1 CONTENTS =head2 Programs =over 4 =item targzipme This droplet will create an archive from a folder, suitable for unpacking with untargzipme.plx below. It is primarily for developers. When launched, the developer has the opportunity to (1) make all binary files MacBinarized and translate all text files from Mac to Unix newlines, (2) do no conversion, or (3) bring up a window containing the names of all files in the archive, allowing the developer to select a mode for each file. The modes in the window are text conversion (plain), MacBinary conversion (bold), and no conversion (italic). The droplet will also attempt to create a filename that will fit within the Mac OS 31-character limit. It would be best for the developer to first create a directory that fits within 27 characters, so ".tgz" can fit after the name. The droplet will not create an archive if the archive already exists. =item untargzipme This droplet will unpack a .tar.gz (or .tgz) archive. If a Macbinary file is found (a binary file ending in .bin), this droplet will attempt to demacbinarize it, and if a text file is found, this droplet will attempt to translate it from Unix or DOS newlines to Mac OS newlines. There is a secondary option on launch that can be chosen to do no translation of any documents. The droplet will not unpack an archive if the directory to unpack to already exists. =item installme If a .tar.gz or .tgz archive is dropped on this droplet, it will first unpack it, in the same way as untargzipme. After unpacking, it will then install the contents of the newly created folder. If a folder is dropped on the droplet instead of a .tar.gz or .tgz file, it will just go ahead and install the contents of the folder. It uses the same routines as CPAN.pm does for make and make install, contained in ExtUtils::MM_MacOS. This is a nice alternative to using CPAN.pm, if you have limited RAM, or if you happen to have a specific distribution already downloaded. =item CPAN-shell For information on how to use the CPAN shell, see the documentation contained in the CPAN.pm file. This requires quite a bit of RAM, as noted above. It also can run slowly on older systems. My two test systems are a PowerBook G3/292 with 160MB of RAM and an iMac 233 with 96MB of RAM. So my systems are decked out, and they work well. But with large distributions, even mine with 40MB allocated to MacPerl can run out of memory. If you get an out of memory error from MacPerl, quit the application. If you try to run another script, you can crash your computer. Before running it the first time, make sure that you have a HOME variable set in your environment variables preferences in the MacPerl application. Also, it might be a good idea to add an EDITOR variable, which would be a four-character creator ID of your favorite text editor. When running the first time, select the defaults during configuration unless you know what you are doing. For the "pager" configuration, you can put in the four-character creator ID of your favorite text editor. When you get to the MIRRORED.BY section, a file containing CPAN mirrors will be downloaded to your computer, and you will be prompted for where you live in the world, and then presented a list of CPAN mirrors, where you will type in the numbers matching the CPAN mirrors you want to use. For each of the questions in this section, you will need to hit control-D to continue. You can hit RETURN for the other questions in configuration. Once configuration is done, you can use the shell normally, according to the CPAN.pm documentation: cpan> get Some::Module # will get the module # distribution and unpack # it similarly to # untargzipme cpan> make Some::Module # will prepare module for # installation; will NOT # compile XS modules cpan> install Some::Module # installs module cpan> readme Some::Module # will open README file in your # editor or "pager" The command C does not test; it will C and C a distribution, though. XS modules are not built. C does nothing. Everything else pretty much works the same as it does on Unix. =back =head2 Included Modules Note that where there are parentheses after a name, that module (or one or more files from that distribution) has been changed from its form in the author's distribution. Archive::Tar 0.20 Stephen Zander (PS) AutoLoader Fixed by Paul Schinder Compress::Zlib 1.01 Paul Marquess (built by CN) Convert::BinHex 1.119 Eryq CPAN 1.47 Andreas Koenig CPAN::WAIT 0.24 Ulrich Pfeifer Data::Dumper 2.10 Gurusamy Sarathy (built by CN) Digest::MD5 2.01 Gisle Aas (built by CN) Exporter Fixed by Paul Schinder ExtUtils::MM_MacOS Matthias Neeracher (CN) File::Spec 0.7 Various HTML::Parser 2.22 Gisle Aas LWP 5.41 Gisle Aas (PS) libnet 1.0606 Graham Barr Mac::AppleEvents::Simple 0.52 Chris Nandor Mac::Apps::Launch 1.61 Chris Nandor Mac::Conversions 1.00 Paul Schinder MIME::Base64 2.10 Gisle Aas (built by CN) Net::Telnet 3.01 Jay Rogers URI 1.00 Gisle Aas =head1 BUGS =over 4 =item Long filename distributions (more than 31 characters) are downloaded, but if the folders in the tar archives are over 31 characters, then unpacking will fail. =item Only .gz and .tar files are dealt with (which covers most distributions). =item MacPerl might think a file or folder is busy, and you have to trash it manually. This usually happens when something else "bad" happens first. =item Complicated Makefile.PL files, or ones that otherwise fail because of stuff that doesn't work under MacPerl, will cause the make and install to be unable to complete. =item A best effort has been made to identify all the proper .pm files to be installed in the right place. Please pay attention, though, to files that are installed that should not be, or files that are not installed that should be. =back =head1 AUTHOR Above modules are authored by different people and are subject to separate copyrights. Included programs installme, targzipme, untargzipme are authored by: Chris Nandor Epudge@pobox.comE, http://pudge.net/ Copyright (c) 1999 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 HISTORY =over 4 =item v0.21 (25 January 1999) =over 4 =item Re-upload. =back =item v0.20 (25 January 1999) =over 4 =item First public release. =item Changes to docs (Paul Schinder). =item Update CPAN.pm to version 1.47. =item Added installme program and documentation. =item (Hopefully) fixed problem with ExtUtils::MM_MacOS::make() not running Makefile.PL (Larry Moore). =back =item v0.10 (23 January 1999) =over 4 =item First release of entire package. =item Patches for CPAN 1.45 and CPAN::FirstTime submitted to Andreas Koenig. =back =back =head1 VERSION Version 0.21 (25 January 1999)