6 Configuration Basics

You configure CC Mode by setting Lisp variables and calling (and perhaps writing) Lisp functions15, which is usually done by adding code to an Emacs initialization file. This file might be site-start.el or .emacs or init.el or default.el or perhaps some other file. See Init File in GNU Emacs Manual. For the sake of conciseness, we just call this file “your .emacs” throughout the rest of the manual.

Several of these variables (currently 16), are known collectively as style variables. CC Mode provides a special mechanism, known as styles to make it easier to set these variables as a group, to “inherit” settings from one style into another, and so on. Style variables remain ordinary Lisp variables, whose values can be read and changed independently of the style system. See Style Variables.

There are several ways you can write the code, depending on the precise effect you want—they are described further down on this page. If you are new to CC Mode, we suggest you begin with the simplest method, “Top-level commands or the customization interface”.

If you make conflicting settings in several of these ways, the way that takes precedence is the one that appears latest in this list:

Here is a summary of the different ways of writing your configuration settings:

Top-level commands or the “customization interface”

Most simply, you can write setq and similar commands at the top level of your .emacs file. When you load a CC Mode buffer, it initializes its configuration from these global values (at least, for those settings you have given values to), so it makes sense to have these setq commands run before CC Mode is first initialized—in particular, before any call to desktop-read (see Saving Emacs Sessions in GNU Emacs Manual). For example, you might set c-basic-offset thus:

(setq c-basic-offset 4)

You can use the more user friendly Customization interface instead, but this manual does not cover in detail how that works. To do this, start by typing M-x customize-group RET c RET. See Easy Customization in GNU Emacs Manual. Emacs normally writes the customizations at the end of your .emacs file. If you use desktop-read, you should edit your .emacs to place the call to desktop-read after the customizations.

The first initialization of CC Mode puts a snapshot of the configuration settings into the special style user. See Built-in Styles.

For basic use of Emacs, either of these ways of configuring is adequate. However, the settings are then the same in all CC Mode buffers and it can be clumsy to communicate them between programmers. For more flexibility, you’ll want to use one (or both) of CC Mode’s more sophisticated facilities, hooks and styles.

Hooks

An Emacs hook is a place to put Lisp functions that you want Emacs to execute later in specific circumstances. See Hooks in GNU Emacs Lisp Reference Manual. CC Mode supplies a main hook and a language-specific hook for each language it supports; any functions you put onto these hooks get executed as the last part of a buffer’s initialization. Typically you put most of your customization within the main hook, and use the language-specific hooks to vary the customization settings between language modes. For example, if you wanted different (non-standard) values of c-basic-offset in C Mode and Java Mode buffers, you could do it like this:

(defun my-c-mode-hook ()
  (setq c-basic-offset 3))
(add-hook 'c-mode-hook 'my-c-mode-hook)

(defun my-java-mode-hook ()
  (setq c-basic-offset 6))
(add-hook 'java-mode-hook 'my-java-mode-hook)

See Hooks for more details on the use of CC Mode hooks.

Styles

A CC Mode style is a coherent collection of customizations with a name. At any time, exactly one style is active in each CC Mode buffer, either the one you have selected or a default. CC Mode is delivered with several existing styles. Additionally, you can create your own styles, possibly based on these existing styles. If you worked in a programming team called the “Free Group”, which had its own coding standards, you might well have this in your .emacs file:

(setq c-default-style '((java-mode . "java")
                        (awk-mode . "awk")
                        (other . "free-group-style")))

See Styles for fuller details on using CC Mode styles and how to create them.

File Local Variable setting

A file local variable setting is a setting which applies to an individual source file. You put this in a local variables list, a special block at the end of the source file (see (emacs)Specifying File Variables).

File Styles

A file style is a rarely used variant of the “style” mechanism described above, which applies to an individual source file. See File Styles. You use this by setting certain special variables in a local variables list (see (emacs)Specifying File Variables).

Hooks with Styles

For ultimate flexibility, you can use hooks and styles together. For example, if your team were developing a product which required a Linux driver, you’d probably want to use the “linux” style for the driver, and your own team’s style for the rest of the code. You could achieve this with code like this in your .emacs:

(defun my-c-mode-hook ()
  (c-set-style
   (if (and (buffer-file-name)
            (string-match "/usr/src/linux" (buffer-file-name)))
       "linux"
     "free-group-style")))
(add-hook 'c-mode-hook 'my-c-mode-hook)

In a programming team, a hook is also a good place for each member to put his own personal preferences. For example, you might be the only person in your team who likes Auto-newline minor mode. You could have it enabled by default by placing the following in your .emacs:

(defun my-turn-on-auto-newline ()
  (c-toggle-auto-newline 1))
(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline)

Footnotes

(15)

DON’T PANIC!!! This isn’t difficult.

(16)

In earlier versions of CC Mode, a File Style setting took precedence over any other setting apart from a File Local Variable setting.