Node:defcustom, Next:Beginning a .emacs File, Previous:Site-wide Init, Up:Emacs Initialization
You can specify variables using
defcustom so that you and
others can then can use Emacs'
customize feature to set their
values. (You cannot use
customize to write function
definitions; but you can write
defuns in your
file. Indeed, you can write any Lisp expression in your
customize feature depends on the
form. Although you can use
setq for variables
that users set, the
defcustom special form is designed for the
You can use your knowledge of
defvar for writing the
first three arguments for
defcustom. The first argument to
defcustom is the name of the variable. The second argument is
the variable's initial value, if any; and this value is set only if
the value has not already been set. The third argument is the
The fourth and subsequent arguments to
defcustom specify types
and options; these are not featured in
arguments are optional.)
Each of these arguments consists of a keyword followed by a value.
Each keyword starts with the character
For example, the customizable user option variable
text-mode-hook looks like this:
(defcustom text-mode-hook nil "Normal hook run when entering Text mode and many related modes." :type 'hook :options '(turn-on-auto-fill flyspell-mode) :group 'data)
The name of the variable is
text-mode-hook; it has no default
value; and its documentation string tells you what it does.
:type keyword tells Emacs what kind of data
text-mode-hook should be set to and how to display the value in
a Customization buffer.
:options keyword specifies a suggested list of values for
the variable. Currently, you can use
:options only for a hook.
The list is only a suggestion; it is not exclusive; a person who sets
the variable may set it to other values; the list shown following the
:options keyword is intended to offer convenient choices to a
:group keyword tells the Emacs Customization
command in which group the variable is located. This tells where to
For more information, see Customization.
text-mode-hook as an example.
There are two ways to customize this variable. You can use the customization command or write the appropriate expressions yourself.
Using the customization command, you can type:
and find that the group for editing files of data is called `data'. Enter that group. Text Mode Hook is the first member. You can click on its various options to set the values. After you click on the button to
Save for Future Sessions
Emacs will write an expression into your
It will look like this:
(custom-set-variables ;; custom-set-variables was added by Custom -- ;; don't edit or cut/paste it! ;; Your init file should contain only one such instance. '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
text-mode-hook-identify function tells
toggle-text-mode-auto-fill which buffers are in Text mode.)
In spite of the warning, you certainly may edit, cut, and paste the expression! I do all time. The purpose of the warning is to scare those who do not know what they are doing, so they do not inadvertently generate an error.
custom-set-variables works somewhat differently than a
setq. While I have never learned the differences, I do modify
custom-set-variables expressions in my
by hand: I make the changes in what appears to me to be a reasonable
manner and have not had any problems. Others prefer to use the
Customization command and let Emacs do the work for them.
custom-set-... function is
This function sets the various font faces. Over time, I have set a
considerable number of faces. Some of the time, I re-set them using
customize; other times, I simply edit the
custom-set-faces expression in my
.emacs file itself.
The second way to customize your
text-mode-hook is to set it
yourself in your
.emacs file using code that has nothing to do
When you do this, and later use
customize, you will see a
message that says
this option has been changed outside the customize buffer.
This message is only a warning. If you click on the button to
Save for Future Sessions
Emacs will write a
custom-set-... expression near the end
.emacs file that will be evaluated after your
hand-written expression. It will, therefore, overrule your
hand-written expression. No harm will be done. When you do this,
however, be careful to remember which expression is active; if you
forget, you may confuse yourself.
So long as you remember where the values are set, you will have no
trouble. In any event, the values are always set in your
initialization file, which is usually called
I myself use
customize for hardly anything. Mostly, I write