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 .