Function: declare-function

declare-function is a macro defined in subr.el.gz.

Signature

(declare-function FN FILE &optional ARGLIST FILEONLY)

Documentation

Tell the byte-compiler that function FN is defined, in FILE.

The FILE argument is not used by the byte-compiler, but by the check-declare package, which checks that FILE contains a definition for FN. (FILE can be nil, and that disables this check.)

FILE can be either a Lisp file (in which case the ".el" extension is optional), or a C file. C files are expanded relative to the Emacs "src/" directory. Lisp files are searched for using locate-library, and if that fails they are expanded relative to the location of the file containing the declaration. A FILE with an "ext:" prefix is an external file. check-declare will check such files if they are found, and skip them without error if they are not.

Optional ARGLIST specifies FN's arguments, or is t to not specify FN's arguments. An omitted ARGLIST defaults to t, not nil: a nil ARGLIST specifies an empty argument list, and an explicit t ARGLIST is a placeholder that allows supplying a later arg.

Optional FILEONLY non-nil means that check-declare will check only that FILE exists, not that it defines FN. This is intended for function definitions that check-declare does not recognize, e.g., defstruct.

Note that for the purposes of check-declare, this statement must be the first non-whitespace on a line.

For more information, see Info node (elisp)Declaring Functions.

Probably introduced at or before Emacs version 23.1.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
;;; subr.el --- basic lisp subroutines for Emacs  -*- lexical-binding:t -*-

;; Copyright (C) 1985-1986, 1992, 1994-1995, 1999-2022 Free Software
;; Foundation, Inc.

;; Maintainer: emacs-devel@gnu.org
;; Keywords: internal
;; Package: emacs

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs 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.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.

;;; Commentary:

;;; Code:

;; declare-function's args use &rest, not &optional, for compatibility
;; with byte-compile-macroexpand-declare-function.

(defmacro declare-function (_fn _file &rest _args)
  "Tell the byte-compiler that function FN is defined, in FILE.
The FILE argument is not used by the byte-compiler, but by the
`check-declare' package, which checks that FILE contains a
definition for FN.  (FILE can be nil, and that disables this
check.)

FILE can be either a Lisp file (in which case the \".el\"
extension is optional), or a C file.  C files are expanded
relative to the Emacs \"src/\" directory.  Lisp files are
searched for using `locate-library', and if that fails they are
expanded relative to the location of the file containing the
declaration.  A FILE with an \"ext:\" prefix is an external file.
`check-declare' will check such files if they are found, and skip
them without error if they are not.

Optional ARGLIST specifies FN's arguments, or is t to not specify
FN's arguments.  An omitted ARGLIST defaults to t, not nil: a nil
ARGLIST specifies an empty argument list, and an explicit t
ARGLIST is a placeholder that allows supplying a later arg.

Optional FILEONLY non-nil means that `check-declare' will check
only that FILE exists, not that it defines FN.  This is intended
for function definitions that `check-declare' does not recognize,
e.g., `defstruct'.

Note that for the purposes of `check-declare', this statement
must be the first non-whitespace on a line.

For more information, see Info node `(elisp)Declaring Functions'."
  (declare (advertised-calling-convention
	    (fn file &optional arglist fileonly) nil))
  ;; Does nothing - byte-compile-declare-function does the work.
  nil)