2010-07-13

Emacs Lisp's Library System

Perm url with updates: http://xahlee.org/emacs/elisp_library_system.html

Emacs Lisp's Library System

Xah Lee, 2010-07-13

This page explains emacs library system. For example, what's the difference between library, package, features? And what's the difference between load-file, load, require, autoload?

What's Library, Package, Feature?

No Namespace

Emacs lisp the language does not have name spaces. Everything is global, with dynamic scope, with some shadowing mechanism. So, don't expect library or module to be language defined name space constructs that somewhat enforce name space and file name relation, as in Perl, Python, Java.

What's the difference between a Package and Library?

The terms “package” and “library”, are used losely in emacs/elisp manual to refer to any useful elisp file. They are not technical definitions in elisp.

A “library” usually refers to elisp file containing a collection of lisp functions, to be called by other lisp source code. For example, the command backward-word is defined in “simple.el”, which is a library of functions.

A “package” usually refers to something useful for emacs users, like a major mode or minor mode. The term “module” is not used by emacs.

Emacs's Concept of “Feature”

The term “feature” has some meaning in elisp, but is not mechanical. A “feature” is a elisp symbol, that is intended to represent the functionality provided by a emacs package.

For example, here's part of the value of “features” when i do “Alt+x describe-variable Enter features”:

ibuffer etags ring cc-mode cc-fonts cc-menus cc-cmds cc-styles
cc-align cc-engine cc-vars cc-defs xlsl-mode encoded-kb speck
sgml-mode dired info newcomment desktop recentf tree-widget wid-edit
advice help-fns ...

A elisp file can call “(provide ‹some symbol›)” near the end, which adds that symbol to the “features” list. The purpose of features and the “features” variable is to provide a way for emacs to know if something is already loaded. The “require” function checks the “features” to see if a symbol is already there before loading the file.

Package/Library/Feature are not Managed

There is no absolute relation between any concept of package/library/feature/autoload facilities and the file name.

By convention, if a elisp file name is “xyz-mode.el”, it OFTEN provides a lisp symbol “xyz-mode” as its feature name (it may not), and the function to invoke the mode is OFTEN named “xyz-mode”. Sometimes the “mode” part is dropped in the file name, feature symbol, or function name.

This is only a lose convention. There are a lot exceptions in many bundled emacs packages. For example, the file “lisp-mode.el” provides the symbol “lisp-mode” as feature, and is invoked by “emacs-lisp-mode”. The “cua-base.el” file provides symbols “cua-base” and “cua” as features, and is invoked by cua-mode. The “text-mode.el” file does not provide any symbol for feature, but is a quite useful mode invoked by text-mode. The file “desktop.el” provides “desktop” as feature, and is invoked by desktop-save-mode.

All the above means, you could have a file named “xyz.el”, which provides a feature named “abc”, while it really just provide a mode to user with the command name “opq-mode” or sometimes just “opq”, and it might be displayed in mode line as “OPQ helper”, or anything else. And, this file can be considered as a package as well as library.

File/Package Loading Mechanisms

Emacs's module system is a primitive system, centered on loading file, with some slightly high level things such as its “features”, “autoload”, “require”. However, nothing is strict or enforced by elisp.

Function NamePurposeTech DetailComment
load-fileLoad a file.Load one specific file.Use this if you have one very SPECIFIC file at one particular file path.
loadLoad a file.Load a file by searching thru var “load-path”. Also, tries to load a compiled version (.elc) if exists.Use this if there are several possible location for the file, and you are using a short file name such as “undo.el” or “undo”, and you want to load the compiled version if it exists (“undo.elc”).
requireLoad a package if it has not already been loaded.Checks the var “features”, if symbol is not there, then call “load” to load it.Best used in elisp source code, similar to other lang's “require” or “import”.
autoloadLoad a file only when a function is called.Associate a function name with a file path. When the function is called, load the file, and execute the function.It is good to use this when you install a package. It save startup time and makes emacs use less system resource.

See also: How To Name Your Emacs Major Mode.

Isn't this all very bad?

Yes it is.

Though, it's just the state of software. Many most popular langs, such as C, C++, PHP, do worse. They don't have a module system neither, but worse, they load a file by “include”. Note that even Scheme Lisp didn't have module system, until R6RS, released in 2007, and the new module system defined in it is widely criticized, and R6RS caused Scheme community to split.