=head1 NAME cpan-mac - Tools for using CPAN with MacPerl (and other stuff) =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). NOTE: this package will NOT aid in the building of XS modules! If you need to build distributions that you download, that contain .xs or .c or other compilable files, please see Arved Sandstrom's Mac XS tutorial. http://macperl.com/depts/Tutorials/ Also NOTE: don't assume warnings are errors. They usually are not. Feel free to send me a log of your output if you do generate errors. One more NOTE: follow the directions in this file carefully, please. =head1 DESCRIPTION =head2 Requirements =over 4 =item PPC or CFM68K versions of the MacPerl distribution =item Roughly 10MB of RAM for targzipme and untargzipme =item Roughly 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 F<: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. Then you will need to increase the partitions as necessary. It is a very good idea to also B directory in the libraries list> specifically. It should already be in the window, but you want it to come first, so you need to add it in by hand. For configuring CPAN.pm for the first time, see L<"CPAN-shell"> below. =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, B. 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 B 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. B Once configuration is done, you can use the shell normally. Here is a safe procedure that can be used to install most distributions. Note that it is often better to install modules individually rather than Bundles, unless you know a Bundle is safe to install under MacPerl. First, of course, you should check CPAN Testers to see if the module has been tested for MacPerl (http://www.perl.org/cpan-testers/). cpan> readme Some::Module # will open README file in your # editor or "pager". cpan> get Some::Module # will get the module # distribution and unpack # it similarly to # untargzipme. inspect # distribution to see if # it needs to be compiled as XS, # or if it is not compatible # with MacPerl. cpan> make Some::Module # will prepare module for # installation; will NOT # compile XS modules. cpan> install Some::Module # installs module. cpan> look Some::Module # will open the distribution's # folder in the Finder # (downloading distribution # if necessary). run tests by # hand. 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. Most of the module versions included here can be gotten in other places. Exceptions have a * in front of the name. Binary distributions and other ports can usually be found at MacPerl Module Porters (http://pudge.net/mmp/). Archive::Tar 0.21 Stephen Zander (PS) AutoLoader Fixed by Paul Schinder * AutoSplit Fixed by Chris Nandor Compress::Zlib 1.04 Paul Marquess (built by CN) Convert::BinHex 1.119 Eryq CPAN 1.50 Andreas Koenig CPAN::WAIT 0.24 Ulrich Pfeifer Data::Dumper 2.101 Gurusamy Sarathy (built by CN) Digest::MD5 2.07 Gisle Aas (built by CN) Exporter From perl5.004_05 ExtUtils::MM_MacOS Matthias Neeracher (CN) File::Spec 0.7 Various FreezeThaw 0.3 Ilya Zakharevich HTML::Parser 2.23 Gisle Aas LWP 5.44 Gisle Aas (PS) libnet 1.0606 Graham Barr * Mac::AppleEvents 1.22 Matthias Neeracher (CN) Mac::AppleEvents::Simple 0.70 Chris Nandor Mac::Apps::Launch 1.70 Chris Nandor Mac::Conversions 1.01 Paul Schinder * Mac::InternetConfig Matthias Neeracher (CN) * Mac::Memory 1.20 Matthias Neeracher (CN) * Mac::Types Matthias Neeracher (CN) MIME::Base64 2.11 Gisle Aas (built by CN) MLDBM 2.00 Gurusamy Sarathy Net::Telnet 3.01 Jay Rogers Storable 0.603 Raphael Manfredi URI 1.03 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. =item The PREREQ_PM stuff is not honored right now. =back =head1 AUTHOR Above modules are authored by different people and are subject to separate copyrights. Copyright below only regards distribution and included programs installme, targzipme, untargzipme, INSTALL. 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 terms of the Artistic License, distributed with Perl. =head1 THANKS Thanks to lots of people, most recently Paul Corr and Peter Prymmer. =head1 HISTORY =over 4 =item v0.32 (09 July 1999) Fixed INSTALL bugs, Types warning, and CPAN-shell bug. =item v0.31 (08 July 1999) Fixed install problem with bad AutoSplit. =item v0.30 (08 July 1999) Updated modules a bunch of modules. Added AutoSplit, Mac::Memory, Mac::AppleEvents, Mac::InternetConfig, Mac::Types, Storable, MLDBM, FreezeThaw. Did some cleanup. =item v0.22 (28 January 1999) =over 4 =item Added support for CPAN's look function. =item Fixed a small bug in the InstallBLIB code that did not have a C on the C code (Paul Schinder). =item If cpan-mac-0.21 is already installed, just copy F and F by hand to your F directory. =back =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.32 (09 July 1999)