.EL File Format – File structure

The first line

By convention the first line of a library is ;;; NAME.el --- SUMMARY, with one space after --- and the summary under about 60 characters, optionally followed by a cookie. A cookie is the text between two -*- marks: a list of variable: value pairs separated by semicolons, which Emacs applies as file-local settings when it visits the file. When the first line begins with #! (a script), the cookie may be on the second line instead. A line with only one value and no colon is a mode name: -*- emacs-lisp -*- means mode: emacs-lisp.

;;; greet.el --- Say hello  -*- lexical-binding: t; coding: utf-8; -*-

Other variables are allowed (indent-tabs-mode, fill-column, sentence-end-double-space, outline-regexp) and are subject to the safety rules of file-local variables below.

Library header

After the first line comes a block of comment lines that the manual calls the conventional headers. The package tools (package.el, lm-header, the archive builders of GNU ELPA and MELPA) read them. A header line is ;; Key: value; a value may continue on the next lines, which start with ;; and extra indentation.

The header is followed by the copyright notice and licence statement (in the GNU files, a block that starts ;; This file is part of GNU Emacs.), then the sections below. The viewer colours the header names (Author: and the others in the table) as directives while it is reading the opening comments.

Sections and comments

A library is divided by comment lines that start with three semicolons and end with a colon. The package tools find them by name:

• ;;; Commentary: – the description of the library and how to use it, written as ;; lines
• ;;; Change Log: or ;;; History: – an optional change log
• ;;; Code: – where the code begins
• ;;; NAME.el ends here – the last line; its absence means the file may have been cut short

Within the code, headings are comment lines starting with ;;; at the left margin (;;; Utilities, and ;;;; with four for a lower level; Outline mode and Imenu use them), comments about the following code start with ;; and are indented like the code, and a comment at the end of a line starts with a single ;. Emacs also treats a form feed (^L, character 12) at the start of a line as a page break between sections. A comment on its own line that starts in column 0 with a single ; is not re-indented by Emacs.

Strings that hold documentation come directly after the name and argument list of a definition; see Functions and Variables and scope.

Autoload cookies

A comment ;;;###autoload on the line before a definition marks it for the autoloader. When a package is installed, or a loaddefs file is generated (make-directory-autoloads, loaddefs-generate), the marked definition is copied into a NAME-autoloads.el or loaddefs.el file as an autoload form, so that Emacs knows the function without loading the whole library. The generator turns a defun, defmacro, define-minor-mode and a few other definitions into an autoload call and copies any other form that follows the cookie verbatim (Packages and autoloads). A form written on the same line after the cookie, as in ;;;###autoload (autoload 'foo "myfile"), is copied instead of the definition below it. The cookie string can be changed: lisp-mode-autoload-regexp also matches comments such as ;;;###calc-autoload, and generated-autoload-file names a different output file.

File-local variables

Besides the first-line cookie, Emacs reads a local variables list at the end of a file, within the last 3,000 characters. It starts with a line that contains Local Variables: and ends with End:, and every line in between carries the same prefix, here the comment marker ;;:

;; Local Variables:
;; indent-tabs-mode: nil
;; byte-compile-warnings: (not obsolete)
;; End:

Emacs asks the user before applying a variable it does not know to be safe (a value that passes the variable’s safe-local-variable test, or one listed in safe-local-variable-values, is accepted without asking), and always asks for eval: forms and for risky variables such as hooks, functions and commands. Variables whose names end in -hook, -function, -map and several others are risky.

Directory-local variables: .dir-locals.el

A file named .dir-locals.el holds settings for every file in its directory and below. A second file .dir-locals-2.el in the same directory is read as well; it is meant for personal settings when the first is under version control. (The MS-DOS version of Emacs uses _dir-locals.el.) The file is not code to run. It is one list that Emacs reads as data, of the form ((SELECTOR . SETTINGS) …):

• the selector is a major-mode symbol (c-mode, emacs-lisp-mode), nil for every mode, or a subdirectory name written as a string;
• the settings are an alist of (VARIABLE . VALUE) pairs, where the variable may be eval (the value is a form to evaluate), mode (turn on a mode), or subdirs (nil excludes subdirectories).

((nil . ((indent-tabs-mode . nil)
         (fill-column . 80)))
 (c-mode . ((c-file-style . "linux")))
 ("tests" . ((nil . ((eval . (setq-local my-test-mode t)))))))

Emacs uses the file found by going up from the visited file’s directory, and uses the deepest file when there are several. The same safety rules as for a local variables list apply, and enable-remote-dir-locals controls whether remote directories are searched. The functions dir-locals-set-class-variables and dir-locals-set-directory-class define the same thing from Lisp. The viewer shows these files as “Emacs directory-local variables file” and colours them as data: a list that starts a list is not a call.

Files that Emacs loads by name

Scripts, encodings and line endings

An Emacs Lisp file can be a script. A first line #!/usr/bin/env -S emacs --script makes the system start Emacs with --script (or -x, which loads the file as a script); the reader skips a #! line wherever it is met. From Emacs 31 a script loaded with -x or --script uses lexical binding.

The text of a file is decoded with the encoding named by the coding: cookie, or by Emacs’s detection, which prefers UTF-8 in current versions. New files should be UTF-8 with a Unix line ending (a single line feed, \n). Emacs reads files with CRLF or a lone CR as well, by detecting the ending, and the reader treats a carriage return like other white space. Characters outside ASCII are allowed in strings, comments and symbol names, but the manual advises writing them with escapes (\N{…}, é) in strings when the file is not UTF-8. The viewer decodes a file as UTF-8, or as Windows-1252 when it is not valid UTF-8, and says so.

Not described

Known, not yet covered

• Reference: the full list of variables that the file-local variables mechanism treats as safe (safe-local-variable properties) and the rules of hack-local-variables for prefix and suffix lines are summarised, not listed.
• Reference: the exact form of generated autoload files (loaddefs.el, its section markers) is described only in outline; the generator is loaddefs-gen.el in the Emacs source.

See also

• Lexical structure – the tokens inside the forms
• Packages and autoloads – provide, require, package archives
• Conventional Headers for Emacs Libraries – the manual’s list of header lines