byte-compiler warnings about undefined functions can now be silenced

[Glenn Morris <rgm@gnu.org>]

Dan Nicolaescu wrote:

> Could you please post a message to emacs-devel about how to use this
> feature?
> 
> An example with the warning that is currently produced by the byte
> compiler and how to use this to get rid of it.

As requested...


When bootstrapping, there are lots of messages about functions that
are "not known to be defined". The compiler is technically correct, but
the code is usually such that when it actually runs, the function will
be defined.

For example, byte-compiling fortran.el used to warn:

  In end of data:
  fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
    to be defined.

But gud-find-c-expr was only used in the function that fortran mode
uses for the local value of `gud-find-expr-function'. So this would
only ever be called from gud, so the warning can safely be suppressed.
It's nice to do this, so that real warnings are more visible.

All you need to do is add a `declare-function' statement before the
first use of the function in question:

  (declare-function gud-find-c-expr "gud.el" nil)

This says that gud-find-c-expr is defined in "gud.el" (the `.el' can
be omitted). The file path is either absolute, or relative to the one
with the declare-function statement (e.g. "../files.el").

The 3rd argument is optional, and specifies the argument list of
gud-find-c-expr. In this case, it takes no arguments (`nil' is
different from not specifying a value). In other cases, this might be
something like (file &optional overwrite). You don't have to specify
the argument list, but if you do the byte-compiler will check that the
calls match the declaration.


The functions `check-declare-file' and `check-declare-directory' will
check that all the declare-function statements in a file or directory
are true (i.e. that the functions are defined in the specified files,
and have the same argument lists, if specified). `make check-declare'
will check all of leim/ and lisp/.

> Also, IMO it would be good to add declare-function to the 22.2
> branch, (even as an empty stub if it's considered too risky), this
> should help with compatibility between the 2 branches.

I don't have much of an opinion. It could easily be added as a no-op
(it's almost a no-op now...).