autoload.el 14.7 KB
Newer Older
Eric S. Raymond's avatar
Eric S. Raymond committed
1 2
;;; autoload.el --- maintain autoloads in loaddefs.el.

3
;;; Copyright (C) 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
4
;;;
Eric S. Raymond's avatar
Eric S. Raymond committed
5
;; Author: Roland McGrath <roland@gnu.ai.mit.edu>
Eric S. Raymond's avatar
Eric S. Raymond committed
6
;; Keywords: maint
Eric S. Raymond's avatar
Eric S. Raymond committed
7

Jim Blandy's avatar
Jim Blandy committed
8 9
;;; This program is free software; you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
Eric S. Raymond's avatar
Eric S. Raymond committed
10
;;; the Free Software Foundation; either version 2, or (at your option)
Jim Blandy's avatar
Jim Blandy committed
11 12 13 14 15 16 17 18 19 20 21 22 23
;;; any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;; GNU General Public License for more details.
;;;
;;; A copy of the GNU General Public License can be obtained from this
;;; program's author (send electronic mail to roland@ai.mit.edu) or from
;;; the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
;;; 02139, USA.
;;;

Richard M. Stallman's avatar
Richard M. Stallman committed
24
;;; Commentary:
25

Richard M. Stallman's avatar
Richard M. Stallman committed
26
;; This code helps GNU Emacs maintainers keep the loaddefs.el file up to
27 28 29 30
;; date.  It interprets magic cookies of the form ";;;###autoload" in
;; lisp source files in various useful ways.  To learn more, read the
;; source; if you're going to use this, you'd better be able to.

Eric S. Raymond's avatar
Eric S. Raymond committed
31 32
;;; Code:

