README for Perl module Emacs::Lisp

README for Perl module Emacs::Lisp
last updated: 2 Mar 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.78) uses features introduced in Perlmacs
0.7, which requires Emacs 20.3 and Perl 5.005. The following table
lists which versions of the various packages work together:

Emacs::Lisp Emacs Perl Perlmacs
=========== ===== ==== ========
0.71 20.2 5.004 0.6.2
0.75 20.3 5.004 0.6.2.2
0.78 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. Because we can. :-)

Actually, my motives have mostly to do with becoming a better
programmer and familiarizing myself with Perl and Emacs, two very
important programs. See
http://www.tux.org/~niemi/opensource/developer-motivation.html for a
nice explanation by David Niemi.

HOW
---
You must first install PERL VERSION 5.005 or higher. If you get core
dumps during process termination, I recommend you configure Perl with
-Dusemymalloc=y. So far, I have seen this problem only with the
Emacs::Lisp test script, and using Perl's malloc seems to cure it.

Your Perl must have working ExtUtils::Embed capabilities. If not,
`configure' 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, have a peek at the generated config.log file for clues,
and mail me any workarounds.

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

ftp://ftp.gnu.org/pub/gnu/emacs/emacs-20.3.tar.gz
ftp://metalab.unc.edu/pub/gnu/emacs/emacs-20.3.tar.gz

You may want to grab the Elisp Manual, elisp-manual-20-2.5.tar.gz,
while you're there. (At this time, knowledge of Elisp is essential
for programming with Emacs::Lisp.)

Retrieve the latest Perlmacs patch from one of these locations:

http://www.perl.com/CPAN/authors/id/JTOBEY/emacs-20.3-perlmacs-*.pl.gz
http://www.john-edwin-tobey.org/perlmacs/src/emacs-20.3-perlmacs-*.pl.gz

(Substitute the highest version number, at least 0.7, for `*'.) Then
do

gzip -dc emacs-20.3.tar.gz |tar xf -
cd emacs-20.3
gzip -dc ../emacs-20.3-perlmacs-*.pl.gz |perl

Have a look at the patched README file for further information. The
basic procedure should be familiar:

./configure
make
make install

This will, by default, install the program in /usr/local/bin under the
names `pmacs' and `perlmacs'. The program can parse its command line
as either Perl or Emacs would, depending on whether "perl" appears in
its name. (Using `--perl' or `--emacs' as the first arg overrides
this.)

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.005 ./configure

Next, build the Emacs::Lisp module in the usual way, but use perlmacs
in place of perl.

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

Most of the documentation for both the patch and the module is in
perl/Emacs/Lisp/Lisp.pm and should be accessible after installation
via

perldoc Emacs::Lisp

Lisp functions, such as `perl-eval', also have Emacs docstrings
accessible through `C-h f'. No texinfo docs yet, sorry.

For information on getting the latest source via anonymous CVS, see
http://john-edwin-tobey.org/perlmacs/.

CAVEATS
-------
As of this ALPHA version, crashes may occur, resulting in the loss of
unsaved editing changes.

This is not meant to be tried 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 software is licensed under the GNU General Public License. See
the file COPYING for details.

WARRANTY
--------
What! Are you kidding? Let's see, where's a copy of that
disclaimer.... oh, here we go:

This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Send bug reports and inquiries to John <[email protected]>.