1 ;;; autoload.el --- maintain autoloads in loaddefs.el.
3 ;;; Copyright (C) 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
5 ;; Author: Roland McGrath <roland@gnu.ai.mit.edu>
8 ;;; This program is free software; you can redistribute it and/or modify
9 ;;; it under the terms of the GNU General Public License as published by
10 ;;; the Free Software Foundation; either version 2, or (at your option)
11 ;;; any later version.
13 ;;; This program is distributed in the hope that it will be useful,
14 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;;; GNU General Public License for more details.
18 ;;; A copy of the GNU General Public License can be obtained from this
19 ;;; program's author (send electronic mail to roland@ai.mit.edu) or from
20 ;;; the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
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.
33 (defun make-autoload (form file)
34 "Turn FORM, a defun or defmacro, into an autoload for source file FILE.
35 Returns nil if FORM is not a defun, define-skeleton or defmacro."
36 (let ((car (car-safe form)))
37 (if (memq car '(defun define-skeleton defmacro))
38 (let ((macrop (eq car 'defmacro))
42 ;; Ignore the arguments.
43 form (cdr (if (eq car 'define-skeleton)
48 (setq form (cdr form))
50 (list 'autoload (list 'quote name) file doc
51 (or (eq car 'define-skeleton)
52 (eq (car-safe (car form)) 'interactive))
53 (if macrop (list 'quote 'macro) nil)))
56 (put 'define-skeleton 'doc-string-elt 3)
58 (defconst generate-autoload-cookie ";;;###autoload"
59 "Magic comment indicating the following form should be autoloaded.
60 Used by \\[update-file-autoloads]. This string should be
61 meaningless to Lisp (e.g., a comment).
66 \(defun function-to-be-autoloaded () ...)
68 If this string appears alone on a line, the following form will be
69 read and an autoload made for it. If there is further text on the line,
70 that text will be copied verbatim to `generated-autoload-file'.")
72 (defconst generate-autoload-section-header "\f\n;;;### "
73 "String inserted before the form identifying
74 the section of autoloads for a file.")
76 (defconst generate-autoload-section-trailer "\n;;;***\n"
77 "String which indicates the end of the section of autoloads for a file.")
79 ;;; Forms which have doc-strings which should be printed specially.
80 ;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
81 ;;; the doc-string in FORM.
83 ;;; There used to be the following note here:
84 ;;; ;;; Note: defconst and defvar should NOT be marked in this way.
85 ;;; ;;; We don't want to produce defconsts and defvars that
86 ;;; ;;; make-docfile can grok, because then it would grok them twice,
87 ;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
88 ;;; ;;; once in loaddefs.el.
90 ;;; Counter-note: Yes, they should be marked in this way.
91 ;;; make-docfile only processes those files that are loaded into the
92 ;;; dumped Emacs, and those files should never have anything
93 ;;; autoloaded here. The above-feared problem only occurs with files
94 ;;; which have autoloaded entries *and* are processed by make-docfile;
95 ;;; there should be no such files.
97 (put 'autoload 'doc-string-elt 3)
98 (put 'defun 'doc-string-elt 3)
99 (put 'defvar 'doc-string-elt 3)
100 (put 'defconst 'doc-string-elt 3)
101 (put 'defmacro 'doc-string-elt 3)
103 (defun autoload-trim-file-name (file)
104 ;; Returns a relative pathname of FILE
105 ;; starting from the directory that loaddefs.el is in.
106 ;; That is normally a directory in load-path,
107 ;; which means Emacs will be able to find FILE when it looks.
108 ;; Any extra directory names here would prevent finding the file.
109 (setq file (expand-file-name file))
110 (file-relative-name file
111 (file-name-directory generated-autoload-file)))
113 (defun generate-file-autoloads (file)
114 "Insert at point a loaddefs autoload section for FILE.
115 autoloads are generated for defuns and defmacros in FILE
116 marked by `generate-autoload-cookie' (which see).
117 If FILE is being visited in a buffer, the contents of the buffer
119 (interactive "fGenerate autoloads for file: ")
120 (let ((outbuf (current-buffer))
122 (load-name (let ((name (file-name-nondirectory file)))
123 (if (string-match "\\.elc?$" name)
124 (substring name 0 (match-beginning 0))
127 (print-readably t) ; This does something in Lucid Emacs.
128 (float-output-format nil)
130 (visited (get-file-buffer file))
133 ;; If the autoload section we create here uses an absolute
134 ;; pathname for FILE in its header, and then Emacs is installed
135 ;; under a different path on another system,
136 ;; `update-autoloads-here' won't be able to find the files to be
137 ;; autoloaded. So, if FILE is in the same directory or a
138 ;; subdirectory of the current buffer's directory, we'll make it
139 ;; relative to the current buffer's directory.
140 (setq file (expand-file-name file))
141 (let* ((source-truename (file-truename file))
142 (dir-truename (file-name-as-directory
143 (file-truename default-directory)))
144 (len (length dir-truename)))
145 (if (and (< len (length source-truename))
146 (string= dir-truename (substring source-truename 0 len)))
147 (setq file (substring source-truename len))))
149 (message "Generating autoloads for %s..." file)
155 ;; It is faster to avoid visiting the file.
156 (set-buffer (get-buffer-create " *generate-autoload-file*"))
157 (kill-all-local-variables)
159 (insert-file-contents file nil))
163 (goto-char (point-min))
165 (skip-chars-forward " \t\n\f")
167 ((looking-at (regexp-quote generate-autoload-cookie))
168 (search-forward generate-autoload-cookie)
169 (skip-chars-forward " \t")
172 ;; Read the next form and make an autoload.
173 (let* ((form (prog1 (read (current-buffer))
174 (or (bolp) (forward-line 1))))
175 (autoload (make-autoload form load-name))
176 (doc-string-elt (get (car-safe form)
179 (setq autoloads-done (cons (nth 1 form)
181 (setq autoload form))
182 (if (and doc-string-elt
183 (stringp (nth doc-string-elt autoload)))
184 ;; We need to hack the printing because the
185 ;; doc-string must be printed specially for
186 ;; make-docfile (sigh).
187 (let* ((p (nthcdr (1- doc-string-elt)
192 (let ((print-escape-newlines t))
193 (mapcar (function (lambda (elt)
197 (princ "\"\\\n" outbuf)
198 (let ((begin (save-excursion
202 (prin1-to-string (car elt)) 1)
204 ;; Insert a backslash before each ( that
205 ;; appears at the beginning of a line in
210 (while (search-backward "\n(" begin t)
217 (prin1-to-string (cdr elt))
221 (let ((print-escape-newlines t))
222 (print autoload outbuf))))
223 ;; Copy the rest of the line to the output.
224 (let ((begin (point)))
226 (princ (buffer-substring begin (point)) outbuf))))
228 ;; Don't read the comment.
232 (forward-line 1)))))))
234 ;; We created this buffer, so we should kill it.
235 (kill-buffer (current-buffer)))
237 (setq output-end (point-marker))))
240 (insert generate-autoload-section-header)
241 (prin1 (list 'autoloads autoloads-done load-name
242 (autoload-trim-file-name file)
243 (nth 5 (file-attributes file)))
246 (insert ";;; Generated autoloads from "
247 (autoload-trim-file-name file) "\n")
248 ;; Warn if we put a line in loaddefs.el
249 ;; that is long enough to cause trouble.
250 (while (< (point) output-end)
253 (if (> (- (point) beg) 900)
255 (message "A line is too long--over 900 characters")
257 (goto-char output-end))))
259 (goto-char output-end)
260 (insert generate-autoload-section-trailer)))
261 (message "Generating autoloads for %s...done" file)))
263 (defconst generated-autoload-file "loaddefs.el"
264 "*File \\[update-file-autoloads] puts autoloads into.
265 A .el file can set this in its local variables section to make its
266 autoloads go somewhere else.")
269 (defun update-file-autoloads (file)
270 "Update the autoloads for FILE in `generated-autoload-file'
271 \(which FILE might bind in its local variables)."
272 (interactive "fUpdate autoloads for file: ")
273 (let ((load-name (let ((name (file-name-nondirectory file)))
274 (if (string-match "\\.elc?$" name)
275 (substring name 0 (match-beginning 0))
278 (existing-buffer (get-file-buffer file)))
280 ;; We want to get a value for generated-autoload-file from
281 ;; the local variables section if it's there.
282 (set-buffer (find-file-noselect file))
283 (set-buffer (find-file-noselect generated-autoload-file))
287 (goto-char (point-min))
288 ;; Look for the section for LOAD-NAME.
289 (while (and (not found)
290 (search-forward generate-autoload-section-header nil t))
291 (let ((form (condition-case ()
292 (read (current-buffer))
294 (cond ((string= (nth 2 form) load-name)
295 ;; We found the section for this file.
296 ;; Check if it is up to date.
297 (let ((begin (match-beginning 0))
298 (last-time (nth 4 form))
299 (file-time (nth 5 (file-attributes file))))
300 (if (and (or (null existing-buffer)
301 (not (buffer-modified-p existing-buffer)))
302 (listp last-time) (= (length last-time) 2)
303 (or (> (car last-time) (car file-time))
304 (and (= (car last-time) (car file-time))
305 (>= (nth 1 last-time)
306 (nth 1 file-time)))))
308 (message "Autoload section for %s is up to date."
310 (setq found 'up-to-date))
311 (search-forward generate-autoload-section-trailer)
312 (delete-region begin (point))
314 ((string< load-name (nth 2 form))
315 ;; We've come to a section alphabetically later than
316 ;; LOAD-NAME. We assume the file is in order and so
317 ;; there must be no section for LOAD-NAME. We will
318 ;; insert one before the section here.
319 (goto-char (match-beginning 0))
320 (setq found 'new)))))
321 (or (eq found 'up-to-date)
323 ;; Check that FILE has any cookies before generating a
324 ;; new section for it.
326 (set-buffer (find-file-noselect file))
329 (goto-char (point-min))
330 (if (search-forward (concat "\n"
331 generate-autoload-cookie)
335 (message file " has no autoloads"))
337 (generate-file-autoloads file))))
338 (if (interactive-p) (save-buffer))
339 (if (and (null existing-buffer)
340 (setq existing-buffer (get-file-buffer file)))
341 (kill-buffer existing-buffer)))))
344 (defun update-autoloads-here ()
346 Update sections of the current buffer generated by \\[update-file-autoloads]."
348 (let ((generated-autoload-file (buffer-file-name)))
350 (goto-char (point-min))
351 (while (search-forward generate-autoload-section-header nil t)
352 (let* ((form (condition-case ()
353 (read (current-buffer))
356 (if (and (stringp file)
357 (or (get-file-buffer file)
358 (file-exists-p file)))
360 (setq file (if (y-or-n-p (format "Can't find library `%s'; remove its autoloads? "
364 (read-file-name (format "Find `%s' load file: "
369 (let ((begin (match-beginning 0)))
370 (search-forward generate-autoload-section-trailer)
371 (delete-region begin (point))))
373 (generate-file-autoloads file)))))))
376 (defun update-directory-autoloads (dir)
377 "Run \\[update-file-autoloads] on each .el file in DIR."
378 (interactive "DUpdate autoloads for directory: ")
379 (let ((enable-local-eval nil))
380 (mapcar 'update-file-autoloads
381 (directory-files dir t "^[^=].*\\.el$")))
384 (set-buffer (find-file-noselect generated-autoload-file))
388 (defun batch-update-autoloads ()
389 "Update the autoloads for the files or directories on the command line.
390 Runs \\[update-file-autoloads] on files and \\[update-directory-autoloads]
391 on directories. Must be used only with -batch, and kills Emacs on completion.
392 Each file will be processed even if an error occurred previously.
393 For example, invoke `emacs -batch -f batch-update-autoloads *.el'."
394 (if (not noninteractive)
395 (error "batch-update-autoloads is to be used only with -batch"))
397 (args command-line-args-left)
398 (enable-local-eval nil)) ;Don't query in batch mode.
399 (message "Updating autoloads in %s..." generated-autoload-file)
400 (let ((frob (function
402 (condition-case lossage
403 (update-file-autoloads file)
405 (princ ">>Error processing ")
408 (if (fboundp 'display-error)
409 (display-error lossage nil)
414 (if (file-directory-p (expand-file-name (car args)))
415 (let ((rest (directory-files (car args) t "\\.el$")))
417 (funcall frob (car rest))
418 (setq rest (cdr rest))))
419 (funcall frob (car args)))
420 (setq args (cdr args))))
421 (save-some-buffers t)
423 (kill-emacs (if lost 1 0))))
427 ;;; autoload.el ends here