Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Open sidebar
emacs
emacs
Commits
a0925923
Commit
a0925923
authored
Nov 24, 2007
by
Richard M. Stallman
Browse files
(Declaring Functions): Clarify previous change.
parent
fc37ae72
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
56 additions
and
34 deletions
+56
-34
doc/lispref/ChangeLog
doc/lispref/ChangeLog
+6
-0
doc/lispref/functions.texi
doc/lispref/functions.texi
+50
-34
No files found.
doc/lispref/ChangeLog
View file @
a0925923
2007-11-24 Richard Stallman <rms@gnu.org>
* functions.texi (Declaring Functions): Clarify previous change.
* compile.texi (Compiler Errors): Clarify previous change.
2007-11-24 Glenn Morris <rgm@gnu.org>
* functions.texi (Declaring Functions): New section.
...
...
doc/lispref/functions.texi
View file @
a0925923
...
...
@@ -1228,50 +1228,66 @@ following the definition, just like macros.
@cindex function declaration
@cindex declaring functions
Byte-compiling a file often produces warnings about functions that
ar
e
@samp{not known to be defined}
(@pxref{Compiler Errors}).
The compiler
i
s technically correct, but the code is usually such that when it
actually runs,
the f
unction @emph{will} be defined. For example,
byte-compiling @file{fortran.el} used to warn:
Byte-compiling a file often produces warnings about functions that
th
e
compiler doesn't know about
(@pxref{Compiler Errors}).
Sometimes this
i
ndicates a real problem, but usually the functions in question are
defined in o
the
r
f
iles which would be loaded if that code is run. For
example,
byte-compiling @file{fortran.el} used to warn:
@example
@
small
example
In end of data:
fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
to be defined.
@end example
fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known to be defined.
@end smallexample
But @code{gud-find-c-expr} is only used in the function that Fortran
mode uses for the local value of @code{gud-find-expr-function}. 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.
In fact, @code{gud-find-c-expr} is only used in the function that
Fortran mode uses for the local value of
@code{gud-find-expr-function}, which is a callback from GUD; if it is
called, the GUD functions will be loaded. When you know that such a
warning does not indicate a real problem, it is good to suppress the
warning. That makes new warnings which might mean real problems more
visible. You do that with @code{declare-function}.
All you need to do is add a @code{declare-function} statement before the
first use of the function in question:
@example
@
small
example
(declare-function gud-find-c-expr "gud.el" nil)
@end example
@end
smalll
example
This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
`.el' can be omitted). The file is searched for using
@code{locate-library}, and failing that it is expanded relative to the
file containing the @code{declare-function} statement. Functions
defined in C can also be declared - @file{.c} files are expanded
relative to the Emacs @file{src/} directory.
The optional third argument specifies the argument list of
@code{gud-find-c-expr}. In this case, it takes no arguments (@code{nil}
is different from not specifying a value). In other cases, this might
be something like @code{(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 @code{check-declare-file} and
@code{check-declare-directory} check that all the
@code{declare-function} statements in a file or directory are true
(i.e. that the functions @emph{are} defined in the specified files, and
have matching argument lists, if these were specified).
@samp{.el} can be omitted). The compiler takes for granted that that file
really defines the function, and does not check.
The optional third argument specifies the argument list of
@code{gud-find-c-expr}. In this case, it takes no arguments
(@code{nil} is different from not specifying a value). In other
cases, this might be something like @code{(file &optional overwrite)}.
You don't have to specify the argument list, but if you do the
byte compiler can check that the calls match the declaration.
@defmac declare-function function file arglist
Tell the byte compiler to assume that @var{function} is defined, with
arguments @var{arglist}, and that the definition should come from
the file @var{file}.
@end defmac
To verify that these functions really are declared where
@code{declare-function} says they are, use @code{check-declare-file}
to check all @code{declare-function} calls in one source file, or use
@code{check-declare-directory} check all the files in and under a
certain directory.
These commands find the file that ought to contain a function's
definition using @code{locate-library}; if that finds no file, they
expand the definition file name relative to the directory of the file
that contains the @code{declare-function} call.
You can also say that a function is defined by C code by specifying
a file name ending in @samp{.c}. @code{check-declare-file} looks for
these files in the C source code directory. This is useful only when
you call a function that is defined only on certain systems. Most
of the primitive functions of Emacs are always defined so they will
never give you a warning.
@node Function Safety
@section Determining whether a Function is Safe to Call
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment