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
• 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