1 ;;; autoload.el --- maintain autoloads in loaddefs.el
3 ;; Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 2001
4 ;; Free Software Foundation, Inc.
6 ;; Author: Roland McGrath <roland@gnu.org>
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
24 ;; Boston, MA 02111-1307, USA.
28 ;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
29 ;; date. It interprets magic cookies of the form ";;;###autoload" in
30 ;; lisp source files in various useful ways. To learn more, read the
31 ;; source; if you're going to use this, you'd better be able to.
35 (defvar generated-autoload-file
"loaddefs.el"
36 "*File \\[update-file-autoloads] puts autoloads into.
37 A `.el' file can set this in its local variables section to make its
38 autoloads go somewhere else. The autoload file is assumed to contain a
39 trailer starting with a FormFeed character.")
41 (defconst generate-autoload-cookie
";;;###autoload"
42 "Magic comment indicating the following form should be autoloaded.
43 Used by \\[update-file-autoloads]. This string should be
44 meaningless to Lisp (e.g., a comment).
49 \(defun function-to-be-autoloaded () ...)
51 If this string appears alone on a line, the following form will be
52 read and an autoload made for it. If there is further text on the line,
53 that text will be copied verbatim to `generated-autoload-file'.")
55 (defconst generate-autoload-section-header
"\f\n;;;### "
56 "String that marks the form at the start of a new file's autoload section.")
58 (defconst generate-autoload-section-trailer
"\n;;;***\n"
59 "String which indicates the end of the section of autoloads for a file.")
61 (defconst generate-autoload-section-continuation
";;;;;; "
62 "String to add on each continuation of the section header form.")
64 (defun make-autoload (form file
)
65 "Turn FORM into an autoload or defvar for source file FILE.
66 Returns nil if FORM is not a special autoload form (i.e. a function definition
67 or macro definition or a defcustom)."
68 (let ((car (car-safe form
)) expand
)
70 ;; For complex cases, try again on the macro-expansion.
71 ((and (memq car
'(easy-mmode-define-global-mode
72 easy-mmode-define-minor-mode define-minor-mode
))
73 (setq expand
(let ((load-file-name file
)) (macroexpand form
)))
74 (eq (car expand
) 'progn
)
75 (memq :autoload-end expand
))
76 (let ((end (memq :autoload-end expand
)))
77 ;; Cut-off anything after the :autoload-end marker.
80 (mapcar (lambda (form) (make-autoload form file
))
83 ;; For special function-like operators, use the `autoload' function.
84 ((memq car
'(defun define-skeleton defmacro define-derived-mode
85 define-generic-mode easy-mmode-define-minor-mode
86 easy-mmode-define-global-mode
87 define-minor-mode defun
*))
88 (let* ((macrop (eq car
'defmacro
))
90 (body (nthcdr (get car
'doc-string-elt
) form
))
91 (doc (if (stringp (car body
)) (pop body
))))
92 ;; `define-generic-mode' quotes the name, so take care of that
93 (list 'autoload
(if (listp name
) name
(list 'quote name
)) file doc
94 (or (and (memq car
'(define-skeleton define-derived-mode
96 easy-mmode-define-global-mode
97 easy-mmode-define-minor-mode
98 define-minor-mode
)) t
)
99 (eq (car-safe (car body
)) 'interactive
))
100 (if macrop
(list 'quote
'macro
) nil
))))
102 ;; Convert defcustom to a simpler (and less space-consuming) defvar,
103 ;; but add some extra stuff if it uses :require.
105 (let ((varname (car-safe (cdr-safe form
)))
106 (init (car-safe (cdr-safe (cdr-safe form
))))
107 (doc (car-safe (cdr-safe (cdr-safe (cdr-safe form
)))))
108 (rest (cdr-safe (cdr-safe (cdr-safe (cdr-safe form
))))))
109 (if (not (plist-get rest
:require
))
110 `(defvar ,varname
,init
,doc
)
112 (defvar ,varname
,init
,doc
)
113 (custom-add-to-group ,(plist-get rest
:group
)
114 ',varname
'custom-variable
)
115 (custom-add-load ',varname
116 ,(plist-get rest
:require
))))))
118 ;; nil here indicates that this is not a special autoload form.
121 ;;; Forms which have doc-strings which should be printed specially.
122 ;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
123 ;;; the doc-string in FORM.
125 ;;; There used to be the following note here:
126 ;;; ;;; Note: defconst and defvar should NOT be marked in this way.
127 ;;; ;;; We don't want to produce defconsts and defvars that
128 ;;; ;;; make-docfile can grok, because then it would grok them twice,
129 ;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
130 ;;; ;;; once in loaddefs.el.
132 ;;; Counter-note: Yes, they should be marked in this way.
133 ;;; make-docfile only processes those files that are loaded into the
134 ;;; dumped Emacs, and those files should never have anything
135 ;;; autoloaded here. The above-feared problem only occurs with files
136 ;;; which have autoloaded entries *and* are processed by make-docfile;
137 ;;; there should be no such files.
139 (put 'autoload
'doc-string-elt
3)
140 (put 'defun
'doc-string-elt
3)
141 (put 'defun
* 'doc-string-elt
3)
142 (put 'defvar
'doc-string-elt
3)
143 (put 'defcustom
'doc-string-elt
3)
144 (put 'defconst
'doc-string-elt
3)
145 (put 'defmacro
'doc-string-elt
3)
146 (put 'defsubst
'doc-string-elt
3)
147 (put 'define-skeleton
'doc-string-elt
2)
148 (put 'define-derived-mode
'doc-string-elt
4)
149 (put 'easy-mmode-define-minor-mode
'doc-string-elt
2)
150 (put 'define-minor-mode
'doc-string-elt
2)
151 (put 'define-generic-mode
'doc-string-elt
7)
152 ;; defin-global-mode has no explicit docstring.
153 (put 'easy-mmode-define-global-mode
'doc-string-elt
1000)
156 (defun autoload-trim-file-name (file)
157 ;; Returns a relative pathname of FILE
158 ;; starting from the directory that loaddefs.el is in.
159 ;; That is normally a directory in load-path,
160 ;; which means Emacs will be able to find FILE when it looks.
161 ;; Any extra directory names here would prevent finding the file.
162 (setq file
(expand-file-name file
))
163 (file-relative-name file
164 (file-name-directory generated-autoload-file
)))
166 (defun autoload-read-section-header ()
167 "Read a section header form.
168 Since continuation lines have been marked as comments,
169 we must copy the text of the form and remove those comment
170 markers before we call `read'."
172 (let ((beginning (point))
175 (while (looking-at generate-autoload-section-continuation
)
177 (setq string
(buffer-substring beginning
(point)))
178 (with-current-buffer (get-buffer-create " *autoload*")
181 (goto-char (point-min))
182 (while (search-forward generate-autoload-section-continuation nil t
)
184 (goto-char (point-min))
185 (read (current-buffer))))))
187 ;; !! Requires OUTBUF to be bound !!
188 (defun autoload-print-form (form)
189 "Print FORM such that make-docfile will find the docstrings."
191 ;; If the form is a sequence, recurse.
192 ((eq (car form
) 'progn
) (mapcar 'autoload-print-form
(cdr form
)))
193 ;; Symbols at the toplevel are meaningless.
196 (let ((doc-string-elt (get (car-safe form
) 'doc-string-elt
)))
197 (if (and doc-string-elt
(stringp (nth doc-string-elt form
)))
198 ;; We need to hack the printing because the
199 ;; doc-string must be printed specially for
200 ;; make-docfile (sigh).
201 (let* ((p (nthcdr (1- doc-string-elt
) form
))
205 (let ((print-escape-newlines t
)
206 (print-escape-nonascii t
))
207 (mapcar (lambda (elt)
211 (princ "\"\\\n" outbuf
)
212 (let ((begin (with-current-buffer outbuf
(point))))
213 (princ (substring (prin1-to-string (car elt
)) 1)
215 ;; Insert a backslash before each ( that
216 ;; appears at the beginning of a line in
218 (with-current-buffer outbuf
220 (while (search-backward "\n(" begin t
)
226 (princ (substring (prin1-to-string (cdr elt
)) 1)
229 (let ((print-escape-newlines t
)
230 (print-escape-nonascii t
))
231 (print form outbuf
)))))))
233 (defun autoload-ensure-default-file (file)
234 "Make sure that the autoload file FILE exists and if not create it."
235 (unless (file-exists-p file
)
237 (concat ";;; " (file-name-nondirectory file
)
238 " --- automatically extracted autoloads\n"
241 "\f\n;; Local Variables:\n"
242 ";; version-control: never\n"
243 ";; no-byte-compile: t\n"
244 ";; no-update-autoloads: t\n"
246 ";;; " (file-name-nondirectory file
)
251 (defun autoload-insert-section-header (outbuf autoloads load-name file time
)
252 "Insert the section-header line,
253 which lists the file name and which functions are in it, etc."
254 (insert generate-autoload-section-header
)
255 (prin1 (list 'autoloads autoloads load-name
256 (if (stringp file
) (autoload-trim-file-name file
) file
)
260 ;; Break that line at spaces, to avoid very long lines.
261 ;; Make each sub-line into a comment.
262 (with-current-buffer outbuf
267 (skip-chars-forward "^ \n")
269 (insert "\n" generate-autoload-section-continuation
))))))
271 (defun generate-file-autoloads (file)
272 "Insert at point a loaddefs autoload section for FILE.
273 autoloads are generated for defuns and defmacros in FILE
274 marked by `generate-autoload-cookie' (which see).
275 If FILE is being visited in a buffer, the contents of the buffer
277 (interactive "fGenerate autoloads for file: ")
278 (let ((outbuf (current-buffer))
280 (load-name (let ((name (file-name-nondirectory file
)))
281 (if (string-match "\\.elc?$" name
)
282 (substring name
0 (match-beginning 0))
285 (print-readably t
) ; This does something in Lucid Emacs.
286 (float-output-format nil
)
288 (visited (get-file-buffer file
))
291 ;; If the autoload section we create here uses an absolute
292 ;; pathname for FILE in its header, and then Emacs is installed
293 ;; under a different path on another system,
294 ;; `update-autoloads-here' won't be able to find the files to be
295 ;; autoloaded. So, if FILE is in the same directory or a
296 ;; subdirectory of the current buffer's directory, we'll make it
297 ;; relative to the current buffer's directory.
298 (setq file
(expand-file-name file
))
299 (let* ((source-truename (file-truename file
))
300 (dir-truename (file-name-as-directory
301 (file-truename default-directory
)))
302 (len (length dir-truename
)))
303 (if (and (< len
(length source-truename
))
304 (string= dir-truename
(substring source-truename
0 len
)))
305 (setq file
(substring source-truename len
))))
307 (message "Generating autoloads for %s..." file
)
313 ;; It is faster to avoid visiting the file.
314 (set-buffer (get-buffer-create " *generate-autoload-file*"))
315 (kill-all-local-variables)
317 (setq buffer-undo-list t
318 buffer-read-only nil
)
320 (insert-file-contents file nil
))
324 (goto-char (point-min))
326 (skip-chars-forward " \t\n\f")
328 ((looking-at (regexp-quote generate-autoload-cookie
))
329 (search-forward generate-autoload-cookie
)
330 (skip-chars-forward " \t")
333 ;; Read the next form and make an autoload.
334 (let* ((form (prog1 (read (current-buffer))
335 (or (bolp) (forward-line 1))))
336 (autoload (make-autoload form load-name
)))
338 (setq autoloads-done
(cons (nth 1 form
)
340 (setq autoload form
))
341 (autoload-print-form autoload
))
343 ;; Copy the rest of the line to the output.
344 (princ (buffer-substring
346 ;; Back up over whitespace, to preserve it.
347 (skip-chars-backward " \f\t")
348 (if (= (char-after (1+ (point))) ?
)
352 (progn (forward-line 1) (point)))
355 ;; Don't read the comment.
359 (forward-line 1)))))))
361 ;; We created this buffer, so we should kill it.
362 (kill-buffer (current-buffer)))
364 (setq output-end
(point-marker))))
367 ;; Insert the section-header line
368 ;; which lists the file name and which functions are in it, etc.
369 (autoload-insert-section-header outbuf autoloads-done load-name file
370 (nth 5 (file-attributes file
)))
371 (insert ";;; Generated autoloads from "
372 (autoload-trim-file-name file
) "\n")
373 (goto-char output-end
)
374 (insert generate-autoload-section-trailer
)))
375 (message "Generating autoloads for %s...done" file
)))
378 (defun update-file-autoloads (file)
379 "Update the autoloads for FILE in `generated-autoload-file'
380 \(which FILE might bind in its local variables).
381 Return FILE if there was no autoload cookie in it."
382 (interactive "fUpdate autoloads for file: ")
383 (let ((load-name (let ((name (file-name-nondirectory file
)))
384 (if (string-match "\\.elc?$" name
)
385 (substring name
0 (match-beginning 0))
388 (existing-buffer (get-file-buffer file
))
391 ;; We want to get a value for generated-autoload-file from
392 ;; the local variables section if it's there.
394 (set-buffer existing-buffer
))
395 ;; We must read/write the file without any code conversion,
396 ;; but still decode EOLs.
397 (let ((coding-system-for-read 'raw-text
))
398 (set-buffer (find-file-noselect
399 (autoload-ensure-default-file
400 (expand-file-name generated-autoload-file
401 (expand-file-name "lisp"
402 source-directory
)))))
403 ;; This is to make generated-autoload-file have Unix EOLs, so
404 ;; that it is portable to all platforms.
405 (setq buffer-file-coding-system
'raw-text-unix
))
406 (or (> (buffer-size) 0)
407 (error "Autoloads file %s does not exist" buffer-file-name
))
408 (or (file-writable-p buffer-file-name
)
409 (error "Autoloads file %s is not writable" buffer-file-name
))
413 (goto-char (point-min))
414 ;; Look for the section for LOAD-NAME.
415 (while (and (not found
)
416 (search-forward generate-autoload-section-header nil t
))
417 (let ((form (autoload-read-section-header)))
418 (cond ((string= (nth 2 form
) load-name
)
419 ;; We found the section for this file.
420 ;; Check if it is up to date.
421 (let ((begin (match-beginning 0))
422 (last-time (nth 4 form
))
423 (file-time (nth 5 (file-attributes file
))))
424 (if (and (or (null existing-buffer
)
425 (not (buffer-modified-p existing-buffer
)))
426 (listp last-time
) (= (length last-time
) 2)
427 (not (autoload-before-p last-time file-time
)))
431 Autoload section for %s is up to date."
433 (setq found
'up-to-date
))
434 (search-forward generate-autoload-section-trailer
)
435 (delete-region begin
(point))
437 ((string< load-name
(nth 2 form
))
438 ;; We've come to a section alphabetically later than
439 ;; LOAD-NAME. We assume the file is in order and so
440 ;; there must be no section for LOAD-NAME. We will
441 ;; insert one before the section here.
442 (goto-char (match-beginning 0))
443 (setq found
'new
)))))
447 ;; No later sections in the file. Put before the last page.
448 (goto-char (point-max))
449 (search-backward "\f" nil t
)))
450 (or (eq found
'up-to-date
)
452 ;; Check that FILE has any cookies before generating a
453 ;; new section for it.
456 (set-buffer existing-buffer
)
457 ;; It is faster to avoid visiting the file.
458 (set-buffer (get-buffer-create " *autoload-file*"))
459 (kill-all-local-variables)
461 (setq buffer-undo-list t
462 buffer-read-only nil
)
464 (insert-file-contents file nil
))
468 (goto-char (point-min))
470 (if (re-search-forward
471 (concat "^" (regexp-quote
472 generate-autoload-cookie
))
476 (message "%s has no autoloads" file
))
477 (setq no-autoloads t
)
480 (kill-buffer (current-buffer))))))))
481 (generate-file-autoloads file
))))
486 (if no-autoloads file
))))
488 (defun autoload-before-p (time1 time2
)
489 (or (< (car time1
) (car time2
))
490 (and (= (car time1
) (car time2
))
491 (< (nth 1 time1
) (nth 1 time2
)))))
493 (defun autoload-remove-section (begin)
495 (search-forward generate-autoload-section-trailer
)
496 (delete-region begin
(point)))
499 (defun update-autoloads-from-directories (&rest dirs
)
501 Update loaddefs.el with all the current autoloads from DIRS, and no old ones.
502 This uses `update-file-autoloads' (which see) do its work."
503 (interactive "DUpdate autoloads from directory: ")
504 (let* ((files (apply 'nconc
505 (mapcar (lambda (dir)
506 (directory-files (expand-file-name dir
)
507 ;; FIXME: add .gz etc...
508 t
"^[^=.].*\\.el\\'"))
510 (this-time (current-time))
511 (no-autoloads nil
) ;files with no autoload cookies.
513 (expand-file-name generated-autoload-file
514 (expand-file-name "lisp" source-directory
)))
515 (top-dir (file-name-directory autoloads-file
)))
518 (find-file-noselect (autoload-ensure-default-file autoloads-file
))
521 ;; Canonicalize file names and remove the autoload file itself.
522 (setq files
(delete (autoload-trim-file-name buffer-file-name
)
523 (mapcar 'autoload-trim-file-name files
)))
525 (goto-char (point-min))
526 (while (search-forward generate-autoload-section-header nil t
)
527 (let* ((form (autoload-read-section-header))
529 (cond ((and (consp file
) (stringp (car file
)))
530 ;; This is a list of files that have no autoload cookies.
531 ;; There shouldn't be more than one such entry.
532 ;; Remove the obsolete section.
533 (autoload-remove-section (match-beginning 0))
534 (let ((last-time (nth 4 form
)))
536 (let ((file-time (nth 5 (file-attributes file
))))
538 (not (autoload-before-p last-time
541 (push file no-autoloads
)
542 (setq files
(delete file files
)))))))
543 ((not (stringp file
)))
544 ((not (file-exists-p (expand-file-name file top-dir
)))
545 ;; Remove the obsolete section.
546 (autoload-remove-section (match-beginning 0)))
547 ((equal (nth 4 form
) (nth 5 (file-attributes file
)))
548 ;; File hasn't changed.
551 (update-file-autoloads file
)))
552 (setq files
(delete file files
)))))
553 ;; Elements remaining in FILES have no existing autoload sections yet.
556 (delq nil
(mapcar 'update-file-autoloads files
))))
558 ;; Add the `no-autoloads' section.
559 (goto-char (point-max))
560 (search-backward "\f" nil t
)
561 (autoload-insert-section-header
562 (current-buffer) nil nil no-autoloads this-time
)
563 (insert generate-autoload-section-trailer
))
568 (defun batch-update-autoloads ()
569 "Update loaddefs.el autoloads in batch mode.
570 Calls `update-autoloads-from-directories' on the command line arguments."
571 (apply 'update-autoloads-from-directories command-line-args-left
)
572 (setq command-line-args-left nil
))
576 ;;; autoload.el ends here