defcustom to declare user-customizable variables.
This macro declares option as a customizable user option. You should not quote option.
This causes the function
twhen given option as an argument. See Defining Variables. The argument doc specifies the documentation string for the variable. (Note that there is no need to start doc with a ‘*’.)
The argument standard is an expression that specifies the standard value for option. Evaluating the
defcustomform evaluates standard, but does not necessarily install the standard value. If option already has a default value,
defcustomdoes not change it. If the user has saved a customization for option,
defcustominstalls the user's customized value as option's default value. If neither of those cases applies,
defcustominstalls the result of evaluating standard as the default value.
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. We recommend avoiding backquotes in standard, because they are not expanded when editing the value, so list values will appear to have the wrong structure.
:groupat least once.
If you specify the
:setkeyword, to make the variable take other special actions when set through the customization buffer, the variable's documentation string should tell the user specifically how to do the same job in hand-written Lisp code.
When you evaluate a
defcustomform with C-M-x in Emacs Lisp mode (
eval-defun), a special feature of
eval-defunarranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to
defvar.) See Defining Variables.
If you put a
defcustomin a file that is preloaded at dump time (see Building Emacs), and the standard value installed for the variable at that time might not be correct, use
custom-reevaluate-setting, described below, to re-evaluate the standard value during or after Emacs startup.
defcustom accepts the following additional keywords:
This is meaningful only for certain types, currently including
alist. See the definition of the
individual types for a description of how to use
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.
defcustomis 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:
:setfunction to initialize the variable, but do not reinitialize it if it is already non-void.
custom-initialize-set, but use the function
set-defaultto set the variable, instead of the variable's
:setfunction. This is the usual choice for a variable whose
:setfunction 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.
:setfunction to initialize the variable. If the variable is already non-void, reset it by calling the
:setfunction using the current value (returned by the
:getmethod). This is the default
:setfunction to initialize the variable, if it is already set or has been customized; otherwise, just use
custom-initialize-default, respectively), but catch errors. If an error occurs during initialization, they set the variable to
set-default, and throw no error.
These two functions are only meant for options defined in pre-loaded files, where some variables or functions used to compute the option's value may not yet be defined. The option normally gets updated in startup.el, ignoring the previously computed value. Because of this typical usage, the value which these two functions compute normally only matters when, after startup, one unsets the option's value and then reevaluates the defcustom. By that time, the necessary variables and functions will be defined, so there will not be an error.
risky-local-variableproperty to value (see File Local Variables).
safe-local-variableproperty to function (see File Local Variables).
:set-afterif 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 Keywords. Here is an example, from the library
(defcustom save-place nil "Non-nil means automatically save place in each file..." :type 'boolean :require 'saveplace :group 'save-place)
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.
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 Property Lists. 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.) This is useful for customizable options that are defined before their value could be computed correctly, such as variables defined in packages that are loaded at dump time, but depend on the run-time information. For example, the value could be a file whose precise name depends on the hierarchy of files when Emacs runs, or a name of a program that needs to be searched at run time.
A good place to put calls to this function is in the function
command-linethat is run during startup (see Startup Summary) or in the various hooks it calls.