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, in the same form as in defun (including the parentheses); or it 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.

View in manual

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-2024 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, in the same form as
in `defun' (including the parentheses); or it 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-macroexpand-declare-function' does
  ;; the work.
  nil)