]> code.delx.au - gnu-emacs/blob - lisp/emacs-lisp/autoload.el
; Merge from origin/emacs-25
[gnu-emacs] / lisp / emacs-lisp / autoload.el
1 ;; autoload.el --- maintain autoloads in loaddefs.el -*- lexical-binding: t -*-
2
3 ;; Copyright (C) 1991-1997, 2001-2016 Free Software Foundation, Inc.
4
5 ;; Author: Roland McGrath <roland@gnu.org>
6 ;; Keywords: maint
7 ;; Package: emacs
8
9 ;; This file is part of GNU Emacs.
10
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 3 of the License, or
14 ;; (at your option) any later version.
15
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.
20
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23
24 ;;; Commentary:
25
26 ;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
27 ;; date. It interprets magic cookies of the form ";;;###autoload" in
28 ;; lisp source files in various useful ways. To learn more, read the
29 ;; source; if you're going to use this, you'd better be able to.
30
31 ;;; Code:
32
33 (require 'lisp-mode) ;for `doc-string-elt' properties.
34 (require 'lisp-mnt)
35 (eval-when-compile (require 'cl-lib))
36
37 (defvar generated-autoload-file nil
38 "File into which to write autoload definitions.
39 A Lisp file can set this in its local variables section to make
40 its autoloads go somewhere else.
41
42 If this is a relative file name, the directory is determined as
43 follows:
44 - If a Lisp file defined `generated-autoload-file' as a
45 file-local variable, use its containing directory.
46 - Otherwise use the \"lisp\" subdirectory of `source-directory'.
47
48 The autoload file is assumed to contain a trailer starting with a
49 FormFeed character.")
50 ;;;###autoload
51 (put 'generated-autoload-file 'safe-local-variable 'stringp)
52
53 (defvar generated-autoload-load-name nil
54 "Load name for `autoload' statements generated from autoload cookies.
55 If nil, this defaults to the file name, sans extension.
56 Typically, you need to set this when the directory containing the file
57 is not in `load-path'.
58 This also affects the generated cus-load.el file.")
59 ;;;###autoload
60 (put 'generated-autoload-load-name 'safe-local-variable 'stringp)
61
62 ;; This feels like it should be a defconst, but MH-E sets it to
63 ;; ";;;###mh-autoload" for the autoloads that are to go into mh-loaddefs.el.
64 (defvar generate-autoload-cookie ";;;###autoload"
65 "Magic comment indicating the following form should be autoloaded.
66 Used by \\[update-file-autoloads]. This string should be
67 meaningless to Lisp (e.g., a comment).
68
69 This string is used:
70
71 \;;;###autoload
72 \(defun function-to-be-autoloaded () ...)
73
74 If this string appears alone on a line, the following form will be
75 read and an autoload made for it. If there is further text on the line,
76 that text will be copied verbatim to `generated-autoload-file'.")
77
78 (defvar autoload-excludes nil
79 "If non-nil, list of absolute file names not to scan for autoloads.")
80
81 (defconst generate-autoload-section-header "\f\n;;;### "
82 "String that marks the form at the start of a new file's autoload section.")
83
84 (defconst generate-autoload-section-trailer "\n;;;***\n"
85 "String which indicates the end of the section of autoloads for a file.")
86
87 (defconst generate-autoload-section-continuation ";;;;;; "
88 "String to add on each continuation of the section header form.")
89
90 ;; In some ways it would be nicer to use a value that is recognizably
91 ;; not a time-value, eg t, but that can cause issues if an older Emacs
92 ;; that does not expect non-time-values loads the file.
93 (defconst autoload--non-timestamp '(0 0 0 0)
94 "Value to insert when `autoload-timestamps' is nil.")
95
96 (defvar autoload-timestamps nil ; experimental, see bug#22213
97 "Non-nil means insert a timestamp for each input file into the output.
98 We use these in incremental updates of the output file to decide
99 if we need to rescan an input file. If you set this to nil,
100 then we use the timestamp of the output file instead. As a result:
101 - for fixed inputs, the output will be the same every time
102 - incremental updates of the output file might not be correct if:
103 i) the timestamp of the output file cannot be trusted (at least
104 relative to that of the input files)
105 ii) any of the input files can be modified during the time it takes
106 to create the output
107 iii) only a subset of the input files are scanned
108 These issues are unlikely to happen in practice, and would arguably
109 represent bugs in the build system. Item iii) will happen if you
110 use a command like `update-file-autoloads', though, since it only
111 checks a single input file.")
112
113 (defvar autoload-modified-buffers) ;Dynamically scoped var.
114
115 (defun make-autoload (form file &optional expansion)
116 "Turn FORM into an autoload or defvar for source file FILE.
117 Returns nil if FORM is not a special autoload form (i.e. a function definition
118 or macro definition or a defcustom).
119 If EXPANSION is non-nil, we're processing the macro expansion of an
120 expression, in which case we want to handle forms differently."
121 (let ((car (car-safe form)) expand)
122 (cond
123 ((and expansion (eq car 'defalias))
124 (pcase-let*
125 ((`(,_ ,_ ,arg . ,rest) form)
126 ;; `type' is non-nil if it defines a macro.
127 ;; `fun' is the function part of `arg' (defaults to `arg').
128 ((or (and (or `(cons 'macro ,fun) `'(macro . ,fun)) (let type t))
129 (and (let fun arg) (let type nil)))
130 arg)
131 ;; `lam' is the lambda expression in `fun' (or nil if not
132 ;; recognized).
133 (lam (if (memq (car-safe fun) '(quote function)) (cadr fun)))
134 ;; `args' is the list of arguments (or t if not recognized).
135 ;; `body' is the body of `lam' (or t if not recognized).
136 ((or `(lambda ,args . ,body)
137 (and (let args t) (let body t)))
138 lam)
139 ;; Get the `doc' from `body' or `rest'.
140 (doc (cond ((stringp (car-safe body)) (car body))
141 ((stringp (car-safe rest)) (car rest))))
142 ;; Look for an interactive spec.
143 (interactive (pcase body
144 ((or `((interactive . ,_) . ,_)
145 `(,_ (interactive . ,_) . ,_))
146 t))))
147 ;; Add the usage form at the end where describe-function-1
148 ;; can recover it.
149 (when (listp args) (setq doc (help-add-fundoc-usage doc args)))
150 ;; (message "autoload of %S" (nth 1 form))
151 `(autoload ,(nth 1 form) ,file ,doc ,interactive ,type)))
152
153 ((and expansion (memq car '(progn prog1)))
154 (let ((end (memq :autoload-end form)))
155 (when end ;Cut-off anything after the :autoload-end marker.
156 (setq form (copy-sequence form))
157 (setcdr (memq :autoload-end form) nil))
158 (let ((exps (delq nil (mapcar (lambda (form)
159 (make-autoload form file expansion))
160 (cdr form)))))
161 (when exps (cons 'progn exps)))))
162
163 ;; For complex cases, try again on the macro-expansion.
164 ((and (memq car '(easy-mmode-define-global-mode define-global-minor-mode
165 define-globalized-minor-mode defun defmacro
166 easy-mmode-define-minor-mode define-minor-mode
167 define-inline cl-defun cl-defmacro))
168 (macrop car)
169 (setq expand (let ((load-file-name file)) (macroexpand form)))
170 (memq (car expand) '(progn prog1 defalias)))
171 (make-autoload expand file 'expansion)) ;Recurse on the expansion.
172
173 ;; For special function-like operators, use the `autoload' function.
174 ((memq car '(define-skeleton define-derived-mode
175 define-compilation-mode define-generic-mode
176 easy-mmode-define-global-mode define-global-minor-mode
177 define-globalized-minor-mode
178 easy-mmode-define-minor-mode define-minor-mode
179 cl-defun defun* cl-defmacro defmacro*
180 define-overloadable-function))
181 (let* ((macrop (memq car '(defmacro cl-defmacro defmacro*)))
182 (name (nth 1 form))
183 (args (pcase car
184 ((or `defun `defmacro
185 `defun* `defmacro* `cl-defun `cl-defmacro
186 `define-overloadable-function)
187 (nth 2 form))
188 (`define-skeleton '(&optional str arg))
189 ((or `define-generic-mode `define-derived-mode
190 `define-compilation-mode)
191 nil)
192 (_ t)))
193 (body (nthcdr (or (function-get car 'doc-string-elt) 3) form))
194 (doc (if (stringp (car body)) (pop body))))
195 ;; Add the usage form at the end where describe-function-1
196 ;; can recover it.
197 (when (listp args) (setq doc (help-add-fundoc-usage doc args)))
198 ;; `define-generic-mode' quotes the name, so take care of that
199 `(autoload ,(if (listp name) name (list 'quote name))
200 ,file ,doc
201 ,(or (and (memq car '(define-skeleton define-derived-mode
202 define-generic-mode
203 easy-mmode-define-global-mode
204 define-global-minor-mode
205 define-globalized-minor-mode
206 easy-mmode-define-minor-mode
207 define-minor-mode))
208 t)
209 (eq (car-safe (car body)) 'interactive))
210 ,(if macrop ''macro nil))))
211
212 ;; For defclass forms, use `eieio-defclass-autoload'.
213 ((eq car 'defclass)
214 (let ((name (nth 1 form))
215 (superclasses (nth 2 form))
216 (doc (nth 4 form)))
217 (list 'eieio-defclass-autoload (list 'quote name)
218 (list 'quote superclasses) file doc)))
219
220 ;; Convert defcustom to less space-consuming data.
221 ((eq car 'defcustom)
222 (let ((varname (car-safe (cdr-safe form)))
223 (init (car-safe (cdr-safe (cdr-safe form))))
224 (doc (car-safe (cdr-safe (cdr-safe (cdr-safe form)))))
225 ;; (rest (cdr-safe (cdr-safe (cdr-safe (cdr-safe form)))))
226 )
227 `(progn
228 (defvar ,varname ,init ,doc)
229 (custom-autoload ',varname ,file
230 ,(condition-case nil
231 (null (cadr (memq :set form)))
232 (error nil))))))
233
234 ((eq car 'defgroup)
235 ;; In Emacs this is normally handled separately by cus-dep.el, but for
236 ;; third party packages, it can be convenient to explicitly autoload
237 ;; a group.
238 (let ((groupname (nth 1 form)))
239 `(let ((loads (get ',groupname 'custom-loads)))
240 (if (member ',file loads) nil
241 (put ',groupname 'custom-loads (cons ',file loads))))))
242
243 ;; When processing a macro expansion, any expression
244 ;; before a :autoload-end should be included. These are typically (put
245 ;; 'fun 'prop val) and things like that.
246 ((and expansion (consp form)) form)
247
248 ;; nil here indicates that this is not a special autoload form.
249 (t nil))))
250
251 ;; Forms which have doc-strings which should be printed specially.
252 ;; A doc-string-elt property of ELT says that (nth ELT FORM) is
253 ;; the doc-string in FORM.
254 ;; Those properties are now set in lisp-mode.el.
255
256 (defun autoload-find-generated-file ()
257 "Visit the autoload file for the current buffer, and return its buffer.
258 If a buffer is visiting the desired autoload file, return it."
259 (let ((enable-local-variables :safe)
260 (enable-local-eval nil))
261 ;; We used to use `raw-text' to read this file, but this causes
262 ;; problems when the file contains non-ASCII characters.
263 (let* ((delay-mode-hooks t)
264 (file (autoload-generated-file))
265 (file-missing (not (file-exists-p file))))
266 (when file-missing
267 (autoload-ensure-default-file file))
268 (with-current-buffer
269 (find-file-noselect
270 (autoload-ensure-file-writeable
271 file))
272 ;; block backups when the file has just been created, since
273 ;; the backups will just be the auto-generated headers.
274 ;; bug#23203
275 (when file-missing
276 (setq buffer-backed-up t)
277 (save-buffer))
278 (current-buffer)))))
279
280 (defun autoload-generated-file ()
281 (expand-file-name generated-autoload-file
282 ;; File-local settings of generated-autoload-file should
283 ;; be interpreted relative to the file's location,
284 ;; of course.
285 (if (not (local-variable-p 'generated-autoload-file))
286 (expand-file-name "lisp" source-directory))))
287
288
289 (defun autoload-read-section-header ()
290 "Read a section header form.
291 Since continuation lines have been marked as comments,
292 we must copy the text of the form and remove those comment
293 markers before we call `read'."
294 (save-match-data
295 (let ((beginning (point))
296 string)
297 (forward-line 1)
298 (while (looking-at generate-autoload-section-continuation)
299 (forward-line 1))
300 (setq string (buffer-substring beginning (point)))
301 (with-current-buffer (get-buffer-create " *autoload*")
302 (erase-buffer)
303 (insert string)
304 (goto-char (point-min))
305 (while (search-forward generate-autoload-section-continuation nil t)
306 (replace-match " "))
307 (goto-char (point-min))
308 (read (current-buffer))))))
309
310 (defvar autoload-print-form-outbuf nil
311 "Buffer which gets the output of `autoload-print-form'.")
312
313 (defun autoload-print-form (form)
314 "Print FORM such that `make-docfile' will find the docstrings.
315 The variable `autoload-print-form-outbuf' specifies the buffer to
316 put the output in."
317 (cond
318 ;; If the form is a sequence, recurse.
319 ((eq (car form) 'progn) (mapcar #'autoload-print-form (cdr form)))
320 ;; Symbols at the toplevel are meaningless.
321 ((symbolp form) nil)
322 (t
323 (let ((doc-string-elt (function-get (car-safe form) 'doc-string-elt))
324 (outbuf autoload-print-form-outbuf))
325 (if (and doc-string-elt (stringp (nth doc-string-elt form)))
326 ;; We need to hack the printing because the
327 ;; doc-string must be printed specially for
328 ;; make-docfile (sigh).
329 (let* ((p (nthcdr (1- doc-string-elt) form))
330 (elt (cdr p)))
331 (setcdr p nil)
332 (princ "\n(" outbuf)
333 (let ((print-escape-newlines t)
334 (print-quoted t)
335 (print-escape-nonascii t))
336 (dolist (elt form)
337 (prin1 elt outbuf)
338 (princ " " outbuf)))
339 (princ "\"\\\n" outbuf)
340 (let ((begin (with-current-buffer outbuf (point))))
341 (princ (substring (prin1-to-string (car elt)) 1)
342 outbuf)
343 ;; Insert a backslash before each ( that
344 ;; appears at the beginning of a line in
345 ;; the doc string.
346 (with-current-buffer outbuf
347 (save-excursion
348 (while (re-search-backward "\n[[(]" begin t)
349 (forward-char 1)
350 (insert "\\"))))
351 (if (null (cdr elt))
352 (princ ")" outbuf)
353 (princ " " outbuf)
354 (princ (substring (prin1-to-string (cdr elt)) 1)
355 outbuf))
356 (terpri outbuf)))
357 (let ((print-escape-newlines t)
358 (print-quoted t)
359 (print-escape-nonascii t))
360 (print form outbuf)))))))
361
362 (defun autoload-rubric (file &optional type feature)
363 "Return a string giving the appropriate autoload rubric for FILE.
364 TYPE (default \"autoloads\") is a string stating the type of
365 information contained in FILE. If FEATURE is non-nil, FILE
366 will provide a feature. FEATURE may be a string naming the
367 feature, otherwise it will be based on FILE's name.
368
369 At present, a feature is in fact always provided, but this should
370 not be relied upon."
371 (let ((basename (file-name-nondirectory file)))
372 (concat ";;; " basename
373 " --- automatically extracted " (or type "autoloads") "\n"
374 ";;\n"
375 ";;; Code:\n\n"
376 "\f\n"
377 ;; This is used outside of autoload.el, eg cus-dep, finder.
378 "(provide '"
379 (if (stringp feature)
380 feature
381 (file-name-sans-extension basename))
382 ")\n"
383 ";; Local Variables:\n"
384 ";; version-control: never\n"
385 ";; no-byte-compile: t\n"
386 ";; no-update-autoloads: t\n"
387 ";; coding: utf-8\n"
388 ";; End:\n"
389 ";;; " basename
390 " ends here\n")))
391
392 (defvar autoload-ensure-writable nil
393 "Non-nil means `autoload-ensure-default-file' makes existing file writable.")
394 ;; Just in case someone tries to get you to overwrite a file that you
395 ;; don't want to.
396 ;;;###autoload
397 (put 'autoload-ensure-writable 'risky-local-variable t)
398
399 (defun autoload-ensure-file-writeable (file)
400 ;; Probably pointless, but replaces the old AUTOGEN_VCS in lisp/Makefile,
401 ;; which was designed to handle CVSREAD=1 and equivalent.
402 (and autoload-ensure-writable
403 (let ((modes (file-modes file)))
404 (if (zerop (logand modes #o0200))
405 ;; Ignore any errors here, and let subsequent attempts
406 ;; to write the file raise any real error.
407 (ignore-errors (set-file-modes file (logior modes #o0200))))))
408 file)
409
410 (defun autoload-ensure-default-file (file)
411 "Make sure that the autoload file FILE exists, creating it if needed.
412 If the file already exists and `autoload-ensure-writable' is non-nil,
413 make it writable."
414 (write-region (autoload-rubric file) nil file))
415
416 (defun autoload-insert-section-header (outbuf autoloads load-name file time)
417 "Insert the section-header line,
418 which lists the file name and which functions are in it, etc."
419 ;; (cl-assert ;Make sure we don't insert it in the middle of another section.
420 ;; (save-excursion
421 ;; (or (not (re-search-backward
422 ;; (concat "\\("
423 ;; (regexp-quote generate-autoload-section-header)
424 ;; "\\)\\|\\("
425 ;; (regexp-quote generate-autoload-section-trailer)
426 ;; "\\)")
427 ;; nil t))
428 ;; (match-end 2))))
429 (insert generate-autoload-section-header)
430 (prin1 `(autoloads ,autoloads ,load-name ,file ,time)
431 outbuf)
432 (terpri outbuf)
433 ;; Break that line at spaces, to avoid very long lines.
434 ;; Make each sub-line into a comment.
435 (with-current-buffer outbuf
436 (save-excursion
437 (forward-line -1)
438 (while (not (eolp))
439 (move-to-column 64)
440 (skip-chars-forward "^ \n")
441 (or (eolp)
442 (insert "\n" generate-autoload-section-continuation))))))
443
444 (defun autoload-find-file (file)
445 "Fetch file and put it in a temp buffer. Return the buffer."
446 ;; It is faster to avoid visiting the file.
447 (setq file (expand-file-name file))
448 (with-current-buffer (get-buffer-create " *autoload-file*")
449 (kill-all-local-variables)
450 (erase-buffer)
451 (setq buffer-undo-list t
452 buffer-read-only nil)
453 (delay-mode-hooks (emacs-lisp-mode))
454 (setq default-directory (file-name-directory file))
455 (insert-file-contents file nil)
456 (let ((enable-local-variables :safe)
457 (enable-local-eval nil))
458 (hack-local-variables))
459 (current-buffer)))
460
461 (defvar no-update-autoloads nil
462 "File local variable to prevent scanning this file for autoload cookies.")
463
464 (defun autoload-file-load-name (file)
465 "Compute the name that will be used to load FILE."
466 ;; OUTFILE should be the name of the global loaddefs.el file, which
467 ;; is expected to be at the root directory of the files we're
468 ;; scanning for autoloads and will be in the `load-path'.
469 (let* ((outfile (default-value 'generated-autoload-file))
470 (name (file-relative-name file (file-name-directory outfile)))
471 (names '())
472 (dir (file-name-directory outfile)))
473 ;; If `name' has directory components, only keep the
474 ;; last few that are really needed.
475 (while name
476 (setq name (directory-file-name name))
477 (push (file-name-nondirectory name) names)
478 (setq name (file-name-directory name)))
479 (while (not name)
480 (cond
481 ((null (cdr names)) (setq name (car names)))
482 ((file-exists-p (expand-file-name "subdirs.el" dir))
483 ;; FIXME: here we only check the existence of subdirs.el,
484 ;; without checking its content. This makes it generate wrong load
485 ;; names for cases like lisp/term which is not added to load-path.
486 (setq dir (expand-file-name (pop names) dir)))
487 (t (setq name (mapconcat #'identity names "/")))))
488 (if (string-match "\\.elc?\\(\\.\\|\\'\\)" name)
489 (substring name 0 (match-beginning 0))
490 name)))
491
492 (defun generate-file-autoloads (file)
493 "Insert at point a loaddefs autoload section for FILE.
494 Autoloads are generated for defuns and defmacros in FILE
495 marked by `generate-autoload-cookie' (which see).
496 If FILE is being visited in a buffer, the contents of the buffer
497 are used.
498 Return non-nil in the case where no autoloads were added at point."
499 (interactive "fGenerate autoloads for file: ")
500 (let ((generated-autoload-file buffer-file-name))
501 (autoload-generate-file-autoloads file (current-buffer))))
502
503 (defun autoload--split-prefixes-1 (strs)
504 (let ((prefixes ()))
505 (dolist (str strs)
506 (string-match "\\`[^-:/_]*[-:/_]*" str)
507 (let* ((prefix (match-string 0 str))
508 (tail (substring str (match-end 0)))
509 (cell (assoc prefix prefixes)))
510 (cond
511 ((null cell) (push (list prefix tail) prefixes))
512 ((equal (cadr cell) tail) nil)
513 (t (setcdr cell (cons tail (cdr cell)))))))
514 prefixes))
515
516 (defun autoload--split-prefixes (prefixes)
517 (apply #'nconc
518 (mapcar (lambda (cell)
519 (let ((prefix (car cell)))
520 (mapcar (lambda (cell)
521 (cons (concat prefix (car cell)) (cdr cell)))
522 (autoload--split-prefixes-1 (cdr cell)))))
523 prefixes)))
524
525 (defvar autoload-compute-prefixes t
526 "If non-nil, autoload will add code to register the prefixes used in a file.
527 Standard prefixes won't be registered anyway. I.e. if a file \"foo.el\" defines
528 variables or functions that use \"foo-\" as prefix, that will not be registered.
529 But all other prefixes will be included.")
530
531 (defconst autoload-defs-autoload-max-size 5
532 "Target length of the list of definition prefixes per file.
533 If set too small, the prefixes will be too generic (i.e. they'll use little
534 memory, we'll end up looking in too many files when we need a particular
535 prefix), and if set too large, they will be too specific (i.e. they will
536 cost more memory use).")
537
538 (defvar autoload-popular-prefixes nil)
539
540 (defun autoload--make-defs-autoload (defs file)
541 ;; Remove the defs that obey the rule that file foo.el (or
542 ;; foo-mode.el) uses "foo-" as prefix.
543 ;; FIXME: help--symbol-completion-table still doesn't know how to use
544 ;; the rule that file foo.el (or foo-mode.el) uses "foo-" as prefix.
545 ;;(let ((prefix
546 ;; (concat (substring file 0 (string-match "-mode\\'" file)) "-")))
547 ;; (dolist (def (prog1 defs (setq defs nil)))
548 ;; (unless (string-prefix-p prefix def)
549 ;; (push def defs))))
550
551 ;; Then compute a small set of prefixes that cover all the
552 ;; remaining definitions.
553 (let ((prefixes (autoload--split-prefixes-1 defs))
554 (again t))
555 ;; (message "Initial prefixes %s : %S" file (mapcar #'car prefixes))
556 (while again
557 (setq again nil)
558 (let ((newprefixes
559 (sort
560 (mapcar (lambda (cell)
561 (cons cell
562 (autoload--split-prefixes-1 (cdr cell))))
563 prefixes)
564 (lambda (x y) (< (length (cdr x)) (length (cdr y)))))))
565 (setq prefixes nil)
566 (while newprefixes
567 (let ((x (pop newprefixes)))
568 (if (or (equal '("") (cdar x))
569 (and (cddr x)
570 (not (member (caar x)
571 autoload-popular-prefixes))
572 (> (+ (length prefixes) (length newprefixes)
573 (length (cdr x)))
574 autoload-defs-autoload-max-size)))
575 ;; Nothing to split or would split too deep.
576 (push (car x) prefixes)
577 ;; (message "Expand %S to %S" (caar x) (cdr x))
578 (setq again t)
579 (setq prefixes
580 (nconc (mapcar (lambda (cell)
581 (cons (concat (caar x)
582 (car cell))
583 (cdr cell)))
584 (cdr x))
585 prefixes)))))))
586 ;; (message "Final prefixes %s : %S" file (mapcar #'car prefixes))
587 (when prefixes
588 `(if (fboundp 'register-definition-prefixes)
589 (register-definition-prefixes ,file ',(mapcar #'car prefixes))))))
590
591 (defun autoload--setup-output (otherbuf outbuf absfile load-name)
592 (let ((outbuf
593 (or (if otherbuf
594 ;; A file-local setting of
595 ;; autoload-generated-file says we
596 ;; should ignore OUTBUF.
597 nil
598 outbuf)
599 (autoload-find-destination absfile load-name)
600 ;; The file has autoload cookies, but they're
601 ;; already up-to-date. If OUTFILE is nil, the
602 ;; entries are in the expected OUTBUF,
603 ;; otherwise they're elsewhere.
604 (throw 'done otherbuf))))
605 (with-current-buffer outbuf
606 (point-marker))))
607
608 (defun autoload--print-cookie-text (output-start load-name file)
609 (let ((standard-output (marker-buffer output-start)))
610 (search-forward generate-autoload-cookie)
611 (skip-chars-forward " \t")
612 (if (eolp)
613 (condition-case-unless-debug err
614 ;; Read the next form and make an autoload.
615 (let* ((form (prog1 (read (current-buffer))
616 (or (bolp) (forward-line 1))))
617 (autoload (make-autoload form load-name)))
618 (if autoload
619 nil
620 (setq autoload form))
621 (let ((autoload-print-form-outbuf
622 standard-output))
623 (autoload-print-form autoload)))
624 (error
625 (message "Autoload cookie error in %s:%s %S"
626 file (count-lines (point-min) (point)) err)))
627
628 ;; Copy the rest of the line to the output.
629 (princ (buffer-substring
630 (progn
631 ;; Back up over whitespace, to preserve it.
632 (skip-chars-backward " \f\t")
633 (if (= (char-after (1+ (point))) ? )
634 ;; Eat one space.
635 (forward-char 1))
636 (point))
637 (progn (forward-line 1) (point)))))))
638
639 (defvar autoload-builtin-package-versions nil)
640
641 ;; When called from `generate-file-autoloads' we should ignore
642 ;; `generated-autoload-file' altogether. When called from
643 ;; `update-file-autoloads' we don't know `outbuf'. And when called from
644 ;; `update-directory-autoloads' it's in between: we know the default
645 ;; `outbuf' but we should obey any file-local setting of
646 ;; `generated-autoload-file'.
647 (defun autoload-generate-file-autoloads (file &optional outbuf outfile)
648 "Insert an autoload section for FILE in the appropriate buffer.
649 Autoloads are generated for defuns and defmacros in FILE
650 marked by `generate-autoload-cookie' (which see).
651 If FILE is being visited in a buffer, the contents of the buffer are used.
652 OUTBUF is the buffer in which the autoload statements should be inserted.
653 If OUTBUF is nil, it will be determined by `autoload-generated-file'.
654
655 If provided, OUTFILE is expected to be the file name of OUTBUF.
656 If OUTFILE is non-nil and FILE specifies a `generated-autoload-file'
657 different from OUTFILE, then OUTBUF is ignored.
658
659 Return non-nil if and only if FILE adds no autoloads to OUTFILE
660 \(or OUTBUF if OUTFILE is nil). The actual return value is
661 FILE's modification time."
662 ;; Include the file name in any error messages
663 (condition-case err
664 (let (load-name
665 (print-length nil)
666 (print-level nil)
667 (float-output-format nil)
668 (visited (get-file-buffer file))
669 (otherbuf nil)
670 (absfile (expand-file-name file))
671 (defs '())
672 ;; nil until we found a cookie.
673 output-start)
674 (when
675 (catch 'done
676 (with-current-buffer (or visited
677 ;; It is faster to avoid visiting the file.
678 (autoload-find-file file))
679 ;; Obey the no-update-autoloads file local variable.
680 (unless no-update-autoloads
681 (or noninteractive (message "Generating autoloads for %s..." file))
682 (setq load-name
683 (if (stringp generated-autoload-load-name)
684 generated-autoload-load-name
685 (autoload-file-load-name absfile)))
686 ;; FIXME? Comparing file-names for equality with just equal
687 ;; is fragile, eg if one has an automounter prefix and one
688 ;; does not, but both refer to the same physical file.
689 (when (and outfile
690 (not
691 (if (memq system-type '(ms-dos windows-nt))
692 (equal (downcase outfile)
693 (downcase (autoload-generated-file)))
694 (equal outfile (autoload-generated-file)))))
695 (setq otherbuf t))
696 (save-excursion
697 (save-restriction
698 (widen)
699 (when autoload-builtin-package-versions
700 (let ((version (lm-header "version"))
701 package)
702 (and version
703 (setq version (ignore-errors (version-to-list version)))
704 (setq package (or (lm-header "package")
705 (file-name-sans-extension
706 (file-name-nondirectory file))))
707 (setq output-start (autoload--setup-output
708 otherbuf outbuf absfile load-name))
709 (let ((standard-output (marker-buffer output-start))
710 (print-quoted t))
711 (princ `(push (purecopy
712 ',(cons (intern package) version))
713 package--builtin-versions))
714 (princ "\n")))))
715
716 (goto-char (point-min))
717 (while (not (eobp))
718 (skip-chars-forward " \t\n\f")
719 (cond
720 ((looking-at (regexp-quote generate-autoload-cookie))
721 ;; If not done yet, figure out where to insert this text.
722 (unless output-start
723 (setq output-start (autoload--setup-output
724 otherbuf outbuf absfile load-name)))
725 (autoload--print-cookie-text output-start load-name file))
726 ((looking-at ";")
727 ;; Don't read the comment.
728 (forward-line 1))
729 (t
730 ;; Avoid (defvar <foo>) by requiring a trailing space.
731 ;; Also, ignore this prefix business
732 ;; for ;;;###tramp-autoload and friends.
733 (when (and (equal generate-autoload-cookie ";;;###autoload")
734 (looking-at "(\\(def[^ ]+\\) ['(]*\\([^' ()\"\n]+\\)[\n \t]")
735 (not (member
736 (match-string 1)
737 '("define-obsolete-function-alias"
738 "define-obsolete-variable-alias"
739 "define-category" "define-key"
740 "defgroup" "defface" "defadvice"
741 ;; Hmm... this is getting ugly:
742 "define-widget"
743 "defun-rcirc-command"))))
744 (push (match-string 2) defs))
745 (forward-sexp 1)
746 (forward-line 1))))))
747
748 (when (and autoload-compute-prefixes defs)
749 ;; This output needs to always go in the main loaddefs.el,
750 ;; regardless of generated-autoload-file.
751 ;; FIXME: the files that don't have autoload cookies but
752 ;; do have definitions end up listed twice in loaddefs.el:
753 ;; once for their register-definition-prefixes and once in
754 ;; the list of "files without any autoloads".
755 (let ((form (autoload--make-defs-autoload defs load-name)))
756 (cond
757 ((null form)) ;All defs obey the default rule, yay!
758 ((not otherbuf)
759 (unless output-start
760 (setq output-start (autoload--setup-output
761 nil outbuf absfile load-name)))
762 (let ((autoload-print-form-outbuf
763 (marker-buffer output-start)))
764 (autoload-print-form form)))
765 (t
766 (let* ((other-output-start
767 ;; To force the output to go to the main loaddefs.el
768 ;; rather than to generated-autoload-file,
769 ;; there are two cases: if outbuf is non-nil,
770 ;; then passing otherbuf=nil is enough, but if
771 ;; outbuf is nil, that won't cut it, so we
772 ;; locally bind generated-autoload-file.
773 (let ((generated-autoload-file
774 (default-value 'generated-autoload-file)))
775 (autoload--setup-output nil outbuf absfile load-name)))
776 (autoload-print-form-outbuf
777 (marker-buffer other-output-start)))
778 (autoload-print-form form)
779 (with-current-buffer (marker-buffer other-output-start)
780 (save-excursion
781 ;; Insert the section-header line which lists
782 ;; the file name and which functions are in it, etc.
783 (goto-char other-output-start)
784 (let ((relfile (file-relative-name absfile)))
785 (autoload-insert-section-header
786 (marker-buffer other-output-start)
787 "actual autoloads are elsewhere" load-name relfile
788 (nth 5 (file-attributes absfile)))
789 (insert ";;; Generated autoloads from " relfile "\n")))
790 (insert generate-autoload-section-trailer)))))))
791
792 (when output-start
793 (let ((secondary-autoloads-file-buf
794 (if otherbuf (current-buffer))))
795 (with-current-buffer (marker-buffer output-start)
796 (cl-assert (> (point) output-start))
797 (save-excursion
798 ;; Insert the section-header line which lists the file name
799 ;; and which functions are in it, etc.
800 (goto-char output-start)
801 (let ((relfile (file-relative-name absfile)))
802 (autoload-insert-section-header
803 (marker-buffer output-start)
804 () load-name relfile
805 (if secondary-autoloads-file-buf
806 ;; MD5 checksums are much better because they do not
807 ;; change unless the file changes (so they'll be
808 ;; equal on two different systems and will change
809 ;; less often than time-stamps, thus leading to fewer
810 ;; unneeded changes causing spurious conflicts), but
811 ;; using time-stamps is a very useful optimization,
812 ;; so we use time-stamps for the main autoloads file
813 ;; (loaddefs.el) where we have special ways to
814 ;; circumvent the "random change problem", and MD5
815 ;; checksum in secondary autoload files where we do
816 ;; not need the time-stamp optimization because it is
817 ;; already provided by the primary autoloads file.
818 (md5 secondary-autoloads-file-buf
819 ;; We'd really want to just use
820 ;; `emacs-internal' instead.
821 nil nil 'emacs-mule-unix)
822 (if autoload-timestamps
823 (nth 5 (file-attributes relfile))
824 autoload--non-timestamp)))
825 (insert ";;; Generated autoloads from " relfile "\n")))
826 (insert generate-autoload-section-trailer))))
827 (or noninteractive
828 (message "Generating autoloads for %s...done" file)))
829 (or visited
830 ;; We created this buffer, so we should kill it.
831 (kill-buffer (current-buffer))))
832 (or (not output-start)
833 ;; If the entries were added to some other buffer, then the file
834 ;; doesn't add entries to OUTFILE.
835 otherbuf))
836 (nth 5 (file-attributes absfile))))
837 (error
838 ;; Probably unbalanced parens in forward-sexp. In that case, the
839 ;; condition is scan-error, and the signal data includes point
840 ;; where the error was found; we'd like to convert that to
841 ;; line:col, but line-number-at-pos gets the wrong line in batch
842 ;; mode for some reason.
843 ;;
844 ;; At least this gets the file name in the error message; the
845 ;; developer can use goto-char to get to the error position.
846 (error "%s:0:0: error: %s: %s" file (car err) (cdr err)))
847 ))
848 \f
849 (defun autoload-save-buffers ()
850 (while autoload-modified-buffers
851 (with-current-buffer (pop autoload-modified-buffers)
852 (let ((version-control 'never))
853 (save-buffer)))))
854
855 ;; FIXME This command should be deprecated.
856 ;; See http://debbugs.gnu.org/22213#41
857 ;;;###autoload
858 (defun update-file-autoloads (file &optional save-after outfile)
859 "Update the autoloads for FILE.
860 If prefix arg SAVE-AFTER is non-nil, save the buffer too.
861
862 If FILE binds `generated-autoload-file' as a file-local variable,
863 autoloads are written into that file. Otherwise, the autoloads
864 file is determined by OUTFILE. If called interactively, prompt
865 for OUTFILE; if called from Lisp with OUTFILE nil, use the
866 existing value of `generated-autoload-file'.
867
868 Return FILE if there was no autoload cookie in it, else nil."
869 (interactive (list (read-file-name "Update autoloads for file: ")
870 current-prefix-arg
871 (read-file-name "Write autoload definitions to file: ")))
872 (let* ((generated-autoload-file (or outfile generated-autoload-file))
873 (autoload-modified-buffers nil)
874 ;; We need this only if the output file handles more than one input.
875 ;; See http://debbugs.gnu.org/22213#38 and subsequent.
876 (autoload-timestamps t)
877 (no-autoloads (autoload-generate-file-autoloads file)))
878 (if autoload-modified-buffers
879 (if save-after (autoload-save-buffers))
880 (if (called-interactively-p 'interactive)
881 (message "Autoload section for %s is up to date." file)))
882 (if no-autoloads file)))
883
884 (defun autoload-find-destination (file load-name)
885 "Find the destination point of the current buffer's autoloads.
886 FILE is the file name of the current buffer.
887 LOAD-NAME is the name as it appears in the output.
888 Returns a buffer whose point is placed at the requested location.
889 Returns nil if the file's autoloads are up-to-date, otherwise
890 removes any prior now out-of-date autoload entries."
891 (catch 'up-to-date
892 (let* ((buf (current-buffer))
893 (existing-buffer (if buffer-file-name buf))
894 (output-file (autoload-generated-file))
895 (output-time (if (file-exists-p output-file)
896 (nth 5 (file-attributes output-file))))
897 (found nil))
898 (with-current-buffer (autoload-find-generated-file)
899 ;; This is to make generated-autoload-file have Unix EOLs, so
900 ;; that it is portable to all platforms.
901 (or (eq 0 (coding-system-eol-type buffer-file-coding-system))
902 (set-buffer-file-coding-system 'unix))
903 (or (> (buffer-size) 0)
904 (error "Autoloads file %s lacks boilerplate" buffer-file-name))
905 (or (file-writable-p buffer-file-name)
906 (error "Autoloads file %s is not writable" buffer-file-name))
907 (widen)
908 (goto-char (point-min))
909 ;; Look for the section for LOAD-NAME.
910 (while (and (not found)
911 (search-forward generate-autoload-section-header nil t))
912 (let ((form (autoload-read-section-header)))
913 (cond ((string= (nth 2 form) load-name)
914 ;; We found the section for this file.
915 ;; Check if it is up to date.
916 (let ((begin (match-beginning 0))
917 (last-time (nth 4 form))
918 (file-time (nth 5 (file-attributes file))))
919 (if (and (or (null existing-buffer)
920 (not (buffer-modified-p existing-buffer)))
921 (cond
922 ;; FIXME? Arguably we should throw a
923 ;; user error, or some kind of warning,
924 ;; if we were called from update-file-autoloads,
925 ;; which can update only a single input file.
926 ;; It's not appropriate to use the output
927 ;; file modtime in such a case,
928 ;; if there are multiple input files
929 ;; contributing to the output.
930 ((and output-time
931 (member last-time
932 (list t autoload--non-timestamp)))
933 (not (time-less-p output-time file-time)))
934 ;; last-time is the time-stamp (specifying
935 ;; the last time we looked at the file) and
936 ;; the file hasn't been changed since.
937 ((listp last-time)
938 (not (time-less-p last-time file-time)))
939 ;; last-time is an MD5 checksum instead.
940 ((stringp last-time)
941 (equal last-time
942 (md5 buf nil nil 'emacs-mule)))))
943 (throw 'up-to-date nil)
944 (autoload-remove-section begin)
945 (setq found t))))
946 ((string< load-name (nth 2 form))
947 ;; We've come to a section alphabetically later than
948 ;; LOAD-NAME. We assume the file is in order and so
949 ;; there must be no section for LOAD-NAME. We will
950 ;; insert one before the section here.
951 (goto-char (match-beginning 0))
952 (setq found t)))))
953 (or found
954 (progn
955 ;; No later sections in the file. Put before the last page.
956 (goto-char (point-max))
957 (search-backward "\f" nil t)))
958 (unless (memq (current-buffer) autoload-modified-buffers)
959 (push (current-buffer) autoload-modified-buffers))
960 (current-buffer)))))
961
962 (defun autoload-remove-section (begin)
963 (goto-char begin)
964 (search-forward generate-autoload-section-trailer)
965 (delete-region begin (point)))
966
967 ;;;###autoload
968 (defun update-directory-autoloads (&rest dirs)
969 "Update autoload definitions for Lisp files in the directories DIRS.
970 In an interactive call, you must give one argument, the name of a
971 single directory. In a call from Lisp, you can supply multiple
972 directories as separate arguments, but this usage is discouraged.
973
974 The function does NOT recursively descend into subdirectories of the
975 directory or directories specified.
976
977 In an interactive call, prompt for a default output file for the
978 autoload definitions, and temporarily bind the variable
979 `generated-autoload-file' to this value. When called from Lisp,
980 use the existing value of `generated-autoload-file'. If any Lisp
981 file binds `generated-autoload-file' as a file-local variable,
982 write its autoloads into the specified file instead."
983 (interactive "DUpdate autoloads from directory: ")
984 (let* ((files-re (let ((tmp nil))
985 (dolist (suf (get-load-suffixes))
986 (unless (string-match "\\.elc" suf) (push suf tmp)))
987 (concat "^[^=.].*" (regexp-opt tmp t) "\\'")))
988 (files (apply #'nconc
989 (mapcar (lambda (dir)
990 (directory-files (expand-file-name dir)
991 t files-re))
992 dirs)))
993 (done ()) ;Files processed; to remove duplicates.
994 (changed nil) ;Non-nil if some change occured.
995 (last-time)
996 ;; Files with no autoload cookies or whose autoloads go to other
997 ;; files because of file-local autoload-generated-file settings.
998 (no-autoloads nil)
999 (autoload-modified-buffers nil)
1000 (generated-autoload-file
1001 (if (called-interactively-p 'interactive)
1002 (read-file-name "Write autoload definitions to file: ")
1003 generated-autoload-file))
1004 (output-time
1005 (if (file-exists-p generated-autoload-file)
1006 (nth 5 (file-attributes generated-autoload-file)))))
1007
1008 (with-current-buffer (autoload-find-generated-file)
1009 (save-excursion
1010 ;; Canonicalize file names and remove the autoload file itself.
1011 (setq files (delete (file-relative-name buffer-file-name)
1012 (mapcar #'file-relative-name files)))
1013
1014 (goto-char (point-min))
1015 (while (search-forward generate-autoload-section-header nil t)
1016 (let* ((form (autoload-read-section-header))
1017 (file (nth 3 form)))
1018 (cond ((and (consp file) (stringp (car file)))
1019 ;; This is a list of files that have no autoload cookies.
1020 ;; There shouldn't be more than one such entry.
1021 ;; Remove the obsolete section.
1022 (autoload-remove-section (match-beginning 0))
1023 (setq last-time (nth 4 form))
1024 (if (member last-time (list t autoload--non-timestamp))
1025 (setq last-time output-time))
1026 (dolist (file file)
1027 (let ((file-time (nth 5 (file-attributes file))))
1028 (when (and file-time
1029 (not (time-less-p last-time file-time)))
1030 ;; file unchanged
1031 (push file no-autoloads)
1032 (setq files (delete file files))))))
1033 ((not (stringp file)))
1034 ((or (not (file-exists-p file))
1035 ;; Remove duplicates as well, just in case.
1036 (member file done)
1037 ;; If the file is actually excluded.
1038 (member (expand-file-name file) autoload-excludes))
1039 ;; Remove the obsolete section.
1040 (setq changed t)
1041 (autoload-remove-section (match-beginning 0)))
1042 ((not (time-less-p (let ((oldtime (nth 4 form)))
1043 (if (member oldtime
1044 (list
1045 t autoload--non-timestamp))
1046 output-time
1047 oldtime))
1048 (nth 5 (file-attributes file))))
1049 ;; File hasn't changed.
1050 nil)
1051 (t
1052 (setq changed t)
1053 (autoload-remove-section (match-beginning 0))
1054 (if (autoload-generate-file-autoloads
1055 ;; Passing `current-buffer' makes it insert at point.
1056 file (current-buffer) buffer-file-name)
1057 (push file no-autoloads))))
1058 (push file done)
1059 (setq files (delete file files)))))
1060 ;; Elements remaining in FILES have no existing autoload sections yet.
1061 (let ((no-autoloads-time (or last-time '(0 0 0 0))) file-time)
1062 (dolist (file files)
1063 (cond
1064 ((member (expand-file-name file) autoload-excludes) nil)
1065 ;; Passing nil as second argument forces
1066 ;; autoload-generate-file-autoloads to look for the right
1067 ;; spot where to insert each autoloads section.
1068 ((setq file-time
1069 (autoload-generate-file-autoloads file nil buffer-file-name))
1070 (push file no-autoloads)
1071 (if (time-less-p no-autoloads-time file-time)
1072 (setq no-autoloads-time file-time)))
1073 (t (setq changed t))))
1074
1075 (when no-autoloads
1076 ;; Sort them for better readability.
1077 (setq no-autoloads (sort no-autoloads 'string<))
1078 ;; Add the `no-autoloads' section.
1079 (goto-char (point-max))
1080 (search-backward "\f" nil t)
1081 (autoload-insert-section-header
1082 (current-buffer) nil nil no-autoloads (if autoload-timestamps
1083 no-autoloads-time
1084 autoload--non-timestamp))
1085 (insert generate-autoload-section-trailer)))
1086
1087 ;; Don't modify the file if its content has not been changed, so `make'
1088 ;; dependencies don't trigger unnecessarily.
1089 (when changed
1090 (let ((version-control 'never))
1091 (save-buffer)))
1092
1093 ;; In case autoload entries were added to other files because of
1094 ;; file-local autoload-generated-file settings.
1095 (autoload-save-buffers))))
1096
1097 (define-obsolete-function-alias 'update-autoloads-from-directories
1098 'update-directory-autoloads "22.1")
1099
1100 ;;;###autoload
1101 (defun batch-update-autoloads ()
1102 "Update loaddefs.el autoloads in batch mode.
1103 Calls `update-directory-autoloads' on the command line arguments.
1104 Definitions are written to `generated-autoload-file' (which
1105 should be non-nil)."
1106 ;; For use during the Emacs build process only.
1107 ;; Exclude those files that are preloaded on ALL platforms.
1108 ;; These are the ones in loadup.el where "(load" is at the start
1109 ;; of the line (crude, but it works).
1110 (unless autoload-excludes
1111 (let ((default-directory (file-name-directory generated-autoload-file))
1112 file)
1113 (when (file-readable-p "loadup.el")
1114 (with-temp-buffer
1115 (insert-file-contents "loadup.el")
1116 (while (re-search-forward "^(load \"\\([^\"]+\\)\"" nil t)
1117 (setq file (match-string 1))
1118 (or (string-match "\\.el\\'" file)
1119 (setq file (format "%s.el" file)))
1120 (or (string-match "\\`site-" file)
1121 (push (expand-file-name file) autoload-excludes)))))))
1122 (let ((args command-line-args-left))
1123 (setq command-line-args-left nil)
1124 (apply #'update-directory-autoloads args)))
1125
1126 (provide 'autoload)
1127
1128 ;;; autoload.el ends here