11.7. Building Your Own Lisp Library


After you have become proficient at Emacs Lisp programming, you will want a library of Lisp functions and packages that you can call up from Emacs at will. Of course, you can define a few small functions in your .emacs file, but if you are writing bigger pieces of code for more specialized purposes, you will not want to clutter up your .emacs file nor will you want Emacs to spend all that time evaluating the code each time you start it up. The answer is to build your own Lisp library, analogous to the Lisp directories that come with Emacs and contain all of its built-in Lisp code. After you have created a library, you can load whatever Lisp packages you need at a given time and not bother with the others.

Creating a library requires two simple steps. First, create a directory in which your Lisp code will reside. Most people create a elisp subdirectory of their home directory. Lisp files are expected to have names ending in .el (your .emacs file is an exception). The second step is to make your directory known to Emacs so that when you try to load a Lisp package, Emacs knows where to find it. Emacs keeps track of such directories in the global variable load-path, which is a list of strings that are directory names.

The initial value for load-path is populated with the names of the Lisp directories that come with Emacs, e.g., /usr/local/emacs/lisp. You will need to add the name of your own Lisp directory to load-path. One way to make this addition is to use the Lisp function append, which concatenates any number of list arguments together. For example, if your Lisp directory is ~<yourname>/lisp, you would put the following in your .emacs file:

(setq load-path (append load-path (list "~yourname/lisp")))

The function list is necessary because all of the arguments to append must be lists. This line of code must precede any commands in your .emacs file that load packages from your Lisp directory.

When you load a library, Emacs searches directories in the order in which they appear in load-path; therefore, in this case, Emacs searches its default Lisp directory first. If you want your directory to be searched first, you should use the cons function described earlier instead of append, as follows:

(setq load-path (cons "~yourname/lisp" load-path))

This form is useful if you want to replace one of the standard Emacs packages with one of your own. For example, you'd use this form if you've written your own version of C mode and want to use it instead of the standard package. Notice that the directory name here is not surrounded by a call to list because cons's first argument can be an atom (a string in this case). This situation is similar to the use of cons for pushing values onto stacks, as in the calculator mode described earlier.

If you want Emacs to search the directory you happen to be in at any given time, simply add nil to load-path, either by prepending it via cons or by appending it via append. Taking this step is analogous to putting . in your Unix PATH environment variable.

After you have created a private Lisp library and told Emacs where to find it, you're ready to load and use the Lisp packages that you've created. There are several ways of loading Lisp packages into Emacs. The first of these should be familiar from Chapter 10:

  • Type M-x load-library Enter as a user command; see Chapter 10.

  • Put the line (load "package-name") within Lisp code. Putting a line like this into your .emacs file makes Emacs load the package whenever you start it.

  • Invoke Emacs with the command-line option "-l package-name". This action loads the package package-name.

  • Put the line (autoload 'function "filename") within Lisp code (typically in your .emacs file), as described in Chapter 10. This action causes Emacs to load the package when you execute the given function.[12]

    [12] There is also the option "-f function-name" which causes Emacs to run the function function-name at startup, with no arguments.

11.7.1 Byte-Compiling Lisp Files

After you have created your Lisp directory, you can make loading and running your Lisp files more efficient by byte-compiling them, or translating their code into byte code, a more compact, machine-readable form. Byte-compiling the Lisp file filename.el creates the byte code file filename.elc. Byte code files are typically 40 to 75 percent of the size of their non-byte-compiled counterparts.

Although byte-compiled files are more efficient, they are not strictly necessary. The load-library command, when given the argument filename, first looks for a file called <filename>.elc. If that doesn't exist, it tries <filename>.el, that is, the non-byte-compiled version. If that doesn't exist, it finally tries just <filename>. Thus, you can byte-compile your .emacs file, which may result in faster startup if your .emacs is large.

You can byte-compile a single function in a buffer of Lisp code by placing your cursor anywhere in the function and typing M-x compile-defun. You can byte-compile an entire file of Lisp by invoking M-x byte-compile-file Enter and supplying the filename. If you omit the .el suffix, Emacs appends it and asks for confirmation. If you have changed the file but have not saved it, Emacs offers to save it first.

Then you will see an entertaining little display in the minibuffer as the byte-compiler does its work: the names of functions being compiled flash by. The byte-compiler creates a file with the same name as the original Lisp file but with c appended; thus, <filename>.el becomes <filename>.elc, and .emacs becomes .emacs.elc.

Finally, if you develop a directory with several Lisp files, and you make changes to some of them, you can use the byte-recompile-directory command to recompile only those Lisp files that have been changed since being byte-compiled (analogously to the Unix make utility). Just type M-x byte-recompile-directory Enter and supply the name of the Lisp directory or just press Enter for the default, which is the current directory.



Learning GNU Emacs
Learning GNU Emacs, Third Edition
ISBN: 0596006489
EAN: 2147483647
Year: 2003
Pages: 161

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net