Confusing about the Emacs custom system

Question

There are several similar setting functions:

1. set & setq
2. set-default
3. defcustom
4. custom-set-value
5. custom-set-variables
6. customize-set-value
7. customize-set-variable

so, what's the difference between these functions?

If I want setting my own preferences to an add-on, for these scenario:

1. If a variable setting by defcustom, which setting-function will be better?
2. And what about a variable setting by defvar?

Answer 1

The short answer to you question is:

• use setq or setq-default for variables defined by defvar.

• use setq, setq-default, or the Customize mechanism for variables defined by defcustom

Below is the long answer.

The functions that you are going to use are the following:

• set is the main function to set the value of a variable.

• setq is another version that automatically quotes its first argument. This is useful since quoting the first argument is what you want to do almost all the time.

• Some variables cannot be set globally. Whenever you set the variable it is only set for the current buffer. If you want to simulate setting this variable globally you use set-default or setq-default.

The functions that a package writer uses are:

• defvar which allows the package writer to define a variable and to give some documentation. This function is not required but makes the life of users easier.

• defcustom builds on defvar. It tells emacs that it is a variable, and it allows the developer to create a custom interface to set the value. The developer can say, things like "this variable can contain only the value 'foo or 'bar".

Setting variables can be done two ways:

1. if defvar was used, the values can only be set by the user in its .emacs by using the set function (or variants)

2. if defcustom was used, the values can be set using set (see 1.) OR by using Customize. When using the customize mechanism, emacs will generate some code that it will place in custom-set-variables. The user should not use this function.

Answer 2

They are, largely all paths to the same thing. There are some important differences though. The best way to get to know them is to read the manuals for Emacs and Elisp (see C-h i). Off the top of the head though:

• set is a "low-level" variable assignment
• (setq foo bar) is shorthand for (set (quote foo) bar)
• (set-default foo bar) means "unless there is a more explicitly scoped definition of foo in the current buffer, use the value bar", and applies to all buffers.
• defcustom is used to mark a variable as one that the user is expected to be able to safely modify through the customize feature.
• custom-set-value and customize-set-value are two names that point to the same function. They're convenience methods for working with the customize system.
• custom-set-variables and customize-set-variables are used to make some set of customized-through-customize variables active, IIRC.

In general, it's recommended to use M-x customize to change things around. You're free to set things defined with defcustom using set or setq in your .emacs, the customize system will warn you about it if you later change it via customize though.

defcustom is generally only used by people writing packages meant for distribution, and I don't think I've seen anyone use custom-set-* outside of files internal to customize. setq is very common in people's initialization files for setting things up how they like them, regardless of whether those things are marked for use with customize or not.

I don't have a full understanding of all this, hopefully someone else can shed more light, but I think that that's a fairly good overview :P

Answer 3

1. set and setq are the lowest level primitives used for assigning any kind of variable.
2. set-default and setq-default are emacs extensions that go along with buffer-local variables, to allow setting the default values used for new buffers. 3-7. All the "custom" stuff is a later addition that was designed to support a user interface for managing variables that are intended to be used as user preferences.
3. defcustom is similar to defvar, but allows you to specify a place in the hierarchy of options, as well as data type information so that the UI can display the value as a menu, or automatically convert user input to the appropriate type.
4. I don't think there is a custom-set-value function.
5. custom-set-variables is used by the customize UI when saving all the user's options. It lists all the variables that the user has changed from their defaults. 6-7. custom-set-value and custom-set-variable are used by the Customize UI to prompt the user for the current and default values of an option variable, and assign them. You don't normally call this yourself.