README for Perl module Emacs::Lisp
last updated: 21 Feb 1999

##################################################################
###### CAUTION ###### CAUTION ###### CAUTION ###### CAUTION ######
##################################################################
#######                                                    #######
#######   THIS IS ALPHA SOFTWARE.  USE AT YOUR OWN RISK!   #######
#######   NOT RESPONSIBLE FOR CRASHES OR LOST DATA!!!!!!!  #######
#######                                                    #######
##################################################################
###### CAUTION ###### CAUTION ###### CAUTION ###### CAUTION ######
##################################################################


WHAT
----
Perlmacs is a patch of GNU Emacs.  It creates a program that has all
the functionality of both Perl and Emacs.  The Emacs::Lisp module
allows Perl code to call functions and access variables of Lisp.

This release (Emacs::Lisp 0.74) is just version 0.71 updated for use
with Emacs 20.3.  You can't use it with a Perlmacs built from Emacs
20.2, and you should not use earlier versions of Emacs::Lisp (<=0.71)
with Emacs 20.3.  (They might seem to work, but they will crash or
behave unpredictably.)  To summarize the version dependencies:

   Emacs::Lisp	Emacs	Perl	Perlmacs
   ===========  =====   ====    ========
       0.71	20.2	5.004	0.6.2
       0.74	20.3	5.004	0.6.2.2
       0.75	20.3	5.005	0.7


WHY
---
The intent is to allow Emacs modules and customization code to be
written in Perl, as well as Emacs Lisp.


HOW
---
You must first install PERL VERSION 5.004 or higher.  I have done
minimal testing with the development Perl version 5.004_59 (WITHOUT
thread support), and somewhat more with Perl 5.004_03.

Your Perl must have working ExtUtils::Embed capabilities.  If not, the
patched Emacs configure script will exclude Perl support, and you will
have something close to standard GNU Emacs.  If you are unsure about
this, watch the messages printed by `configure'.  If they say that
Perl is embeddable, good.  If not, you might want to peek in the
generated config.log for clues.

Retrieve the Emacs 20.3 distribution from a location such as one of
these:

   ftp://prep.ai.mit.edu/pub/gnu/emacs-20.3.tar.gz
   ftp://sunsite.unc.edu/pub/gnu/emacs-20.3.tar.gz

You may want to grab the Elisp Manual, elisp-manual-19-2.4.2.tar.gz,
while you're there.

Retrieve Perlmacs patch version 0.6.2.2 from

   http://www.perl.com/CPAN/authors/id/JTOBEY/emacs-20.3-perlmacs-0.6.2.2.pl.gz

Then do

   gzip -dc emacs-20.3.tar.gz |tar xf -
   cd emacs-20.3
   gzip -dc ../emacs-20.3-perlmacs-0.6.2.2.pl.gz |perl
   ./configure
   make
   make install

NOTE: This will install the program as /usr/local/bin/emacs by default.

If you wish to use an installed version of Perl other than the one
that's in your $PATH, set the environment variable $PERL to the
desired program when running configure.  For example, under bash or
sh:

   PERL=perl5.004 ./configure

However, this method has been know to fail sometimes.

To build Emacs::Lisp, first make "perlmacs" a name for the emacs
binary you just installed:

   ln /usr/local/bin/emacs /usr/local/bin/perlmacs

(This makes what follows simpler.  It will happen automatically in
Perlmacs 0.7.)

Then, do the usual commands for installing a module, but use
`perlmacs' in place of `perl'.  (The program parses its command line
like Perl if it is invoked by a name containing "perl".)

   gzip -dc Emacs-Lisp-*.tar.gz |tar xf -
   cd Emacs-Lisp-*
   perlmacs Makefile.PL
   make
   make test
   make install

Use `perldoc Emacs::Lisp' for documentation.


CAVEATS
-------
As of this ALPHA version, crashes may occur, resulting in the loss of
unsaved editing changes.  (But as far as I can tell, they occur only
in specific circumstances which do not affect what I consider "normal"
use.  I have been using a patched Emacs since Perlmacs version 0.3,
and replaced my .emacs with a Perl script as of 0.6.  The only crashes
have occurred during admittedly risky experiments involving nonlocal
jumps.  Because I am careful to save my work often, I have not lost
any data.)

This is not meant to be tried (yet) on anything other than Unix-like
systems.  However, if you get it to work on non-unix, I would be
delighted to hear about it!


LICENSE
-------
This module, like all extensions to GNU Emacs, is licensed under the
GNU General Public License.  See the files Lisp.pm and COPYING for
details.


-- John
spam@john-edwin-tobey.org
