comparison lisp/emacs-lisp/bytecomp.el @ 99747:51f96d4c63b0

* emacs-lisp/bytecomp.el (byte-compile-dynamic-docstrings) (byte-compile-output-docform): Reflow docstrings. (no-byte-compile): Fix typo in docstring. (byte-recompile-directory, compile-defun): Doc fixes. (emacs-lisp-file-regexp, byte-compile-verbose) (byte-compile-compatibility, byte-optimize, byte-compile-delete-errors) (byte-compile-dynamic-docstrings, byte-optimize-log) (byte-compile-error-on-warn, byte-compile-warnings) (byte-compile-generate-call-tree, byte-compile-call-tree-sort): Remove * from defcustom docstrings.

99746:07389f46a9e0

(defgroup bytecomp nil
  "Emacs Lisp byte-compiler."
  :group 'lisp)

(defcustom emacs-lisp-file-regexp "\\.el$"
  "*Regexp which matches Emacs Lisp source files.
You may want to redefine the function `byte-compile-dest-file'
if you change this variable."
  :group 'bytecomp
  :type 'regexp)

;; thing to do.
(autoload 'byte-decompile-bytecode "byte-opt")

(defcustom byte-compile-verbose
  (and (not noninteractive) (> baud-rate search-slow-speed))
  "*Non-nil means print messages describing progress of byte-compiler."
  :group 'bytecomp
  :type 'boolean)

(defcustom byte-compile-compatibility nil
  "*Non-nil means generate output that can run in Emacs 18.
This only means that it can run in principle, if it doesn't require
facilities that have been added more recently."
  :group 'bytecomp
  :type 'boolean)

;;   "*If this is true, then the byte-compiler will generate bytecode which
;; makes use of byte-ops which are present only in Emacs 19.  Code generated
;; this way can never be run in Emacs 18, and may even cause it to crash.")

(defcustom byte-optimize t
  "*Enable optimization in the byte compiler.
Possible values are:
  nil      - no optimization
  t        - all optimizations
  `source' - source-level optimizations only
  `byte'   - code-level optimizations only"

		 (const :tag "all" t)
		 (const :tag "source-level" source)
		 (const :tag "byte-level" byte)))

(defcustom byte-compile-delete-errors nil
  "*If non-nil, the optimizer may delete forms that may signal an error.
This includes variable references and calls to functions such as `car'."
  :group 'bytecomp
  :type 'boolean)

(defvar byte-compile-dynamic nil

(defvar byte-compile-disable-print-circle nil
  "If non-nil, disable `print-circle' on printing a byte-compiled code.")
;;;###autoload(put 'byte-compile-disable-print-circle 'safe-local-variable 'booleanp)

(defcustom byte-compile-dynamic-docstrings t
  "*If non-nil, compile doc strings for lazy access.
We bury the doc strings of functions and variables
inside comments in the file, and bring them into core only when they
are actually needed.

When this option is true, if you load the compiled file and then move it,
you won't be able to find the documentation of anything in that file.

To disable this option for a certain file, make it a file-local variable

  :group 'bytecomp
  :type 'boolean)
;;;###autoload(put 'byte-compile-dynamic-docstrings 'safe-local-variable 'booleanp)

(defcustom byte-optimize-log nil
  "*If true, the byte-compiler will log its optimizations into *Compile-Log*.
If this is 'source, then only source-level optimizations will be logged.
If it is 'byte, then only byte-level optimizations will be logged."
  :group 'bytecomp
  :type '(choice (const :tag "none" nil)
		 (const :tag "all" t)
		 (const :tag "source-level" source)
		 (const :tag "byte-level" byte)))

(defcustom byte-compile-error-on-warn nil
  "*If true, the byte-compiler reports warnings with `error'."
  :group 'bytecomp
  :type 'boolean)

(defconst byte-compile-warning-types
  '(redefine callargs free-vars unresolved
	     obsolete noruntime cl-functions interactive-only
	     make-local mapcar)
  "The list of warning types used when `byte-compile-warnings' is t.")
(defcustom byte-compile-warnings t
  "*List of warnings that the byte-compiler should issue (t for all).

Elements of the list may be:

  free-vars   references to variables not in the current lexical scope.
  unresolved  calls to unknown functions.

(defvar byte-compile-not-obsolete-var nil
  "If non-nil, this is a variable that shouldn't be reported as obsolete.")

(defcustom byte-compile-generate-call-tree nil
  "*Non-nil means collect call-graph information when compiling.
This records which functions were called and from where.
If the value is t, compilation displays the call graph when it finishes.
If the value is neither t nor nil, compilation asks you whether to display
the graph.

invoked interactively are excluded from this list."
  :group 'bytecomp
  :type '(choice (const :tag "Yes" t) (const :tag "No" nil)
		 (other :tag "Ask" lambda)))

(defvar byte-compile-call-tree nil "Alist of functions and their call tree.
Each element looks like

  \(FUNCTION CALLERS CALLS\)

where CALLERS is a list of functions that call FUNCTION, and CALLS
is a list of functions for which calls were generated while compiling
FUNCTION.")

(defcustom byte-compile-call-tree-sort 'name
  "*If non-nil, sort the call tree.
The values `name', `callers', `calls', `calls+callers'
specify different fields to sort on."
  :group 'bytecomp
  :type '(choice (const name) (const callers) (const calls)
		 (const calls+callers) (const nil)))

;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2008-02/msg00134.html
;;;###autoload
(defun byte-recompile-directory (bytecomp-directory &optional bytecomp-arg
                                                    bytecomp-force)
  "Recompile every `.el' file in BYTECOMP-DIRECTORY that needs recompilation.
This is if a `.elc' file exists but is older than the `.el' file.
Files in subdirectories of BYTECOMP-DIRECTORY are processed also.

If the `.elc' file does not exist, normally this function *does not*
compile the corresponding `.el' file.  However, if the prefix argument
BYTECOMP-ARG is 0, that means do compile all those files.  A nonzero

	       (if (> skip-count 0) (format ", %d skipped" skip-count) "")
	       (if (> dir-count 1)
                   (format " in %d directories" dir-count) "")))))

(defvar no-byte-compile nil
  "Non-nil to prevent byte-compiling of emacs-lisp code.
This is normally set in local file variables at the end of the elisp file:

;; Local Variables:\n;; no-byte-compile: t\n;; End: ")
;;;###autoload(put 'no-byte-compile 'safe-local-variable 'booleanp)

;;; compiling a single function
;;;###autoload
(defun compile-defun (&optional arg)
  "Compile and evaluate the current top-level form.
Print the result in the echo area.
With argument, insert value in current buffer after the form."
  (interactive "P")
  (save-excursion
    (end-of-defun)
    (beginning-of-defun)
    (let* ((byte-compile-current-file nil)

  "Print a form with a doc string.  INFO is (prefix doc-index postfix).
If PREFACE and NAME are non-nil, print them too,
before INFO and the FORM but after the doc string itself.
If SPECINDEX is non-nil, it is the index in FORM
of the function bytecode string.  In that case,
we output that argument and the following argument (the constants vector)
together, for lazy loading.
QUOTED says that we have to put a quote before the
list that represents a doc string reference.
`autoload' and `custom-declare-variable' need that."
  ;; We need to examine byte-compile-dynamic-docstrings
  ;; in the input buffer (now current), not in the output buffer.

    (cond
     ((= 1 len) (byte-compile-constant 0))
     ((= 2 len)
      (byte-compile-form (cadr form))
      (byte-compile-out 'byte-negate 0))
     ((= 3 len) 
      (byte-compile-form (nth 1 form))
      (byte-compile-form (nth 2 form))
      (byte-compile-out 'byte-diff 0))
     ;; Don't use binary operations for > 2 operands, as that may
     ;; cause overflow/truncation in float operations.

99747:51f96d4c63b0

(defgroup bytecomp nil
  "Emacs Lisp byte-compiler."
  :group 'lisp)

(defcustom emacs-lisp-file-regexp "\\.el$"
  "Regexp which matches Emacs Lisp source files.
You may want to redefine the function `byte-compile-dest-file'
if you change this variable."
  :group 'bytecomp
  :type 'regexp)

;; thing to do.
(autoload 'byte-decompile-bytecode "byte-opt")

(defcustom byte-compile-verbose
  (and (not noninteractive) (> baud-rate search-slow-speed))
  "Non-nil means print messages describing progress of byte-compiler."
  :group 'bytecomp
  :type 'boolean)

(defcustom byte-compile-compatibility nil
  "Non-nil means generate output that can run in Emacs 18.
This only means that it can run in principle, if it doesn't require
facilities that have been added more recently."
  :group 'bytecomp
  :type 'boolean)

;;   "*If this is true, then the byte-compiler will generate bytecode which
;; makes use of byte-ops which are present only in Emacs 19.  Code generated
;; this way can never be run in Emacs 18, and may even cause it to crash.")

(defcustom byte-optimize t
  "Enable optimization in the byte compiler.
Possible values are:
  nil      - no optimization
  t        - all optimizations
  `source' - source-level optimizations only
  `byte'   - code-level optimizations only"

		 (const :tag "all" t)
		 (const :tag "source-level" source)
		 (const :tag "byte-level" byte)))

(defcustom byte-compile-delete-errors nil
  "If non-nil, the optimizer may delete forms that may signal an error.
This includes variable references and calls to functions such as `car'."
  :group 'bytecomp
  :type 'boolean)

(defvar byte-compile-dynamic nil

(defvar byte-compile-disable-print-circle nil
  "If non-nil, disable `print-circle' on printing a byte-compiled code.")
;;;###autoload(put 'byte-compile-disable-print-circle 'safe-local-variable 'booleanp)

(defcustom byte-compile-dynamic-docstrings t
  "If non-nil, compile doc strings for lazy access.
We bury the doc strings of functions and variables inside comments in
the file, and bring them into core only when they are actually needed.

When this option is true, if you load the compiled file and then move it,
you won't be able to find the documentation of anything in that file.

To disable this option for a certain file, make it a file-local variable

  :group 'bytecomp
  :type 'boolean)
;;;###autoload(put 'byte-compile-dynamic-docstrings 'safe-local-variable 'booleanp)

(defcustom byte-optimize-log nil
  "If true, the byte-compiler will log its optimizations into *Compile-Log*.
If this is 'source, then only source-level optimizations will be logged.
If it is 'byte, then only byte-level optimizations will be logged."
  :group 'bytecomp
  :type '(choice (const :tag "none" nil)
		 (const :tag "all" t)
		 (const :tag "source-level" source)
		 (const :tag "byte-level" byte)))

(defcustom byte-compile-error-on-warn nil
  "If true, the byte-compiler reports warnings with `error'."
  :group 'bytecomp
  :type 'boolean)

(defconst byte-compile-warning-types
  '(redefine callargs free-vars unresolved
	     obsolete noruntime cl-functions interactive-only
	     make-local mapcar)
  "The list of warning types used when `byte-compile-warnings' is t.")
(defcustom byte-compile-warnings t
  "List of warnings that the byte-compiler should issue (t for all).

Elements of the list may be:

  free-vars   references to variables not in the current lexical scope.
  unresolved  calls to unknown functions.

(defvar byte-compile-not-obsolete-var nil
  "If non-nil, this is a variable that shouldn't be reported as obsolete.")

(defcustom byte-compile-generate-call-tree nil
  "Non-nil means collect call-graph information when compiling.
This records which functions were called and from where.
If the value is t, compilation displays the call graph when it finishes.
If the value is neither t nor nil, compilation asks you whether to display
the graph.

invoked interactively are excluded from this list."
  :group 'bytecomp
  :type '(choice (const :tag "Yes" t) (const :tag "No" nil)
		 (other :tag "Ask" lambda)))

(defvar byte-compile-call-tree nil
  "Alist of functions and their call tree.
Each element looks like

  \(FUNCTION CALLERS CALLS\)

where CALLERS is a list of functions that call FUNCTION, and CALLS
is a list of functions for which calls were generated while compiling
FUNCTION.")

(defcustom byte-compile-call-tree-sort 'name
  "If non-nil, sort the call tree.
The values `name', `callers', `calls', `calls+callers'
specify different fields to sort on."
  :group 'bytecomp
  :type '(choice (const name) (const callers) (const calls)
		 (const calls+callers) (const nil)))

;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2008-02/msg00134.html
;;;###autoload
(defun byte-recompile-directory (bytecomp-directory &optional bytecomp-arg
                                                    bytecomp-force)
  "Recompile every `.el' file in BYTECOMP-DIRECTORY that needs recompilation.
This happens when a `.elc' file exists but is older than the `.el' file.
Files in subdirectories of BYTECOMP-DIRECTORY are processed also.

If the `.elc' file does not exist, normally this function *does not*
compile the corresponding `.el' file.  However, if the prefix argument
BYTECOMP-ARG is 0, that means do compile all those files.  A nonzero

	       (if (> skip-count 0) (format ", %d skipped" skip-count) "")
	       (if (> dir-count 1)
                   (format " in %d directories" dir-count) "")))))

(defvar no-byte-compile nil
  "Non-nil to prevent byte-compiling of Emacs Lisp code.
This is normally set in local file variables at the end of the elisp file:

;; Local Variables:\n;; no-byte-compile: t\n;; End: ")
;;;###autoload(put 'no-byte-compile 'safe-local-variable 'booleanp)

;;; compiling a single function
;;;###autoload
(defun compile-defun (&optional arg)
  "Compile and evaluate the current top-level form.
Print the result in the echo area.
With argument ARG, insert value in current buffer after the form."
  (interactive "P")
  (save-excursion
    (end-of-defun)
    (beginning-of-defun)
    (let* ((byte-compile-current-file nil)

  "Print a form with a doc string.  INFO is (prefix doc-index postfix).
If PREFACE and NAME are non-nil, print them too,
before INFO and the FORM but after the doc string itself.
If SPECINDEX is non-nil, it is the index in FORM
of the function bytecode string.  In that case,
we output that argument and the following argument
\(the constants vector) together, for lazy loading.
QUOTED says that we have to put a quote before the
list that represents a doc string reference.
`autoload' and `custom-declare-variable' need that."
  ;; We need to examine byte-compile-dynamic-docstrings
  ;; in the input buffer (now current), not in the output buffer.

    (cond
     ((= 1 len) (byte-compile-constant 0))
     ((= 2 len)
      (byte-compile-form (cadr form))
      (byte-compile-out 'byte-negate 0))
     ((= 3 len)
      (byte-compile-form (nth 1 form))
      (byte-compile-form (nth 2 form))
      (byte-compile-out 'byte-diff 0))
     ;; Don't use binary operations for > 2 operands, as that may
     ;; cause overflow/truncation in float operations.