A variable definition is a construct that announces your intention to use a symbol as a global variable. It uses the special forms
defconst, which are documented below.
A variable definition serves three purposes. First, it informs people who read the code that the symbol is intended to be used a certain way (as a variable). Second, it informs the Lisp system of this, optionally supplying an initial value and a documentation string. Third, it provides information to programming tools such as
etags, allowing them to find where the variable was defined.
The difference between
defvar is mainly a matter of intent, serving to inform human readers of whether the value should ever change. Emacs Lisp does not actually prevent you from changing the value of a variable defined with
defconst. One notable difference between the two forms is that
defconst unconditionally initializes the variable, whereas
defvar initializes it only if it is originally void.
To define a customizable variable, you should use
defcustom (which calls
defvar as a subroutine). See Variable Definitions.
special form defvar symbol [value [doc-string]]
This special form defines
symbol as a variable. Note that
symbol is not evaluated; the symbol to be defined should appear explicitly in the
defvar form. The variable is marked as special, meaning that it should always be dynamically bound (see Variable Scoping).
value is specified, and
symbol is void (i.e., it has no dynamically bound value; see Void Variables), then
value is evaluated and
symbol is set to the result. But if
symbol is not void,
value is not evaluated, and
symbol’s value is left unchanged. If
value is omitted, the value of
symbol is not changed in any case.
Note that specifying a value, even
nil, marks the variable as special permanently. Whereas if
value is omitted then the variable is only marked special locally (i.e. within the current lexical scope, or file if at the top-level). This can be useful for suppressing byte compilation warnings, see Compiler Errors.
symbol has a buffer-local binding in the current buffer,
defvar acts on the default value, which is buffer-independent, rather than the buffer-local binding. It sets the default value if the default value is void. See Buffer-Local Variables.
symbol is already lexically bound (e.g., if the
defvar form occurs in a
let form with lexical binding enabled), then
defvar sets the dynamic value. The lexical binding remains in effect until its binding construct exits. See Variable Scoping.
When you evaluate a top-level
defvar form with
C-M-x in Emacs Lisp mode (
eval-defun), a special feature of
eval-defun arranges to set the variable unconditionally, without testing whether its value is void.
doc-string argument is supplied, it specifies the documentation string for the variable (stored in the symbol’s
variable-documentation property). See Documentation.
Here are some examples. This form defines
foo but does not initialize it:
This example initializes the value of
23, and gives it a documentation string:
(defvar bar 23
"The normal weight of a bar.")
defvar form returns
symbol, but it is normally used at top level in a file where its value does not matter.
For a more elaborate example of using
defvar without a value, see Local defvar example.
special form defconst symbol value [doc-string]
This special form defines
symbol as a value and initializes it. It informs a person reading your code that
symbol has a standard global value, established here, that should not be changed by the user or by other programs. Note that
symbol is not evaluated; the symbol to be defined must appear explicitly in the
defconst form, like
defvar, marks the variable as special, meaning that it should always be dynamically bound (see Variable Scoping). In addition, it marks the variable as risky (see File Local Variables).
defconst always evaluates
value, and sets the value of
symbol to the result. If
symbol does have a buffer-local binding in the current buffer,
defconst sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with
An example of the use of
defconst is Emacs’s definition of
float-pi—the mathematical constant pi, which ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however,
defconst is only advisory.
(defconst float-pi 3.141592653589793 "The value of Pi.")
(setq float-pi 3)
Warning: If you use a
defvar special form while the variable has a local binding (made with
let, or a function argument), it sets the local binding rather than the global binding. This is not what you usually want. To prevent this, use these special forms at top level in a file, where normally no local binding is in effect, and make sure to load the file before making a local binding for the variable.