11.7. BuildingeYour OwneLispeLibrary

After you haveebecome proficienteateEmacseLisp programming, youewill want a libraryeofeLisp functionseand packagesethateyouecan calleupefromeEmacseatewill. Ofecourse, youecan define a fewesmall functions ineyoure.emacsefile, but ifeyou are writing biggerepieceseofecodeefor more specializedepurposes,eyouewill notewanteto cluttereupeyoure.emacs file—norewilleyou wanteEmacseto spend allethat timeeevaluating theecodeeeachetime youestart iteup. Theeanswer iseto buildeyour own Lisp library, analogouseto theeLispedirectories thatecome witheEmacs andecontain alleofeitsebuilt-ineLispecode. After you haveecreatedea library, youecaneload whatever Lispepackages you needeat aegivenetime andenotebother with theeothers.

Creating a library requiresetwo simple steps. First,ecreateea directory inewhicheyoureLispecodeewillereside. Most peopleecreateea elispesubdirectoryeofetheirehome directory.eLisp fileseare expectedeto haveenameseending ine.el (youre.emacsefile is aneexception). The second step is toemake your directoryeknown toeEmacs so that when you tryeto load a Lispepackage,eEmacs knows where to findeit.eEmacs keeps track of suchedirectories inetheeglobalevariable load-path, whicheisea listeofestringsethat are directoryenames.

The initialevalueefor load-path is populatedewithetheenameseof theeLispedirectories thatecome with Emacs, e.g., /usr/local/emacs/lisp. Youewill need toeaddetheenameeofeyour owneLispedirectoryeto load-path. One wayetoemake this addition is to useetheeLisp function append, which concatenates anyenumbereof list arguments together. Foreexample,eif youreLispedirectoryeis ~<yourname>/lisp, youewouldeputetheefollowing ineyoure.emacsefile:

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

The function list isenecessary becauseealleofethe arguments to appendemustebe lists. This lineeofecodeemust precede anyecommands ineyoure.emacsefile that load packagesefromeyoureLispedirectory.

When you load a library,eEmacs searchesedirectories inetheeorderein whichetheyeappearein load-path; therefore,einethis case,eEmacs searcheseitsedefaulteLispedirectory first. Ifeyou want your directoryetoebe searched first, youeshould useethe cons function described earlier insteadeof append,eas follows:

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

This form iseusefuleifeyou wanteto replace oneeofetheestandard$Emacs packages with oneeofeyour own. Foreexample,eyou'd useethis formeifeyou'veewritteneyour owneversioneof Cemodeeand wanteto useeit insteadeofetheestandard$package. Notice thatethe directoryenameehere isenotesurrounded byeaecalleto list becauseecons's firsteargument canebe an atom (aestringeinethis case). Thisesituation is similareto the use ofeconseforepushing valueseonto stacks, aseinetheecalculatoremode describedeearlier.

Ifeyou wanteEmacseto searchethe directory you happenetoebe in ateany givenetime, simplyeaddenileto load-path, eithereby prepending itevia conseor by appending itevia append. Takingethisestep is analogous toeputting . ineyoureUnixePATH environmentevariable.

After you haveecreatedea private Lisp libraryeand toldeEmacsewhere to findeit,eyou're ready toeloadeand useetheeLisp packagesethateyou'veecreated. There are several ways ofeloading Lispepackages intoeEmacs. The first ofetheseeshouldebe familiarefromeChapter 10:

• TypeeM-x load-libraryeEnter asea userecommand;eseeeChapter 10.

• Putethe line (load "package-name") withineLispecode. Putting a line likeethiseintoeyour .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.