Customizable variables, also called user options, are
global Lisp variables whose values can be set through the Customize
interface. Unlike other global variables, which are defined with
defvar (see Defining Global Variables), customizable variables are
defined using the
defcustom macro. In addition to calling
defvar as a subroutine,
defcustom states how the
variable should be displayed in the Customize interface, the values it
is allowed to take, etc.
This macro declares option as a user option (i.e., a customizable variable). You should not quote option.
The argument standard is an expression that specifies the
standard value for option. Evaluating the
evaluates standard, but does not necessarily bind the option to
that value. If option already has a default value, it is left
unchanged. If the user has already saved a customization for
option, the user’s customized value is installed as the default
value. Otherwise, the result of evaluating standard is
installed as the default value.
defvar, this macro marks
option as a special
variable, meaning that it should always be dynamically bound. If
option is already lexically bound, that lexical binding remains
in effect until the binding construct exits. See Scoping Rules for Variable Bindings.
The expression standard can be evaluated at various other times, too—whenever the customization facility needs to know option’s standard value. So be sure to use an expression which is harmless to evaluate at any time.
The argument doc specifies the documentation string for the variable.
defcustom does not specify any
:group, the last group
defgroup in the same file will be used. This way, most
defcustom do not need an explicit
When you evaluate a
defcustom form with C-M-x in Emacs Lisp
eval-defun), a special feature of
arranges to set the variable unconditionally, without testing whether
its value is void. (The same feature applies to
see Defining Global Variables.) Using
eval-defun on a defcustom
that is already defined calls the
:set function (see below),
if there is one.
If you put a
defcustom in a pre-loaded Emacs Lisp file
(see Building Emacs), the standard value installed at dump time
might be incorrect, e.g., because another variable that it depends on
has not been assigned the right value yet. In that case, use
custom-reevaluate-setting, described below, to re-evaluate the
standard value after Emacs starts up.
In addition to the keywords listed in Common Item Keywords, this macro accepts the following keywords:
Use type as the data type for this option. It specifies which
values are legitimate, and how to display the value
(see Customization Types). Every
defcustom should specify
a value for this keyword.
Specify the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives.
This is meaningful only for certain types, currently including
alist. See the definition of the
individual types for a description of how to use
defcustom form with a different
value does not clear the values added by previous evaluations, or
added by calls to
custom-add-frequent-value (see below).
Specify setfunction as the way to change the value of this
option when using the Customize interface. The function
setfunction should take two arguments, a symbol (the option
name) and the new value, and should do whatever is necessary to update
the value properly for this option (which may not mean simply setting
the option as a Lisp variable); preferably, though, it should not
modify its value argument destructively. The default for
If defined, setfunction will also be called when evaluating a
defcustom form with C-M-x in Emacs Lisp mode and when the
option’s value is changed via the
If you specify this keyword, the variable’s documentation string
should describe how to do the same job in hand-written Lisp code,
either by invoking setfunction directly or by using
Specify getfunction as the way to extract the value of this
option. The function getfunction should take one argument, a
symbol, and should return whatever customize should use as the
current value for that symbol (which need not be the symbol’s Lisp
value). The default is
You have to really understand the workings of Custom to use
:get correctly. It is meant for values that are treated in
Custom as variables but are not actually stored in Lisp variables. It
is almost surely a mistake to specify getfunction for a value
that really is stored in a Lisp variable.
function should be a function used to initialize the variable
defcustom is evaluated. It should take two arguments,
the option name (a symbol) and the value. Here are some predefined
functions meant for use in this way:
Use the variable’s
:set function to initialize the variable, but
do not reinitialize it if it is already non-void.
custom-initialize-set, but use the function
set-default-toplevel-value to set the variable, instead of the
:set function. This is the usual choice for a
:set function enables or disables a minor mode;
with this choice, defining the variable will not call the minor mode
function, but customizing the variable will do so.
Always use the
:set function to initialize the variable. If
the variable is already non-void, reset it by calling the
function using the current value (returned by the
This is the default
:set function to initialize the variable, if it is
already set or has been customized; otherwise, just use
This function behaves like
custom-initialize-set, but it
delays the actual initialization to the next Emacs start. This should
be used in files that are preloaded (or for autoloaded variables), so
that the initialization is done in the run-time context rather than
the build-time context. This also has the side-effect that the
(delayed) initialization is performed with the
See Building Emacs.
If the value is
t, mark option as automatically
buffer-local; if the value is
permanent, also set options
permanent-local property to
t. See Creating and Deleting Buffer-Local Bindings.
Set the variable’s
risky-local-variable property to
value (see File Local Variables).
Set the variable’s
safe-local-variable property to
function (see File Local Variables).
When setting variables according to saved customizations, make sure to
set the variables variables before this one; i.e., delay
setting this variable until after those others have been handled. Use
:set-after if setting this variable won’t work properly unless
those other variables already have their intended values.
It is useful to specify the
:require keyword for an option
that turns on a certain feature. This causes Emacs to load the
feature, if it is not already loaded, whenever the option is set.
See Common Item Keywords. Here is an example:
(defcustom frobnicate-automatically nil "Non-nil means automatically frobnicate all buffers." :type 'boolean :require 'frobnicate-mode :group 'frobnicate)
If a customization item has a type such as
alist, which supports
:options, you can add additional
values to the list from outside the
defcustom declaration by
custom-add-frequent-value. For example, if you define a
my-lisp-mode-initialization intended to be called from
emacs-lisp-mode-hook, you might want to add that to the list of
reasonable values for
emacs-lisp-mode-hook, but not by editing
its definition. You can do it thus:
(custom-add-frequent-value 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
For the customization option symbol, add value to the list of reasonable values.
The precise effect of adding a value depends on the customization type of symbol.
Since evaluating a
defcustom form does not clear values added
previously, Lisp programs can use this function to add values for user
options not yet defined.
defcustom uses the symbol property
standard-value to record the expression for the standard value,
saved-value to record the value saved by the user with the
customization buffer, and
customized-value to record the value
set by the user with the customization buffer, but not saved.
See Symbol Properties. In addition, there’s
which is used to record the value set by a theme (see Custom Themes). These properties are lists, the car of which is an
expression that evaluates to the value.
This function re-evaluates the standard value of symbol, which
should be a user option declared via
defcustom. If the
variable was customized, this function re-evaluates the saved value
instead. Then it sets the user option to that value (using the
:set property if that is defined).
This is useful for customizable options that are defined before their value could be computed correctly. For example, during startup Emacs calls this function for some user options that were defined in pre-loaded Emacs Lisp files, but whose initial values depend on information available only at run-time.
This function returns non-
nil if arg is a customizable
variable. A customizable variable is either a variable that has a
custom-autoload property (usually
meaning it was declared with
defcustom), or an alias for
another customizable variable.