Xah Lee, 2008-07
This pages gives a general install instruction for emacs package you downloaded from the web.
There are hundreds of useful emacs packages on the web that are not bundled with emacs. Some are for special purposes such as making emacs act as a mp3 player, some provided some extra functionalities, some are modes for less popular languages. Often, there is no install instruction included, and you may notice that each's installation methods seem to differ wildly. The following gives a over view on how emacs package is installed.
Suppose you downloaded a new emacs packages on the web named “xyz.el”. To install this, all you have to do is to make emacs load the file. Just open the file, then type “Alt+x eval-buffer”, then you are all done.
If you want emacs to automatically load the file when it starts, put the following in your emacs init file:
;; Tell emacs where is your personal elisp lib dir ;; this is the dir you have the xyz.el file (add-to-list 'load-path "~/my_emacs_lib/") ;; load the packaged named xyz. (load "xyz") ;; best not to include the ending “.el” or “.elc”
Alternatively, you can also just do:
(load-file "~/Documents/emacs/xyz.el")
What's the difference between “load-file” and “load”?
“load-file” is designed to load one specific file, taking a specific file path.
“load” is designed to find the file thru the paths in the variable “load-path”. For example, if you have “(load "xyz")”, then emacs will try first to load file named “xyz.elc” by searching thru the dirs in “load-path” variable, if none found, it'll try “xyz.el”, and few other alternative.
Both load and load-file can accept full path or paths starting with “~”.
(info "(emacs) Lisp Libraries")
Elisp source code can be byte compiled. When a file is byte compiled, it loads faster, and the functions will run faster too (about 6 times faster). For packages that's just few hundred of lines of not very complex functions, the difference in speed is usually not noticeable in today's computer.
To compile your code, type “Alt+x byte-compile-file”. Once you compiled the code, you'll get a file with suffix “.elc”. When you call “(load "xyz")” without specifying the file extension, emacs'll automatically try to load “xyz.elc” first, if it doesn't exist, emacs'll then try “xyz.el”.
(info "(elisp) Byte Compilation")
Emacs determines what mode to use primarily by 2 mechanisms, in order: (1) Check the first line in the file, using “magic-mode-alist”. (2) Check the file name's suffix, using “auto-mode-alist”.
The “magic-mode-alist” is a list that emacs use to match the first line of a file with a mode. For example, if you want files that begin with the line “<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...” to always use nxml-mode, then add the following to your emacs init file:
(add-to-list
'magic-mode-alist
'("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"" . nxml-mode))
The magic-mode-alist is a list. In the above example, the string with the “DOCTYPE” is a regex, used to match the first line of a file.
If emacs goes thru magic-mode-alist and didn't find any match, then it'll use auto-mode-alist to check on file name suffix. The “auto-mode-alist” associates a file name suffix with a mode. For example, if you want files ending in “.js” to always open with js2-mode, then do:
(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
Note: The double backslash in the string “\\.js\\'” is used to escape the backslash. So, the regex engine just got “\.js\'”. The “\.” is to match a period. The “\'” is one of emacs special regex syntax, to match end of a string. (See also: Text Pattern Matching in Emacs)
(info "(elisp) Regexp Backslash")
You can see what are the values of magic-mode-alist or auto-mode-alist by typing “Alt+x describe-variable”.
There are few minor details about how emacs determines what mode to load, but the above should cover vast majority of needs. For detail, see emacs manual.
(info "(emacs) Choosing Modes")
Elisp has a feature that's loading function's definition only when needed, by the function “autoload”. The advantage is that users don't need to load all the packages when emacs starts. With autoload, packages will only load when it is actually called.
The “autolad” function associates a function's name with its source code file location. When the function is called, emacs executes the file that contains the function's definition then executes the function. This way, it saves emacs from pre-loading its few thousand functions when it launches. But user can still call functions or commands as if it is already loaded.
Some emacs mode are over ten thousand lines of code. (e.g. js2-mode, nxml-mode, CEDET) Many packages make use of the autoload feature, so that you only need to load a single file that define autoloaded functions.
For example, nxml mode's instruction tells you to do:
(load-file "~/Documents/emacs/nxml-mode-20041004/rng-auto.el")
The above loads the file, which sets up autoloading by making various “autoload” calls.
For another example, js2-mode's install instruction tells you to put the following in your emacs init file:
(autoload 'js2-mode "js2" nil t)
The above code means this: when function “js2-mode” is called, load it from the library named “js2”. Emacs will call “load” to load it, and it finds the js2 library by searching the dir paths in the variable “load-path”.
If there is a package you always want it loaded, use “require”. This function is mostly used in elisp coding, similar to Perl's “require”, PHP's “require()”, python's “import”, Java's “import”.
You usually don't want to use “require” for installing packages.
Emacs mode usually comes with inline documentation. To view it, first switch to the mode by typing “Alt+x ‹mode name›”. Once in the mode, type “Alt+x describe-mode”. Emacs will show its inline documentation. (Emacs will first list a bunch of minor modes thats on.)
Robust modes usually have graphical menus too. So, switch to the mode, then you can check what menu commands it has in the menu bar.
Sometimes, a mode comes with complete documentation in “info” format (file with suffix “.info”). To read the info, type “Ctrl+u Alt+x info” then type the info file's name.
Here's a bit technical detail about some elisp issues related to library. Knowing it helps you a bit when installing packages.
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.
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” is just some elisp files that do something useful. A “package” usually refers to a particular one. The term “module” is not used by emacs.
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. This elisp symbol, can be placed on the predefined global variable named “features”, which is a list of symbols. For example, here's part of the value of “features” when i do “Ctrl+h v 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.
There is no absolute relation between any concept of package/library/module/feature/autoload facilities and the file name. By convention, if a elisp file name is “xyz-mode.el”, it usually provides a lisp symbol “xyz-mode” as emacs feature, and the function is often “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.
Emacs's library/module/package is a primitive system, centered on loading file (load-file), with some slightly high level things such as its “features”, “autoload”, “require”. However, nothing is strict or enforced by elisp.
| Function Name | Purpose | Tech Detail | Comment |
|---|---|---|---|
| load-file | Load a specific file. | Loads a file of a give file path. | This is the most basic mechanism. |
| load | Load a file by a package name. | Load a file by searching thru var “load-path”. Also, tries to load a compiled version if exists. | This is slightly higher lever than load-file, by using the concept of package name. However, elisp does not define what's a package name in any technical way. |
| autoload | Load a file only when a function is called. Save startup time. | Associate a function's symbol 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. |
| require | Load a file if it has not already been loaded. | Checks the var “features”, if symbol is not there, then call “load” to load it. | This is used in elisp coding, similar to other lang's “require” or “import”. |
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”, “OPQ helper”, or anything else. And, this file can be considered as a package as well as library.