1 ;;; autoload.el --- maintain autoloads in loaddefs.el.
3 ;; Copyright (C) 1991, 92, 93, 94, 95, 96, 97 Free Software Foundation, Inc.
5 ;; Author: Roland McGrath <roland@gnu.org>
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
27 ;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
28 ;; date. It interprets magic cookies of the form ";;;###autoload" in
29 ;; lisp source files in various useful ways. To learn more, read the
30 ;; source; if you're going to use this, you'd better be able to.
34 (defvar generated-autoload-file "loaddefs.el"
35 "*File \\[update-file-autoloads] puts autoloads into.
36 A `.el' file can set this in its local variables section to make its
37 autoloads go somewhere else. The autoload file is assumed to contain a
38 trailer starting with a FormFeed character.")
40 (defconst generate-autoload-cookie ";;;###autoload"
41 "Magic comment indicating the following form should be autoloaded.
42 Used by \\[update-file-autoloads]. This string should be
43 meaningless to Lisp (e.g., a comment).
48 \(defun function-to-be-autoloaded () ...)
50 If this string appears alone on a line, the following form will be
51 read and an autoload made for it. If there is further text on the line,
52 that text will be copied verbatim to `generated-autoload-file'.")
54 (defconst generate-autoload-section-header "\f\n;;;### "
55 "String that marks the form at the start of a new file's autoload section.")
57 (defconst generate-autoload-section-trailer "\n;;;***\n"
58 "String which indicates the end of the section of autoloads for a file.")
60 (defconst generate-autoload-section-continuation ";;;;;; "
61 "String to add on each continuation of the section header form.")
63 (defun make-autoload (form file)
64 "Turn FORM into an autoload or defvar for source file FILE.
65 Returns nil if FORM is not a `defun', `define-skeleton',
66 `define-derived-mode', `define-generic-mode', `defmacro', `defcustom',
67 `define-minor-mode' or `easy-mmode-define-minor-mode'."
68 (let ((car (car-safe form)))
69 (if (memq car '(defun define-skeleton defmacro define-derived-mode
70 define-generic-mode easy-mmode-define-minor-mode
71 define-minor-mode defun*))
72 (let ((macrop (eq car 'defmacro))
76 ;; Ignore the arguments.
78 ((memq car '(define-skeleton define-minor-mode
79 easy-mmode-define-minor-mode)) form)
80 ((eq car 'define-derived-mode) (cdr (cdr form)))
81 ((eq car 'define-generic-mode)
82 (cdr (cdr (cdr (cdr (cdr form))))))
86 (setq form (cdr form))
88 ;; `define-generic-mode' quotes the name, so take care of that
89 (list 'autoload (if (listp name) name (list 'quote name)) file doc
90 (or (eq car 'define-skeleton) (eq car 'define-derived-mode)
91 (eq car 'define-generic-mode)
92 (eq car 'easy-mmode-define-minor-mode)
93 (eq car 'define-minor-mode)
94 (eq (car-safe (car form)) 'interactive))
95 (if macrop (list 'quote 'macro) nil)))
96 ;; Convert defcustom to a simpler (and less space-consuming) defvar,
97 ;; but add some extra stuff if it uses :require.
98 (if (eq car 'defcustom)
99 (let ((varname (car-safe (cdr-safe form)))
100 (init (car-safe (cdr-safe (cdr-safe form))))
101 (doc (car-safe (cdr-safe (cdr-safe (cdr-safe form)))))
102 (rest (cdr-safe (cdr-safe (cdr-safe (cdr-safe form))))))
103 (if (not (plist-get rest :require))
104 `(defvar ,varname ,init ,doc)
106 (defvar ,varname ,init ,doc)
107 (custom-add-to-group ,(plist-get rest :group)
108 ',varname 'custom-variable)
109 (custom-add-load ',varname
110 ,(plist-get rest :require)))))
113 ;;; Forms which have doc-strings which should be printed specially.
114 ;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
115 ;;; the doc-string in FORM.
117 ;;; There used to be the following note here:
118 ;;; ;;; Note: defconst and defvar should NOT be marked in this way.
119 ;;; ;;; We don't want to produce defconsts and defvars that
120 ;;; ;;; make-docfile can grok, because then it would grok them twice,
121 ;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
122 ;;; ;;; once in loaddefs.el.
124 ;;; Counter-note: Yes, they should be marked in this way.
125 ;;; make-docfile only processes those files that are loaded into the
126 ;;; dumped Emacs, and those files should never have anything
127 ;;; autoloaded here. The above-feared problem only occurs with files
128 ;;; which have autoloaded entries *and* are processed by make-docfile;
129 ;;; there should be no such files.
131 (put 'autoload 'doc-string-elt 3)
132 (put 'defun 'doc-string-elt 3)
133 (put 'defvar 'doc-string-elt 3)
134 (put 'defcustom 'doc-string-elt 3)
135 (put 'defconst 'doc-string-elt 3)
136 (put 'defmacro 'doc-string-elt 3)
137 (put 'define-skeleton 'doc-string-elt 3)
138 (put 'define-derived-mode 'doc-string-elt 3)
139 (put 'easy-mmode-define-minor-mode 'doc-string-elt 3)
140 (put 'define-minor-mode 'doc-string-elt 3)
141 (put 'define-generic-mode 'doc-string-elt 3)
144 (defun autoload-trim-file-name (file)
145 ;; Returns a relative pathname of FILE
146 ;; starting from the directory that loaddefs.el is in.
147 ;; That is normally a directory in load-path,
148 ;; which means Emacs will be able to find FILE when it looks.
149 ;; Any extra directory names here would prevent finding the file.
150 (setq file (expand-file-name file))
151 (file-relative-name file
152 (file-name-directory generated-autoload-file)))
154 (defun autoload-read-section-header ()
155 "Read a section header form.
156 Since continuation lines have been marked as comments,
157 we must copy the text of the form and remove those comment
158 markers before we call `read'."
160 (let ((beginning (point))
163 (while (looking-at generate-autoload-section-continuation)
165 (setq string (buffer-substring beginning (point)))
166 (with-current-buffer (get-buffer-create " *autoload*")
169 (goto-char (point-min))
170 (while (search-forward generate-autoload-section-continuation nil t)
172 (goto-char (point-min))
173 (read (current-buffer))))))
175 (defun generate-file-autoloads (file)
176 "Insert at point a loaddefs autoload section for FILE.
177 autoloads are generated for defuns and defmacros in FILE
178 marked by `generate-autoload-cookie' (which see).
179 If FILE is being visited in a buffer, the contents of the buffer
181 (interactive "fGenerate autoloads for file: ")
182 (let ((outbuf (current-buffer))
184 (load-name (let ((name (file-name-nondirectory file)))
185 (if (string-match "\\.elc?$" name)
186 (substring name 0 (match-beginning 0))
189 (print-readably t) ; This does something in Lucid Emacs.
190 (float-output-format nil)
192 (visited (get-file-buffer file))
195 ;; If the autoload section we create here uses an absolute
196 ;; pathname for FILE in its header, and then Emacs is installed
197 ;; under a different path on another system,
198 ;; `update-autoloads-here' won't be able to find the files to be
199 ;; autoloaded. So, if FILE is in the same directory or a
200 ;; subdirectory of the current buffer's directory, we'll make it
201 ;; relative to the current buffer's directory.
202 (setq file (expand-file-name file))
203 (let* ((source-truename (file-truename file))
204 (dir-truename (file-name-as-directory
205 (file-truename default-directory)))
206 (len (length dir-truename)))
207 (if (and (< len (length source-truename))
208 (string= dir-truename (substring source-truename 0 len)))
209 (setq file (substring source-truename len))))
211 (message "Generating autoloads for %s..." file)
217 ;; It is faster to avoid visiting the file.
218 (set-buffer (get-buffer-create " *generate-autoload-file*"))
219 (kill-all-local-variables)
221 (setq buffer-undo-list t
222 buffer-read-only nil)
224 (insert-file-contents file nil))
228 (goto-char (point-min))
230 (skip-chars-forward " \t\n\f")
232 ((looking-at (regexp-quote generate-autoload-cookie))
233 (search-forward generate-autoload-cookie)
234 (skip-chars-forward " \t")
237 ;; Read the next form and make an autoload.
238 (let* ((form (prog1 (read (current-buffer))
239 (or (bolp) (forward-line 1))))
240 (autoload-1 (make-autoload form load-name))
241 (autoload (if (eq (car autoload-1) 'progn)
244 (doc-string-elt (get (car-safe form)
247 (setq autoloads-done (cons (nth 1 form)
249 (setq autoload form))
250 (if (and doc-string-elt
251 (stringp (nth doc-string-elt autoload)))
252 ;; We need to hack the printing because the
253 ;; doc-string must be printed specially for
254 ;; make-docfile (sigh).
255 (let* ((p (nthcdr (1- doc-string-elt)
260 (let ((print-escape-newlines t)
261 (print-escape-nonascii t))
262 (mapcar (function (lambda (elt)
266 (princ "\"\\\n" outbuf)
267 (let ((begin (save-excursion
271 (prin1-to-string (car elt)) 1)
273 ;; Insert a backslash before each ( that
274 ;; appears at the beginning of a line in
279 (while (search-backward "\n(" begin t)
286 (prin1-to-string (cdr elt))
290 (let ((print-escape-newlines t)
291 (print-escape-nonascii t))
292 (print autoload outbuf)))
293 (if (eq (car autoload-1) 'progn)
294 ;; Print the rest of the form
295 (let ((print-escape-newlines t)
296 (print-escape-nonascii t))
297 (mapcar (function (lambda (elt)
299 (cddr autoload-1)))))
300 ;; Copy the rest of the line to the output.
301 (princ (buffer-substring
303 ;; Back up over whitespace, to preserve it.
304 (skip-chars-backward " \f\t")
305 (if (= (char-after (1+ (point))) ? )
309 (progn (forward-line 1) (point)))
312 ;; Don't read the comment.
316 (forward-line 1)))))))
318 ;; We created this buffer, so we should kill it.
319 (kill-buffer (current-buffer)))
321 (setq output-end (point-marker))))
324 ;; Insert the section-header line
325 ;; which lists the file name and which functions are in it, etc.
326 (insert generate-autoload-section-header)
327 (prin1 (list 'autoloads autoloads-done load-name
328 (autoload-trim-file-name file)
329 (nth 5 (file-attributes file)))
332 ;; Break that line at spaces, to avoid very long lines.
333 ;; Make each sub-line into a comment.
334 (with-current-buffer outbuf
339 (skip-chars-forward "^ \n")
341 (insert "\n" generate-autoload-section-continuation)))))
342 (insert ";;; Generated autoloads from "
343 (autoload-trim-file-name file) "\n")
344 ;; Warn if we put a line in loaddefs.el
345 ;; that is long enough to cause trouble.
346 (while (< (point) output-end)
349 (if (> (- (point) beg) 900)
351 (message "A line is too long--over 900 characters")
353 (goto-char output-end))))
355 (goto-char output-end)
356 (insert generate-autoload-section-trailer)))
357 (message "Generating autoloads for %s...done" file)))
360 (defun update-file-autoloads (file)
361 "Update the autoloads for FILE in `generated-autoload-file'
362 \(which FILE might bind in its local variables)."
363 (interactive "fUpdate autoloads for file: ")
364 (let ((load-name (let ((name (file-name-nondirectory file)))
365 (if (string-match "\\.elc?$" name)
366 (substring name 0 (match-beginning 0))
369 (existing-buffer (get-file-buffer file)))
371 ;; We want to get a value for generated-autoload-file from
372 ;; the local variables section if it's there.
374 (set-buffer existing-buffer))
375 ;; We must read/write the file without any code conversion.
376 (let ((coding-system-for-read 'no-conversion))
377 (set-buffer (find-file-noselect
378 (expand-file-name generated-autoload-file
379 (expand-file-name "lisp"
380 source-directory)))))
381 (or (> (buffer-size) 0)
382 (error "Autoloads file %s does not exist" buffer-file-name))
383 (or (file-writable-p buffer-file-name)
384 (error "Autoloads file %s is not writable" buffer-file-name))
388 (goto-char (point-min))
389 ;; Look for the section for LOAD-NAME.
390 (while (and (not found)
391 (search-forward generate-autoload-section-header nil t))
392 (let ((form (autoload-read-section-header)))
393 (cond ((string= (nth 2 form) load-name)
394 ;; We found the section for this file.
395 ;; Check if it is up to date.
396 (let ((begin (match-beginning 0))
397 (last-time (nth 4 form))
398 (file-time (nth 5 (file-attributes file))))
399 (if (and (or (null existing-buffer)
400 (not (buffer-modified-p existing-buffer)))
401 (listp last-time) (= (length last-time) 2)
402 (or (> (car last-time) (car file-time))
403 (and (= (car last-time) (car file-time))
404 (>= (nth 1 last-time)
405 (nth 1 file-time)))))
409 Autoload section for %s is up to date."
411 (setq found 'up-to-date))
412 (search-forward generate-autoload-section-trailer)
413 (delete-region begin (point))
415 ((string< load-name (nth 2 form))
416 ;; We've come to a section alphabetically later than
417 ;; LOAD-NAME. We assume the file is in order and so
418 ;; there must be no section for LOAD-NAME. We will
419 ;; insert one before the section here.
420 (goto-char (match-beginning 0))
421 (setq found 'new)))))
425 ;; No later sections in the file. Put before the last page.
426 (goto-char (point-max))
427 (search-backward "\f" nil t)))
428 (or (eq found 'up-to-date)
430 ;; Check that FILE has any cookies before generating a
431 ;; new section for it.
434 (set-buffer existing-buffer)
435 ;; It is faster to avoid visiting the file.
436 (set-buffer (get-buffer-create " *autoload-file*"))
437 (kill-all-local-variables)
439 (setq buffer-undo-list t
440 buffer-read-only nil)
442 (insert-file-contents file nil))
446 (goto-char (point-min))
448 (if (re-search-forward
449 (concat "^" (regexp-quote
450 generate-autoload-cookie))
454 (message "%s has no autoloads" file))
457 (kill-buffer (current-buffer))))))))
458 (generate-file-autoloads file))))
464 (defun update-autoloads-from-directories (&rest dirs)
466 Update loaddefs.el with all the current autoloads from DIRS, and no old ones.
467 This uses `update-file-autoloads' (which see) do its work."
468 (interactive "DUpdate autoloads from directory: ")
469 (let ((files (apply 'nconc
470 (mapcar (function (lambda (dir)
471 (directory-files (expand-file-name dir)
478 (expand-file-name generated-autoload-file
479 (expand-file-name "lisp"
481 (setq top-dir (file-name-directory autoloads-file))
483 (set-buffer (find-file-noselect autoloads-file))
485 (goto-char (point-min))
486 (while (search-forward generate-autoload-section-header nil t)
487 (let* ((form (autoload-read-section-header))
489 (cond ((not (stringp file)))
490 ((not (file-exists-p (expand-file-name file top-dir)))
491 ;; Remove the obsolete section.
492 (let ((begin (match-beginning 0)))
493 (search-forward generate-autoload-section-trailer)
494 (delete-region begin (point))))
496 (update-file-autoloads file)))
497 (setq files (delete file files)))))
498 ;; Elements remaining in FILES have no existing autoload sections.
499 (mapcar 'update-file-autoloads files)
503 (defun batch-update-autoloads ()
504 "Update loaddefs.el autoloads in batch mode.
505 Calls `update-autoloads-from-directories' on the command line arguments."
506 (apply 'update-autoloads-from-directories command-line-args-left)
507 (setq command-line-args-left nil))
511 ;;; autoload.el ends here