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 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 (let ((macrop (eq car
'defmacro
))
75 ;; Ignore the arguments.
77 ((memq car
'(define-skeleton
78 easy-mmode-define-minor-mode
)) form
)
79 ((eq car
'define-derived-mode
) (cdr (cdr form
)))
80 ((eq car
'define-generic-mode
)
81 (cdr (cdr (cdr (cdr (cdr form
))))))
85 (setq form
(cdr form
))
87 ;; `define-generic-mode' quotes the name, so take care of that
88 (list 'autoload
(if (listp name
) name
(list 'quote name
)) file doc
89 (or (eq car
'define-skeleton
) (eq car
'define-derived-mode
)
90 (eq car
'define-generic-mode
)
91 (eq car
'easy-mmode-define-minor-mode
)
92 (eq (car-safe (car form
)) 'interactive
))
93 (if macrop
(list 'quote
'macro
) nil
)))
94 ;; Convert defcustom to a simpler (and less space-consuming) defvar,
95 ;; but add some extra stuff if it uses :require.
96 (if (eq car
'defcustom
)
97 (let ((varname (car-safe (cdr-safe form
)))
98 (init (car-safe (cdr-safe (cdr-safe form
))))
99 (doc (car-safe (cdr-safe (cdr-safe (cdr-safe form
)))))
100 (rest (cdr-safe (cdr-safe (cdr-safe (cdr-safe form
))))))
101 (if (not (plist-get rest
:require
))
102 `(defvar ,varname
,init
,doc
)
104 (defvar ,varname
,init
,doc
)
105 (custom-add-to-group ,(plist-get rest
:group
)
106 ',varname
'custom-variable
)
107 (custom-add-load ',varname
108 ,(plist-get rest
:require
)))))
111 ;;; Forms which have doc-strings which should be printed specially.
112 ;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
113 ;;; the doc-string in FORM.
115 ;;; There used to be the following note here:
116 ;;; ;;; Note: defconst and defvar should NOT be marked in this way.
117 ;;; ;;; We don't want to produce defconsts and defvars that
118 ;;; ;;; make-docfile can grok, because then it would grok them twice,
119 ;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
120 ;;; ;;; once in loaddefs.el.
122 ;;; Counter-note: Yes, they should be marked in this way.
123 ;;; make-docfile only processes those files that are loaded into the
124 ;;; dumped Emacs, and those files should never have anything
125 ;;; autoloaded here. The above-feared problem only occurs with files
126 ;;; which have autoloaded entries *and* are processed by make-docfile;
127 ;;; there should be no such files.
129 (put 'autoload
'doc-string-elt
3)
130 (put 'defun
'doc-string-elt
3)
131 (put 'defvar
'doc-string-elt
3)
132 (put 'defcustom
'doc-string-elt
3)
133 (put 'defconst
'doc-string-elt
3)
134 (put 'defmacro
'doc-string-elt
3)
135 (put 'define-skeleton
'doc-string-elt
3)
136 (put 'define-derived-mode
'doc-string-elt
3)
137 (put 'easy-mmode-define-minor-mode
'doc-string-elt
3)
138 (put 'define-generic-mode
'doc-string-elt
3)
141 (defun autoload-trim-file-name (file)
142 ;; Returns a relative pathname of FILE
143 ;; starting from the directory that loaddefs.el is in.
144 ;; That is normally a directory in load-path,
145 ;; which means Emacs will be able to find FILE when it looks.
146 ;; Any extra directory names here would prevent finding the file.
147 (setq file
(expand-file-name file
))
148 (file-relative-name file
149 (file-name-directory generated-autoload-file
)))
151 (defun autoload-read-section-header ()
152 "Read a section header form.
153 Since continuation lines have been marked as comments,
154 we must copy the text of the form and remove those comment
155 markers before we call `read'."
157 (let ((beginning (point))
160 (while (looking-at generate-autoload-section-continuation
)
162 (setq string
(buffer-substring beginning
(point)))
163 (with-current-buffer (get-buffer-create " *autoload*")
166 (goto-char (point-min))
167 (while (search-forward generate-autoload-section-continuation nil t
)
169 (goto-char (point-min))
170 (read (current-buffer))))))
172 (defun generate-file-autoloads (file)
173 "Insert at point a loaddefs autoload section for FILE.
174 autoloads are generated for defuns and defmacros in FILE
175 marked by `generate-autoload-cookie' (which see).
176 If FILE is being visited in a buffer, the contents of the buffer
178 (interactive "fGenerate autoloads for file: ")
179 (let ((outbuf (current-buffer))
181 (load-name (let ((name (file-name-nondirectory file
)))
182 (if (string-match "\\.elc?$" name
)
183 (substring name
0 (match-beginning 0))
186 (print-readably t
) ; This does something in Lucid Emacs.
187 (float-output-format nil
)
189 (visited (get-file-buffer file
))
192 ;; If the autoload section we create here uses an absolute
193 ;; pathname for FILE in its header, and then Emacs is installed
194 ;; under a different path on another system,
195 ;; `update-autoloads-here' won't be able to find the files to be
196 ;; autoloaded. So, if FILE is in the same directory or a
197 ;; subdirectory of the current buffer's directory, we'll make it
198 ;; relative to the current buffer's directory.
199 (setq file
(expand-file-name file
))
200 (let* ((source-truename (file-truename file
))
201 (dir-truename (file-name-as-directory
202 (file-truename default-directory
)))
203 (len (length dir-truename
)))
204 (if (and (< len
(length source-truename
))
205 (string= dir-truename
(substring source-truename
0 len
)))
206 (setq file
(substring source-truename len
))))
208 (message "Generating autoloads for %s..." file
)
214 ;; It is faster to avoid visiting the file.
215 (set-buffer (get-buffer-create " *generate-autoload-file*"))
216 (kill-all-local-variables)
218 (setq buffer-undo-list t
219 buffer-read-only nil
)
221 (insert-file-contents file nil
))
225 (goto-char (point-min))
227 (skip-chars-forward " \t\n\f")
229 ((looking-at (regexp-quote generate-autoload-cookie
))
230 (search-forward generate-autoload-cookie
)
231 (skip-chars-forward " \t")
234 ;; Read the next form and make an autoload.
235 (let* ((form (prog1 (read (current-buffer))
236 (or (bolp) (forward-line 1))))
237 (autoload-1 (make-autoload form load-name
))
238 (autoload (if (eq (car autoload-1
) 'progn
)
241 (doc-string-elt (get (car-safe form
)
244 (setq autoloads-done
(cons (nth 1 form
)
246 (setq autoload form
))
247 (if (and doc-string-elt
248 (stringp (nth doc-string-elt autoload
)))
249 ;; We need to hack the printing because the
250 ;; doc-string must be printed specially for
251 ;; make-docfile (sigh).
252 (let* ((p (nthcdr (1- doc-string-elt
)
257 (let ((print-escape-newlines t
)
258 (print-escape-nonascii t
))
259 (mapcar (function (lambda (elt)
263 (princ "\"\\\n" outbuf
)
264 (let ((begin (save-excursion
268 (prin1-to-string (car elt
)) 1)
270 ;; Insert a backslash before each ( that
271 ;; appears at the beginning of a line in
276 (while (search-backward "\n(" begin t
)
283 (prin1-to-string (cdr elt
))
287 (let ((print-escape-newlines t
)
288 (print-escape-nonascii t
))
289 (print autoload outbuf
)))
290 (if (eq (car autoload-1
) 'progn
)
291 ;; Print the rest of the form
292 (let ((print-escape-newlines t
)
293 (print-escape-nonascii t
))
294 (mapcar (function (lambda (elt)
296 (cddr autoload-1
)))))
297 ;; Copy the rest of the line to the output.
298 (princ (buffer-substring
300 ;; Back up over whitespace, to preserve it.
301 (skip-chars-backward " \f\t")
302 (if (= (char-after (1+ (point))) ?
)
306 (progn (forward-line 1) (point)))
309 ;; Don't read the comment.
313 (forward-line 1)))))))
315 ;; We created this buffer, so we should kill it.
316 (kill-buffer (current-buffer)))
318 (setq output-end
(point-marker))))
321 ;; Insert the section-header line
322 ;; which lists the file name and which functions are in it, etc.
323 (insert generate-autoload-section-header
)
324 (prin1 (list 'autoloads autoloads-done load-name
325 (autoload-trim-file-name file
)
326 (nth 5 (file-attributes file
)))
329 ;; Break that line at spaces, to avoid very long lines.
330 ;; Make each sub-line into a comment.
331 (with-current-buffer outbuf
336 (skip-chars-forward "^ \n")
338 (insert "\n" generate-autoload-section-continuation
)))))
339 (insert ";;; Generated autoloads from "
340 (autoload-trim-file-name file
) "\n")
341 ;; Warn if we put a line in loaddefs.el
342 ;; that is long enough to cause trouble.
343 (while (< (point) output-end
)
346 (if (> (- (point) beg
) 900)
348 (message "A line is too long--over 900 characters")
350 (goto-char output-end
))))
352 (goto-char output-end
)
353 (insert generate-autoload-section-trailer
)))
354 (message "Generating autoloads for %s...done" file
)))
357 (defun update-file-autoloads (file)
358 "Update the autoloads for FILE in `generated-autoload-file'
359 \(which FILE might bind in its local variables)."
360 (interactive "fUpdate autoloads for file: ")
361 (let ((load-name (let ((name (file-name-nondirectory file
)))
362 (if (string-match "\\.elc?$" name
)
363 (substring name
0 (match-beginning 0))
366 (existing-buffer (get-file-buffer file
)))
368 ;; We want to get a value for generated-autoload-file from
369 ;; the local variables section if it's there.
371 (set-buffer existing-buffer
))
372 ;; We must read/write the file without any code conversion.
373 (let ((coding-system-for-read 'no-conversion
))
374 (set-buffer (find-file-noselect
375 (expand-file-name generated-autoload-file
376 (expand-file-name "lisp"
377 source-directory
)))))
378 (or (> (buffer-size) 0)
379 (error "Autoloads file %s does not exist" buffer-file-name
))
380 (or (file-writable-p buffer-file-name
)
381 (error "Autoloads file %s is not writable" buffer-file-name
))
385 (goto-char (point-min))
386 ;; Look for the section for LOAD-NAME.
387 (while (and (not found
)
388 (search-forward generate-autoload-section-header nil t
))
389 (let ((form (autoload-read-section-header)))
390 (cond ((string= (nth 2 form
) load-name
)
391 ;; We found the section for this file.
392 ;; Check if it is up to date.
393 (let ((begin (match-beginning 0))
394 (last-time (nth 4 form
))
395 (file-time (nth 5 (file-attributes file
))))
396 (if (and (or (null existing-buffer
)
397 (not (buffer-modified-p existing-buffer
)))
398 (listp last-time
) (= (length last-time
) 2)
399 (or (> (car last-time
) (car file-time
))
400 (and (= (car last-time
) (car file-time
))
401 (>= (nth 1 last-time
)
402 (nth 1 file-time
)))))
406 Autoload section for %s is up to date."
408 (setq found
'up-to-date
))
409 (search-forward generate-autoload-section-trailer
)
410 (delete-region begin
(point))
412 ((string< load-name
(nth 2 form
))
413 ;; We've come to a section alphabetically later than
414 ;; LOAD-NAME. We assume the file is in order and so
415 ;; there must be no section for LOAD-NAME. We will
416 ;; insert one before the section here.
417 (goto-char (match-beginning 0))
418 (setq found
'new
)))))
422 ;; No later sections in the file. Put before the last page.
423 (goto-char (point-max))
424 (search-backward "\f" nil t
)))
425 (or (eq found
'up-to-date
)
427 ;; Check that FILE has any cookies before generating a
428 ;; new section for it.
431 (set-buffer existing-buffer
)
432 ;; It is faster to avoid visiting the file.
433 (set-buffer (get-buffer-create " *autoload-file*"))
434 (kill-all-local-variables)
436 (setq buffer-undo-list t
437 buffer-read-only nil
)
439 (insert-file-contents file nil
))
443 (goto-char (point-min))
445 (if (re-search-forward
446 (concat "^" (regexp-quote
447 generate-autoload-cookie
))
451 (message "%s has no autoloads" file
))
454 (kill-buffer (current-buffer))))))))
455 (generate-file-autoloads file
))))
461 (defun update-autoloads-from-directories (&rest dirs
)
463 Update loaddefs.el with all the current autoloads from DIRS, and no old ones.
464 This uses `update-file-autoloads' (which see) do its work."
465 (interactive "DUpdate autoloads from directory: ")
466 (let ((files (apply 'nconc
467 (mapcar (function (lambda (dir)
468 (directory-files (expand-file-name dir
)
475 (expand-file-name generated-autoload-file
476 (expand-file-name "lisp"
478 (setq top-dir
(file-name-directory autoloads-file
))
480 (set-buffer (find-file-noselect autoloads-file
))
482 (goto-char (point-min))
483 (while (search-forward generate-autoload-section-header nil t
)
484 (let* ((form (autoload-read-section-header))
486 (cond ((not (stringp file
)))
487 ((not (file-exists-p (expand-file-name file top-dir
)))
488 ;; Remove the obsolete section.
489 (let ((begin (match-beginning 0)))
490 (search-forward generate-autoload-section-trailer
)
491 (delete-region begin
(point))))
493 (update-file-autoloads file
)))
494 (setq files
(delete file files
)))))
495 ;; Elements remaining in FILES have no existing autoload sections.
496 (mapcar 'update-file-autoloads files
)
500 (defun batch-update-autoloads ()
501 "Update loaddefs.el autoloads in batch mode.
502 Calls `update-autoloads-from-directories' on the command line arguments."
503 (apply 'update-autoloads-from-directories command-line-args-left
)
504 (setq command-line-args-left nil
))
508 ;;; autoload.el ends here