Jim Blandy's avatar
Jim Blandy committed
33 34
(defun make-autoload (form file)
  "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."
Jim Blandy's avatar
Jim Blandy committed
36
  (let ((car (car-safe form)))
37
    (if (memq car '(defun define-skeleton defmacro))
38 39
	(let ((macrop (eq car 'defmacro))
	      name doc)
40 41 42 43 44 45 46
	  (setq form (cdr form)
		name (car form)
		;; Ignore the arguments.
		form (cdr (if (eq car 'define-skeleton)
			      form
			    (cdr form)))
		doc (car form))
Jim Blandy's avatar
Jim Blandy committed
47 48 49 50
	  (if (stringp doc)
	      (setq form (cdr form))
	    (setq doc nil))
	  (list 'autoload (list 'quote name) file doc
51 52
		(or (eq car 'define-skeleton)
		    (eq (car-safe (car form)) 'interactive))
53
		(if macrop (list 'quote 'macro) nil)))
Jim Blandy's avatar
Jim Blandy committed
54 55
      nil)))

56 57
(put 'define-skeleton 'doc-string-elt 3)

Jim Blandy's avatar
Jim Blandy committed
58
(defconst generate-autoload-cookie ";;;###autoload"
59 60
  "Magic comment indicating the following form should be autoloaded.
Used by \\[update-file-autoloads].  This string should be
Jim Blandy's avatar
Jim Blandy committed
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
meaningless to Lisp (e.g., a comment).

This string is used:

;;;###autoload
\(defun function-to-be-autoloaded () ...)

If this string appears alone on a line, the following form will be
read and an autoload made for it.  If there is further text on the line,
that text will be copied verbatim to `generated-autoload-file'.")

(defconst generate-autoload-section-header "\f\n;;;### "
  "String inserted before the form identifying
the section of autoloads for a file.")

(defconst generate-autoload-section-trailer "\n;;;***\n"
  "String which indicates the end of the section of autoloads for a file.")

Jim Blandy's avatar
Jim Blandy committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
;;; Forms which have doc-strings which should be printed specially.
;;; A doc-string-elt property of ELT says that (nth ELT FORM) is
;;; the doc-string in FORM.
;;;
;;; There used to be the following note here:
;;; ;;; Note: defconst and defvar should NOT be marked in this way.
;;; ;;; We don't want to produce defconsts and defvars that
;;; ;;; make-docfile can grok, because then it would grok them twice,
;;; ;;; once in foo.el (where they are given with ;;;###autoload) and
;;; ;;; once in loaddefs.el.
;;;
;;; Counter-note: Yes, they should be marked in this way.
;;; make-docfile only processes those files that are loaded into the
;;; dumped Emacs, and those files should never have anything
;;; autoloaded here.  The above-feared problem only occurs with files
;;; which have autoloaded entries *and* are processed by make-docfile;
;;; there should be no such files.

Jim Blandy's avatar
Jim Blandy committed
97
(put 'autoload 'doc-string-elt 3)
Jim Blandy's avatar
Jim Blandy committed
98 99 100 101
(put 'defun    'doc-string-elt 3)
(put 'defvar   'doc-string-elt 3)
(put 'defconst 'doc-string-elt 3)
(put 'defmacro 'doc-string-elt 3)
Jim Blandy's avatar
Jim Blandy committed
102

103
(defun autoload-trim-file-name (file)
104 105 106 107 108
  ;; Returns a relative pathname of FILE
  ;; starting from the directory that loaddefs.el is in.
  ;; That is normally a directory in load-path,
  ;; which means Emacs will be able to find FILE when it looks.
  ;; Any extra directory names here would prevent finding the file.
109 110
  (setq file (expand-file-name file))
  (file-relative-name file
111
		      (file-name-directory generated-autoload-file)))
112

Jim Blandy's avatar
Jim Blandy committed
113 114 115
(defun generate-file-autoloads (file)
  "Insert at point a loaddefs autoload section for FILE.
autoloads are generated for defuns and defmacros in FILE
116
marked by `generate-autoload-cookie' (which see).
Jim Blandy's avatar
Jim Blandy committed
117 118 119 120 121 122 123 124 125 126
If FILE is being visited in a buffer, the contents of the buffer
are used."
  (interactive "fGenerate autoloads for file: ")
  (let ((outbuf (current-buffer))
	(autoloads-done '())
	(load-name (let ((name (file-name-nondirectory file)))
		     (if (string-match "\\.elc?$" name)
			 (substring name 0 (match-beginning 0))
		       name)))
	(print-length nil)
127
	(print-readably t)		; This does something in Lucid Emacs.
128
	(float-output-format nil)
Jim Blandy's avatar
Jim Blandy committed
129
	(done-any nil)
130
	(visited (get-file-buffer file))
Jim Blandy's avatar
Jim Blandy committed
131
	output-end)
Jim Blandy's avatar
Jim Blandy committed
132 133 134 135 136 137

    ;; If the autoload section we create here uses an absolute
    ;; pathname for FILE in its header, and then Emacs is installed
    ;; under a different path on another system,
    ;; `update-autoloads-here' won't be able to find the files to be
    ;; autoloaded.  So, if FILE is in the same directory or a
Jim Blandy's avatar
Jim Blandy committed
138
    ;; subdirectory of the current buffer's directory, we'll make it
Jim Blandy's avatar
Jim Blandy committed
139 140
    ;; relative to the current buffer's directory.
    (setq file (expand-file-name file))
141 142 143 144 145 146 147
    (let* ((source-truename (file-truename file))
	   (dir-truename (file-name-as-directory
			  (file-truename default-directory)))
	   (len (length dir-truename)))
      (if (and (< len (length source-truename))
	       (string= dir-truename (substring source-truename 0 len)))
	  (setq file (substring source-truename len))))
Jim Blandy's avatar
Jim Blandy committed
148

Jim Blandy's avatar
Jim Blandy committed
149
    (message "Generating autoloads for %s..." file)
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
    (save-excursion
      (unwind-protect
	  (progn
	    (set-buffer (find-file-noselect file))
	    (save-excursion
	      (save-restriction
		(widen)
		(goto-char (point-min))
		(while (not (eobp))
		  (skip-chars-forward " \t\n\f")
		  (cond
		   ((looking-at (regexp-quote generate-autoload-cookie))
		    (search-forward generate-autoload-cookie)
		    (skip-chars-forward " \t")
		    (setq done-any t)
165 166 167
		    (if (eolp)
			;; Read the next form and make an autoload.
			(let* ((form (prog1 (read (current-buffer))
168
				       (or (bolp) (forward-line 1))))
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
			       (autoload (make-autoload form load-name))
			       (doc-string-elt (get (car-safe form)
						    'doc-string-elt)))
			  (if autoload
			      (setq autoloads-done (cons (nth 1 form)
							 autoloads-done))
			    (setq autoload form))
			  (if (and doc-string-elt
				   (stringp (nth doc-string-elt autoload)))
			      ;; We need to hack the printing because the
			      ;; doc-string must be printed specially for
			      ;; make-docfile (sigh).
			      (let* ((p (nthcdr (1- doc-string-elt)
						autoload))
				     (elt (cdr p)))
				(setcdr p nil)
				(princ "\n(" outbuf)
				(let ((print-escape-newlines t))
				  (mapcar (function (lambda (elt)
						      (prin1 elt outbuf)
						      (princ " " outbuf)))
					  autoload))
				(princ "\"\\\n" outbuf)
				(let ((begin (save-excursion
					       (set-buffer outbuf)
					       (point))))
195
				  (princ (substring
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
					  (prin1-to-string (car elt)) 1)
					 outbuf)
				  ;; Insert a backslash before each ( that
				  ;; appears at the beginning of a line in
				  ;; the doc string.
				  (save-excursion
				    (set-buffer outbuf)
				    (save-excursion
				      (while (search-backward "\n(" begin t)
					(forward-char 1)
					(insert "\\"))))
				  (if (null (cdr elt))
				      (princ ")" outbuf)
				    (princ " " outbuf)
				    (princ (substring
					    (prin1-to-string (cdr elt))
					    1)
					   outbuf))
214 215
				  (terpri outbuf)))
			    (let ((print-escape-newlines t))
216
			      (print autoload outbuf))))
217 218 219
			  ;; Copy the rest of the line to the output.
			  (let ((begin (point)))
			    (forward-line 1)
220
			    (princ (buffer-substring begin (point)) outbuf))))
221 222 223 224 225 226
		   ((looking-at ";")
		    ;; Don't read the comment.
		    (forward-line 1))
		   (t
		    (forward-sexp 1)
		    (forward-line 1)))))))
227 228 229 230 231
	(or visited
	    ;; We created this buffer, so we should kill it.
	    (kill-buffer (current-buffer)))
	(set-buffer outbuf)
	(setq output-end (point-marker))))
Jim Blandy's avatar
Jim Blandy committed
232 233 234
    (if done-any
	(progn
	  (insert generate-autoload-section-header)
235 236
	  (prin1 (list 'autoloads autoloads-done load-name
		       (autoload-trim-file-name file)
Jim Blandy's avatar
Jim Blandy committed
237 238 239
		       (nth 5 (file-attributes file)))
		 outbuf)
	  (terpri outbuf)
240 241
	  (insert ";;; Generated autoloads from "
		  (autoload-trim-file-name file) "\n")
242 243 244 245 246 247 248 249 250 251 252
	  ;; Warn if we put a line in loaddefs.el
	  ;; that is long enough to cause trouble.
	  (while (< (point) output-end)
	    (let ((beg (point)))
	      (end-of-line)
	      (if (> (- (point) beg) 900)
		  (progn
		    (message "A line is too long--over 900 characters")
		    (sleep-for 2)
		    (goto-char output-end))))
	    (forward-line 1))
Jim Blandy's avatar
Jim Blandy committed
253 254 255
	  (goto-char output-end)
	  (insert generate-autoload-section-trailer)))
    (message "Generating autoloads for %s...done" file)))
256

Jim Blandy's avatar
Jim Blandy committed
257 258 259 260 261 262 263 264 265 266 267 268 269 270
(defconst generated-autoload-file "loaddefs.el"
   "*File \\[update-file-autoloads] puts autoloads into.
A .el file can set this in its local variables section to make its
autoloads go somewhere else.")

;;;###autoload
(defun update-file-autoloads (file)
  "Update the autoloads for FILE in `generated-autoload-file'
\(which FILE might bind in its local variables)."
  (interactive "fUpdate autoloads for file: ")
  (let ((load-name (let ((name (file-name-nondirectory file)))
		     (if (string-match "\\.elc?$" name)
			 (substring name 0 (match-beginning 0))
		       name)))
271
	(found nil)
Jim Blandy's avatar
Jim Blandy committed
272 273 274 275 276 277 278 279 280 281
	(existing-buffer (get-file-buffer file)))
    (save-excursion
      ;; We want to get a value for generated-autoload-file from
      ;; the local variables section if it's there.
      (set-buffer (find-file-noselect file))
      (set-buffer (find-file-noselect generated-autoload-file))
      (save-excursion
	(save-restriction
	  (widen)
	  (goto-char (point-min))
282 283 284
	  ;; Look for the section for LOAD-NAME.
	  (while (and (not found)
		      (search-forward generate-autoload-section-header nil t))
Jim Blandy's avatar
Jim Blandy committed
285 286 287
	    (let ((form (condition-case ()
			    (read (current-buffer))
			  (end-of-file nil))))
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
	      (cond ((string= (nth 2 form) load-name)
		     ;; We found the section for this file.
		     ;; Check if it is up to date.
		     (let ((begin (match-beginning 0))
			   (last-time (nth 4 form))
			   (file-time (nth 5 (file-attributes file))))
		       (if (and (or (null existing-buffer)
				    (not (buffer-modified-p existing-buffer)))
				(listp last-time) (= (length last-time) 2)
				(or (> (car last-time) (car file-time))
				    (and (= (car last-time) (car file-time))
					 (>= (nth 1 last-time)
					     (nth 1 file-time)))))
			   (progn
			     (message "Autoload section for %s is up to date."
				      file)
			     (setq found 'up-to-date))
			 (search-forward generate-autoload-section-trailer)
			 (delete-region begin (point))
			 (setq found t))))
		    ((string< load-name (nth 2 form))
		     ;; We've come to a section alphabetically later than
		     ;; LOAD-NAME.  We assume the file is in order and so
		     ;; there must be no section for LOAD-NAME.  We will
		     ;; insert one before the section here.
		     (goto-char (match-beginning 0))
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
		     (setq found 'new)))))
	  (or (eq found 'up-to-date)
	      (and (eq found 'new)
		   ;; Check that FILE has any cookies before generating a
		   ;; new section for it.
		   (save-excursion
		     (set-buffer (find-file-noselect file))
		     (save-excursion
		       (widen)
		       (goto-char (point-min))
		       (if (search-forward (concat "\n"
						   generate-autoload-cookie)
					   nil t)
			   nil
			 (if (interactive-p)
			     (message file " has no autoloads"))
			 t))))
331
	      (generate-file-autoloads file))))
332
      (if (interactive-p) (save-buffer))
Jim Blandy's avatar
Jim Blandy committed
333 334 335 336 337 338
      (if (and (null existing-buffer)
	       (setq existing-buffer (get-file-buffer file)))
	  (kill-buffer existing-buffer)))))

;;;###autoload
(defun update-autoloads-here ()
339 340
  "\
Update sections of the current buffer generated by \\[update-file-autoloads]."
Jim Blandy's avatar
Jim Blandy committed
341 342 343 344 345 346 347 348 349 350 351 352 353
  (interactive)
  (let ((generated-autoload-file (buffer-file-name)))
    (save-excursion
      (goto-char (point-min))
      (while (search-forward generate-autoload-section-header nil t)
	(let* ((form (condition-case ()
			 (read (current-buffer))
		       (end-of-file nil)))
	       (file (nth 3 form)))
	  (if (and (stringp file)
		   (or (get-file-buffer file)
		       (file-exists-p file)))
	      ()
354 355
	    (setq file (if (y-or-n-p (format "Can't find library `%s'; remove its autoloads? "
					     (nth 2 form) file))
Jim Blandy's avatar
Jim Blandy committed
356 357
			   t
			 (condition-case ()
358
			     (read-file-name (format "Find `%s' load file: "
Jim Blandy's avatar
Jim Blandy committed
359 360 361 362 363 364 365 366 367 368 369 370 371 372
						     (nth 2 form))
					     nil nil t)
			   (quit nil)))))
	  (if file
	      (let ((begin (match-beginning 0)))
		(search-forward generate-autoload-section-trailer)
		(delete-region begin (point))))
	  (if (stringp file)
	      (generate-file-autoloads file)))))))

;;;###autoload
(defun update-directory-autoloads (dir)
  "Run \\[update-file-autoloads] on each .el file in DIR."
  (interactive "DUpdate autoloads for directory: ")
373 374 375
  (let ((enable-local-eval nil))
    (mapcar 'update-file-autoloads
	    (directory-files dir t "^[^=].*\\.el$")))
376 377 378 379
  (if (interactive-p)
      (save-excursion
	(set-buffer (find-file-noselect generated-autoload-file))
	(save-buffer))))
Jim Blandy's avatar
Jim Blandy committed
380 381 382 383 384 385 386

;;;###autoload
(defun batch-update-autoloads ()
  "Update the autoloads for the files or directories on the command line.
Runs \\[update-file-autoloads] on files and \\[update-directory-autoloads]
on directories.  Must be used only with -batch, and kills Emacs on completion.
Each file will be processed even if an error occurred previously.
387
For example, invoke `emacs -batch -f batch-update-autoloads *.el'."
Jim Blandy's avatar
Jim Blandy committed
388
  (if (not noninteractive)
Roland McGrath's avatar
Roland McGrath committed
389
      (error "batch-update-autoloads is to be used only with -batch"))
Jim Blandy's avatar
Jim Blandy committed
390
  (let ((lost nil)
391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413
	(args command-line-args-left)
	(enable-local-eval nil))	;Don't query in batch mode.
    (message "Updating autoloads in %s..." generated-autoload-file)
    (let ((frob (function
 		 (lambda (file)
 		   (condition-case lossage
 		       (update-file-autoloads file)
 		     (error
 		      (princ ">>Error processing ")
 		      (princ file)
 		      (princ ": ")
 		      (if (fboundp 'display-error)
 			  (display-error lossage nil)
 			(prin1 lossage))
 		      (princ "\n")
 		      (setq lost t)))))))
      (while args
 	(if (file-directory-p (expand-file-name (car args)))
 	    (let ((rest (directory-files (car args) t "\\.el$")))
 	      (while rest
 		(funcall frob (car rest))
 		(setq rest (cdr rest))))
 	  (funcall frob (car args)))
414
 	(setq args (cdr args))))
Jim Blandy's avatar
Jim Blandy committed
415 416 417 418 419
    (save-some-buffers t)
    (message "Done")
    (kill-emacs (if lost 1 0))))

(provide 'autoload)
Jim Blandy's avatar
Jim Blandy committed
420

Eric S. Raymond's avatar
Eric S. Raymond committed
421
;;; autoload.el ends here