This page 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. (e.g. Dictionary Lookup, Twitter, enhanced dir viewer DiredPlus mode, enhanced bookmark ( BookmarkPlus), modes for less popular languages ( PowerShell Modes, Visual Basic Mode, OCaml/F#, AutoHotkey Mode,BBCode mode ). Often, there is no install instruction included, and you may notice that each's installation methods seem to differ wildly. The following gives a overview on how emacs package are installed.
Loading the File
Just Load the File to Test Manually First
Suppose you downloaded a simple emacs package on the web named “xyz.el” that is is just one single file. To use the package, all you have to do is to make emacs load the file. Just open the file, then type 【Alt+x eval-buffer】, then you can start to use whatever commands or new features provided by that package.
Place it in your 〔~/.emacs.d/〕 directory
If you want emacs to automatically load the file when it starts, put the file in the dir 〔~/.emacs.d/〕, then put the following in your emacs init file:
;; Tell emacs where is your personal elisp lib dir
;; this is the dir you place all your extra packages
(add-to-list 'load-path "~/.emacs.d/")
;; load the packaged named xyz.
(load "xyz") ;; best not to include the ending “.el” or “.elc”
What is the Purpose of 〔~/.emacs.d/〕 Path?
By convention, the 〔~/.emacs.d/〕 is a dir for all your personal packages. It is the default value of the variable “user-emacs-directory”. On Windows, the path is 〔%HOMEPATH%\.emacs.d\〕. (see also: Windows Environment Variables.) Emacs 23 should have created this dir for you. If it's not there, you can just create it yourself.
Byte Compile
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")
Auto-Activation of Mode When Opening File
See: Emacs: How to Associate a File with a Major Mode?.
Mode Documentation
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.
“load-file”, “load”, “autoload”, “require” …
What's the difference between “load-file” and “load”?
“load-file” is designed to load one specific file, taking a specific file path, usually a full path.
“load” is designed to find the file thru the paths in different locations, and load the compiled version (“.elc”) if it exists. For example, if you have
(load "xyz"), then emacs will first try 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, relative path, or paths starting with “~”.
What's the difference between “require” and “load”?
Sometimes you'll see the installation instruction telling you to use “require”, like this:
(require 'redo)
“require” will check if the symbol is already loaded, if so, it won't load it again. Load will always load it (if it can find the file in the var “load-path”.).
“require” checks if a package is already loaded by looking for the package's special symbol name in the value of the var named “features”.
The argument to require is a lisp symbol (followed by a optional path). The argument to “load” is a file name or path.
(info "(emacs) Lisp Libraries")
(info "(elisp) Loading")
What is “autoload”?
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. They have a special elisp file that's mostly just autoload calls. So, to run the package, you simply load this file that setup autoload.
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 “rng-auto.el”. This file actually contain a bunch of “autoload” calls, which sets up autoloading, while not actually really loading the package.
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 the command “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”.
Importing/Requiring a Library
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”, python's “import”, PHP's “require()”, Java's “import”.
You usually don't want to use “require” for installing packages.
Tech Detail of Emacs Lisp's Library System
For more detail about the difference of emacs's concept of package, libraries, features, modes, and between load-file, load, require, autoload, see: Emacs Lisp's Library System.
