1xref(3) Erlang Module Definition xref(3)
2
6 xref - A Cross Reference Tool for analyzing dependencies between func‐
7 tions, modules, applications and releases.
8
10 Xref is a cross reference tool that can be used for finding dependen‐
11 cies between functions, modules, applications and releases.
12 Calls between functions are either local calls like f(), or external
14 calls like m:f(). Module data, which are extracted from BEAM files,
15 include local functions, exported functions, local calls and external
16 calls. By default, calls to built-in functions () are ignored, but if
17 the option builtins, accepted by some of this module's functions, is
18 set to true, calls to BIFs are included as well. It is the analyzing
19 OTP version that decides what functions are BIFs. Functional objects
20 are assumed to be called where they are created (and nowhere else).
21 Unresolved calls are calls to apply or spawn with variable module,
22 variable function, or variable arguments. Examples are M:F(a), apply(M,
23 f, [a]), and spawn(m, f(), Args). Unresolved calls are represented by
24 calls where variable modules have been replaced with the atom
25 '$M_EXPR', variable functions have been replaced with the atom
26 '$F_EXPR', and variable number of arguments have been replaced with the
27 number -1. The above mentioned examples are represented by calls to
28 '$M_EXPR':'$F_EXPR'/1, '$M_EXPR':f/1, and m:'$F_EXPR'/-1. The unre‐
29 solved calls are a subset of the external calls.
30 Warning:
32 Unresolved calls make module data incomplete, which implies that the
33 results of analyses may be invalid.
34 Applications are collections of modules. The modules' BEAM files are
37 located in the ebin subdirectory of the application directory. The name
38 of the application directory determines the name and version of the
39 application. Releases are collections of applications located in the
40 lib subdirectory of the release directory. There is more to read about
41 applications and releases in the Design Principles book.
42 Xref servers are identified by names, supplied when creating new
44 servers. Each Xref server holds a set of releases, a set of applica‐
45 tions, and a set of modules with module data. Xref servers are indepen‐
46 dent of each other, and all analyses are evaluated in the context of
47 one single Xref server (exceptions are the functions m/1 and d/1 which
48 do not use servers at all). The mode of an Xref server determines what
49 module data are extracted from BEAM files as modules are added to the
50 server. Starting with R7, BEAM files compiled with the option
51 debug_info contain so called debug information, which is an abstract
52 representation of the code. In functions mode, which is the default
53 mode, function calls and line numbers are extracted from debug informa‐
54 tion. In modules mode, debug information is ignored if present, but
55 dependencies between modules are extracted from other parts of the BEAM
56 files. The modules mode is significantly less time and space consuming
57 than the functions mode, but the analyses that can be done are limited.
58 An analyzed module is a module that has been added to an Xref server
60 together with its module data. A library module is a module located in
61 some directory mentioned in the library path. A library module is said
62 to be used if some of its exported functions are used by some analyzed
63 module. An unknown module is a module that is neither an analyzed mod‐
64 ule nor a library module, but whose exported functions are used by some
65 analyzed module. An unknown function is a used function that is neither
66 local or exported by any analyzed module nor exported by any library
67 module. An undefined function is an externally used function that is
68 not exported by any analyzed module or library module. With this
69 notion, a local function can be an undefined function, namely if it is
70 externally used from some module. All unknown functions are also unde‐
71 fined functions; there is a figure in the User's Guide that illustrates
72 this relationship.
73 Starting with R9C, the module attribute tag deprecated can be used to
75 inform Xref about deprecated functions and optionally when functions
76 are planned to be removed. A few examples show the idea:
77 -deprecated({f,1}).:
79 The exported function f/1 is deprecated. Nothing is said whether
80 f/1 will be removed or not.
81 -deprecated({f,'_'}).:
83 All exported functions f/0, f/1 and so on are deprecated.
84 -deprecated(module).:
86 All exported functions in the module are deprecated. Equivalent to
87 -deprecated({'_','_'})..
88 -deprecated([{g,1,next_version}]).:
90 The function g/1 is deprecated and will be removed in next version.
91 -deprecated([{g,2,next_major_release}]).:
93 The function g/2 is deprecated and will be removed in next major
94 release.
95 -deprecated([{g,3,eventually}]).:
97 The function g/3 is deprecated and will eventually be removed.
98 -deprecated({'_','_',eventually}).:
100 All exported functions in the module are deprecated and will even‐
101 tually be removed.
102 Before any analysis can take place, module data must be set up. For
104 instance, the cross reference and the unknown functions are computed
105 when all module data are known. The functions that need complete data
106 (analyze, q, variables) take care of setting up data automatically.
107 Module data need to be set up (again) after calls to any of the add,
108 replace, remove, set_library_path or update functions.
109 The result of setting up module data is the Call Graph. A (directed)
111 graph consists of a set of vertices and a set of (directed) edges. The
112 edges represent calls (From, To) between functions, modules, applica‐
113 tions or releases. From is said to call To, and To is said to be used
114 by From. The vertices of the Call Graph are the functions of all module
115 data: local and exported functions of analyzed modules; used BIFs; used
116 exported functions of library modules; and unknown functions. The func‐
117 tions module_info/0,1 added by the compiler are included among the
118 exported functions, but only when called from some module. The edges
119 are the function calls of all module data. A consequence of the edges
120 being a set is that there is only one edge if a function is locally or
121 externally used several times on one and the same line of code.
122 The Call Graph is represented by Erlang terms (the sets are lists),
124 which is suitable for many analyses. But for analyses that look at
125 chains of calls, a list representation is much too slow. Instead the
126 representation offered by the digraph module is used. The translation
127 of the list representation of the Call Graph - or a subgraph thereof -
128 to the digraph representation does not come for free, so the language
129 used for expressing queries to be described below has a special opera‐
130 tor for this task and a possibility to save the digraph representation
131 for subsequent analyses.
132 In addition to the Call Graph there is a graph called the Inter Call
134 Graph. This is a graph of calls (From, To) such that there is a chain
135 of calls from From to To in the Call Graph, and every From and To is an
136 exported function or an unused local function. The vertices are the
137 same as for the Call Graph.
138 Calls between modules, applications and releases are also directed
140 graphs. The types of the vertices and edges of these graphs are (rang‐
141 ing from the most special to the most general): Fun for functions; Mod
142 for modules; App for applications; and Rel for releases. The following
143 paragraphs will describe the different constructs of the language used
144 for selecting and analyzing parts of the graphs, beginning with the
145 constants:
146 * Expression ::= Constants
148 * Constants ::= Consts | Consts : Type | RegExpr
150 * Consts ::= Constant | [Constant, ...] | {Constant, ...}
152 * Constant ::= Call | Const
154 * Call ::= FunSpec -> FunSpec | {MFA, MFA} | AtomConst -> AtomConst |
156 {AtomConst, AtomConst}
157 * Const ::= AtomConst | FunSpec | MFA
159 * AtomConst ::= Application | Module | Release
161 * FunSpec ::= Module : Function / Arity
163 * MFA ::= {Module, Function, Arity}
165 * RegExpr ::= RegString : Type | RegFunc | RegFunc : Type
167 * RegFunc ::= RegModule : RegFunction / RegArity
169 * RegModule ::= RegAtom
171 * RegFunction ::= RegAtom
173 * RegArity ::= RegString | Number | _ | -1
175 * RegAtom ::= RegString | Atom | _
177 * RegString ::= - a regular expression, as described in the re mod‐
179 ule, enclosed in double quotes -
180 * Type ::= Fun | Mod | App | Rel
182 * Function ::= Atom
184 * Application ::= Atom
186 * Module ::= Atom
188 * Release ::= Atom
190 * Arity ::= Number | -1
192 * Atom ::= - same as Erlang atoms -
194 * Number ::= - same as non-negative Erlang integers -
196 Examples of constants are: kernel, kernel->stdlib, [kernel, sasl], [pg
198 -> mnesia, {tv, mnesia}] : Mod. It is an error if an instance of Const
199 does not match any vertex of any graph. If there are more than one ver‐
200 tex matching an untyped instance of AtomConst, then the one of the most
201 general type is chosen. A list of constants is interpreted as a set of
202 constants, all of the same type. A tuple of constants constitute a
203 chain of calls (which may, but does not have to, correspond to an
204 actual chain of calls of some graph). Assigning a type to a list or
205 tuple of Constant is equivalent to assigning the type to each Constant.
206 Regular expressions are used as a means to select some of the vertices
208 of a graph. A RegExpr consisting of a RegString and a type - an example
209 is "xref_.*" : Mod - is interpreted as those modules (or applications
210 or releases, depending on the type) that match the expression. Simi‐
211 larly, a RegFunc is interpreted as those vertices of the Call Graph
212 that match the expression. An example is "xref_.*":"add_.*"/"(2|3)",
213 which matches all add functions of arity two or three of any of the
214 xref modules. Another example, one that matches all functions of arity
215 10 or more: _:_/"[1-9].+". Here _ is an abbreviation for ".*", that is,
216 the regular expression that matches anything.
217 The syntax of variables is simple:
219 * Expression ::= Variable
221 * Variable ::= - same as Erlang variables -
223 There are two kinds of variables: predefined variables and user vari‐
225 ables. Predefined variables hold set up module data, and cannot be
226 assigned to but only used in queries. User variables on the other hand
227 can be assigned to, and are typically used for temporary results while
228 evaluating a query, and for keeping results of queries for use in sub‐
229 sequent queries. The predefined variables are (variables marked with
230 (*) are available in functions mode only):
231 E:
233 Call Graph Edges (*).
234 V:
236 Call Graph Vertices (*).
237 M:
239 Modules. All modules: analyzed modules, used library modules, and
240 unknown modules.
241 A:
243 Applications.
244 R:
246 Releases.
247 ME:
249 Module Edges. All module calls.
250 AE:
252 Application Edges. All application calls.
253 RE:
255 Release Edges. All release calls.
256 L:
258 Local Functions (*). All local functions of analyzed modules.
259 X:
261 Exported Functions. All exported functions of analyzed modules and
262 all used exported functions of library modules.
263 F:
265 Functions (*).
266 B:
268 Used BIFs. B is empty if builtins is false for all analyzed mod‐
269 ules.
270 U:
272 Unknown Functions.
273 UU:
275 Unused Functions (*). All local and exported functions of analyzed
276 modules that have not been used.
277 XU:
279 Externally Used Functions. Functions of all modules - including
280 local functions - that have been used in some external call.
281 LU:
283 Locally Used Functions (*). Functions of all modules that have been
284 used in some local call.
285 OL:
287 Functions with an attribute tag on_load (*).
288 LC:
290 Local Calls (*).
291 XC:
293 External Calls (*).
294 AM:
296 Analyzed Modules.
297 UM:
299 Unknown Modules.
300 LM:
302 Used Library Modules.
303 UC:
305 Unresolved Calls. Empty in modules mode.
306 EE:
308 Inter Call Graph Edges (*).
309 DF:
311 Deprecated Functions. All deprecated exported functions and all
312 used deprecated BIFs.
313 DF_1:
315 Deprecated Functions. All deprecated functions to be removed in
316 next version.
317 DF_2:
319 Deprecated Functions. All deprecated functions to be removed in
320 next version or next major release.
321 DF_3:
323 Deprecated Functions. All deprecated functions to be removed in
324 next version, next major release, or later.
325 These are a few facts about the predefined variables (the set operators
327 + (union) and - (difference) as well as the cast operator (Type) are
328 described below):
329 * F is equal to L + X.
331 * V is equal to X + L + B + U, where X, L, B and U are pairwise dis‐
333 joint (that is, have no elements in common).
334 * UU is equal to V - (XU + LU), where LU and XU may have elements in
336 common. Put in another way:
337 * V is equal to UU + XU + LU.
339 * OL is a subset of F.
341 * E is equal to LC + XC. Note that LC and XC may have elements in
343 common, namely if some function is locally and externally used from
344 one and the same function.
345 * U is a subset of XU.
347 * B is a subset of XU.
349 * LU is equal to range LC.
351 * XU is equal to range XC.
353 * LU is a subset of F.
355 * UU is a subset of F.
357 * range UC is a subset of U.
359 * M is equal to AM + LM + UM, where AM, LM and UM are pairwise dis‐
361 joint.
362 * ME is equal to (Mod) E.
364 * AE is equal to (App) E.
366 * RE is equal to (Rel) E.
368 * (Mod) V is a subset of M. Equality holds if all analyzed modules
370 have some local, exported, or unknown function.
371 * (App) M is a subset of A. Equality holds if all applications have
373 some module.
374 * (Rel) A is a subset of R. Equality holds if all releases have some
376 application.
377 * DF_1 is a subset of DF_2.
379 * DF_2 is a subset of DF_3.
381 * DF_3 is a subset of DF.
383 * DF is a subset of X + B.
385 An important notion is that of conversion of expressions. The syntax of
387 a cast expression is:
388 * Expression ::= ( Type ) Expression
390 The interpretation of the cast operator depends on the named type Type,
392 the type of Expression, and the structure of the elements of the inter‐
393 pretation of Expression. If the named type is equal to the expression
394 type, no conversion is done. Otherwise, the conversion is done one step
395 at a time; (Fun) (App) RE, for instance, is equivalent to (Fun) (Mod)
396 (App) RE. Now assume that the interpretation of Expression is a set of
397 constants (functions, modules, applications or releases). If the named
398 type is more general than the expression type, say Mod and Fun respec‐
399 tively, then the interpretation of the cast expression is the set of
400 modules that have at least one of their functions mentioned in the
401 interpretation of the expression. If the named type is more special
402 than the expression type, say Fun and Mod, then the interpretation is
403 the set of all the functions of the modules (in modules mode, the con‐
404 version is partial since the local functions are not known). The con‐
405 versions to and from applications and releases work analogously. For
406 instance, (App) "xref_.*" : Mod returns all applications containing at
407 least one module such that xref_ is a prefix of the module name.
408 Now assume that the interpretation of Expression is a set of calls. If
410 the named type is more general than the expression type, say Mod and
411 Fun respectively, then the interpretation of the cast expression is the
412 set of calls (M1, M2) such that the interpretation of the expression
413 contains a call from some function of M1 to some function of M2. If the
414 named type is more special than the expression type, say Fun and Mod,
415 then the interpretation is the set of all function calls (F1, F2) such
416 that the interpretation of the expression contains a call (M1, M2) and
417 F1 is a function of M1 and F2 is a function of M2 (in modules mode,
418 there are no functions calls, so a cast to Fun always yields an empty
419 set). Again, the conversions to and from applications and releases work
420 analogously.
421 The interpretation of constants and variables are sets, and those sets
423 can be used as the basis for forming new sets by the application of set
424 operators. The syntax:
425 * Expression ::= Expression BinarySetOp Expression
427 * BinarySetOp ::= + | * | -
429 +, * and - are interpreted as union, intersection and difference
431 respectively: the union of two sets contains the elements of both sets;
432 the intersection of two sets contains the elements common to both sets;
433 and the difference of two sets contains the elements of the first set
434 that are not members of the second set. The elements of the two sets
435 must be of the same structure; for instance, a function call cannot be
436 combined with a function. But if a cast operator can make the elements
437 compatible, then the more general elements are converted to the less
438 general element type. For instance, M + F is equivalent to (Fun) M + F,
439 and E - AE is equivalent to E - (Fun) AE. One more example: X * xref :
440 Mod is interpreted as the set of functions exported by the module xref;
441 xref : Mod is converted to the more special type of X (Fun, that is)
442 yielding all functions of xref, and the intersection with X (all func‐
443 tions exported by analyzed modules and library modules) is interpreted
444 as those functions that are exported by some module and functions of
445 xref.
446 There are also unary set operators:
448 * Expression ::= UnarySetOp Expression
450 * UnarySetOp ::= domain | range | strict
452 Recall that a call is a pair (From, To). domain applied to a set of
454 calls is interpreted as the set of all vertices From, and range as the
455 set of all vertices To. The interpretation of the strict operator is
456 the operand with all calls on the form (A, A) removed.
457 The interpretation of the restriction operators is a subset of the
459 first operand, a set of calls. The second operand, a set of vertices,
460 is converted to the type of the first operand. The syntax of the
461 restriction operators:
462 * Expression ::= Expression RestrOp Expression
464 * RestrOp ::= |
466 * RestrOp ::= ||
468 * RestrOp ::= |||
470 The interpretation in some detail for the three operators:
472 |:
474 The subset of calls from any of the vertices.
475 ||:
477 The subset of calls to any of the vertices.
478 |||:
480 The subset of calls to and from any of the vertices. For all sets
481 of calls CS and all sets of vertices VS, CS ||| VS is equivalent
482 to CS | VS * CS || VS.
483 Two functions (modules, applications, releases) belong to the same
485 strongly connected component if they call each other (in)directly. The
486 interpretation of the components operator is the set of strongly con‐
487 nected components of a set of calls. The condensation of a set of calls
488 is a new set of calls between the strongly connected components such
489 that there is an edge between two components if there is some constant
490 of the first component that calls some constant of the second compo‐
491 nent.
492 The interpretation of the of operator is a chain of calls of the second
494 operand (a set of calls) that passes throw all of the vertices of the
495 first operand (a tuple of constants), in the given order. The second
496 operand is converted to the type of the first operand. For instance,
497 the of operator can be used for finding out whether a function calls
498 another function indirectly, and the chain of calls demonstrates how.
499 The syntax of the graph analyzing operators:
500 * Expression ::= Expression BinaryGraphOp Expression
502 * Expression ::= UnaryGraphOp Expression
504 * UnaryGraphOp ::= components | condensation
506 * BinaryGraphOp ::= of
508 As was mentioned before, the graph analyses operate on the digraph rep‐
510 resentation of graphs. By default, the digraph representation is cre‐
511 ated when needed (and deleted when no longer used), but it can also be
512 created explicitly by use of the closure operator:
513 * Expression ::= ClosureOp Expression
515 * ClosureOp ::= closure
517 The interpretation of the closure operator is the transitive closure of
519 the operand.
520 The restriction operators are defined for closures as well; closure E |
522 xref : Mod is interpreted as the direct or indirect function calls from
523 the xref module, while the interpretation of E | xref : Mod is the set
524 of direct calls from xref. If some graph is to be used in several graph
525 analyses, it saves time to assign the digraph representation of the
526 graph to a user variable, and then make sure that every graph analysis
527 operates on that variable instead of the list representation of the
528 graph.
529 The lines where functions are defined (more precisely: where the first
531 clause begins) and the lines where functions are used are available in
532 functions mode. The line numbers refer to the files where the functions
533 are defined. This holds also for files included with the -include and
534 -include_lib directives, which may result in functions defined appar‐
535 ently in the same line. The line operators are used for assigning line
536 numbers to functions and for assigning sets of line numbers to function
537 calls. The syntax is similar to the one of the cast operator:
538 * Expression ::= ( LineOp) Expression
540 * Expression ::= ( XLineOp) Expression
542 * LineOp ::= Lin | ELin | LLin | XLin
544 * XLineOp ::= XXL
546 The interpretation of the Lin operator applied to a set of functions
548 assigns to each function the line number where the function is defined.
549 Unknown functions and functions of library modules are assigned the
550 number 0.
551 The interpretation of some LineOp operator applied to a set of function
553 calls assigns to each call the set of line numbers where the first
554 function calls the second function. Not all calls are assigned line
555 numbers by all operators:
556 * the Lin operator is defined for Call Graph Edges;
558 * the LLin operator is defined for Local Calls.
560 * the XLin operator is defined for External Calls.
562 * the ELin operator is defined for Inter Call Graph Edges.
564 The Lin (LLin, XLin) operator assigns the lines where calls (local
566 calls, external calls) are made. The ELin operator assigns to each call
567 (From, To), for which it is defined, every line L such that there is a
568 chain of calls from From to To beginning with a call on line L.
569 The XXL operator is defined for the interpretation of any of the LineOp
571 operators applied to a set of function calls. The result is that of
572 replacing the function call with a line numbered function call, that
573 is, each of the two functions of the call is replaced by a pair of the
574 function and the line where the function is defined. The effect of the
575 XXL operator can be undone by the LineOp operators. For instance, (Lin)
576 (XXL) (Lin) E is equivalent to (Lin) E.
577 The +, -, * and # operators are defined for line number expressions,
579 provided the operands are compatible. The LineOp operators are also
580 defined for modules, applications, and releases; the operand is implic‐
581 itly converted to functions. Similarly, the cast operator is defined
582 for the interpretation of the LineOp operators.
583 The interpretation of the counting operator is the number of elements
585 of a set. The operator is undefined for closures. The +, - and * opera‐
586 tors are interpreted as the obvious arithmetical operators when applied
587 to numbers. The syntax of the counting operator:
588 * Expression ::= CountOp Expression
590 * CountOp ::= #
592 All binary operators are left associative; for instance, A | B || C is
594 equivalent to (A | B) || C. The following is a list of all operators,
595 in increasing order of precedence:
596 * +, -
598 * *
600 * #
602 * |, ||, |||
604 * of
606 * (Type)
608 * closure, components, condensation, domain, range, strict
610 Parentheses are used for grouping, either to make an expression more
612 readable or to override the default precedence of operators:
613 * Expression ::= ( Expression )
615 A query is a non-empty sequence of statements. A statement is either an
617 assignment of a user variable or an expression. The value of an assign‐
618 ment is the value of the right hand side expression. It makes no sense
619 to put a plain expression anywhere else but last in queries. The syntax
620 of queries is summarized by these productions:
621 * Query ::= Statement, ...
623 * Statement ::= Assignment | Expression
625 * Assignment ::= Variable := Expression | Variable = Expression
627 A variable cannot be assigned a new value unless first removed. Vari‐
629 ables assigned to by the = operator are removed at the end of the
630 query, while variables assigned to by the := operator can only be
631 removed by calls to forget. There are no user variables when module
632 data need to be set up again; if any of the functions that make it nec‐
633 essary to set up module data again is called, all user variables are
634 forgotten.
635 Types
637 application() = atom()
639 arity() = int() | -1
640 bool() = true | false
641 call() = {atom(), atom()} | funcall()
642 constant() = mfa() | module() | application() | release()
643 directory() = string()
644 file() = string()
645 funcall() = {mfa(), mfa()}
646 function() = atom()
647 int() = integer() >= 0
648 library() = atom()
649 library_path() = path() | code_path
650 mfa() = {module(), function(), arity()}
651 mode() = functions | modules
652 module() = atom()
653 release() = atom()
654 string_position() = int() | at_end
655 variable() = atom()
656 xref() = atom() | pid()
657
659 add_application(Xref, Directory [, Options]) -> {ok, application()} |
660 Error
661 Types:
663 Directory = directory()
665 Error = {error, module(), Reason}
666 Options = [Option] | Option
667 Option = {builtins, bool()} | {name, application()} | {ver‐
668 bose, bool()} | {warnings, bool()}
669 Reason = {application_clash, {application(), directory(),
670 directory()}} | {file_error, file(), error()} |
671 {invalid_filename, term()} | {invalid_options, term()} | -
672 see also add_directory -
673 Xref = xref()
674 Adds an application, the modules of the application and module
676 data of the modules to an Xref server. The modules will be mem‐
677 bers of the application. The default is to use the base name of
678 the directory with the version removed as application name, but
679 this can be overridden by the name option. Returns the name of
680 the application.
681 If the given directory has a subdirectory named ebin, modules
683 (BEAM files) are searched for in that directory, otherwise mod‐
684 ules are searched for in the given directory.
685 If the mode of the Xref server is functions, BEAM files that
687 contain no debug information are ignored.
688 add_directory(Xref, Directory [, Options]) -> {ok, Modules} | Error
690 Types:
692 Directory = directory()
694 Error = {error, module(), Reason}
695 Modules = [module()]
696 Options = [Option] | Option
697 Option = {builtins, bool()} | {recurse, bool()} | {verbose,
698 bool()} | {warnings, bool()}
699 Reason = {file_error, file(), error()} | {invalid_filename,
700 term()} | {invalid_options, term()} | {unrecognized_file,
701 file()} | - error from beam_lib:chunks/2 -
702 Xref = xref()
703 Adds the modules found in the given directory and the modules'
705 data to an Xref server. The default is not to examine subdirec‐
706 tories, but if the option recurse has the value true, modules
707 are searched for in subdirectories on all levels as well as in
708 the given directory. Returns a sorted list of the names of the
709 added modules.
710 The modules added will not be members of any applications.
712 If the mode of the Xref server is functions, BEAM files that
714 contain no debug information are ignored.
715 add_module(Xref, File [, Options]) -> {ok, module()} | Error
717 Types:
719 Error = {error, module(), Reason}
721 File = file()
722 Options = [Option] | Option
723 Option = {builtins, bool()} | {verbose, bool()} | {warnings,
724 bool()}
725 Reason = {file_error, file(), error()} | {invalid_filename,
726 term()} | {invalid_options, term()} | {module_clash, {mod‐
727 ule(), file(), file()}} | {no_debug_info, file()} | - error
728 from beam_lib:chunks/2 -
729 Xref = xref()
730 Adds a module and its module data to an Xref server. The module
732 will not be member of any application. Returns the name of the
733 module.
734 If the mode of the Xref server is functions, and the BEAM file
736 contains no debug information, the error message no_debug_info
737 is returned.
738 add_release(Xref, Directory [, Options]) -> {ok, release()} | Error
740 Types:
742 Directory = directory()
744 Error = {error, module(), Reason}
745 Options = [Option] | Option
746 Option = {builtins, bool()} | {name, release()} | {verbose,
747 bool()} | {warnings, bool()}
748 Reason = {application_clash, {application(), directory(),
749 directory()}} | {file_error, file(), error()} |
750 {invalid_filename, term()} | {invalid_options, term()} |
751 {release_clash, {release(), directory(), directory()}} | -
752 see also add_directory -
753 Xref = xref()
754 Adds a release, the applications of the release, the modules of
756 the applications, and module data of the modules to an Xref
757 server. The applications will be members of the release, and the
758 modules will be members of the applications. The default is to
759 use the base name of the directory as release name, but this can
760 be overridden by the name option. Returns the name of the
761 release.
762 If the given directory has a subdirectory named lib, the direc‐
764 tories in that directory are assumed to be application directo‐
765 ries, otherwise all subdirectories of the given directory are
766 assumed to be application directories. If there are several ver‐
767 sions of some application, the one with the highest version is
768 chosen.
769 If the mode of the Xref server is functions, BEAM files that
771 contain no debug information are ignored.
772 analyze(Xref, Analysis [, Options]) -> {ok, Answer} | Error
774 Types:
776 Analysis = undefined_function_calls | undefined_functions |
778 locals_not_used | exports_not_used | deprecated_func‐
779 tion_calls | {deprecated_function_calls, DeprFlag} | depre‐
780 cated_functions | {deprecated_functions, DeprFlag} | {call,
781 FuncSpec} | {use, FuncSpec} | {module_call, ModSpec} | {mod‐
782 ule_use, ModSpec} | {application_call, AppSpec} | {applica‐
783 tion_use, AppSpec} | {release_call, RelSpec} | {release_use,
784 RelSpec}
785 Answer = [term()]
786 AppSpec = application() | [application()]
787 DeprFlag = next_version | next_major_release | eventually
788 Error = {error, module(), Reason}
789 FuncSpec = mfa() | [mfa()]
790 ModSpec = module() | [module()]
791 Options = [Option] | Option
792 Option = {verbose, bool()}
793 RelSpec = release() | [release()]
794 Reason = {invalid_options, term()} | {parse_error,
795 string_position(), term()} | {unavailable_analysis, term()} |
796 {unknown_analysis, term()} | {unknown_constant, string()} |
797 {unknown_variable, variable()}
798 Xref = xref()
799 Evaluates a predefined analysis. Returns a sorted list without
801 duplicates of call() or constant(), depending on the chosen
802 analysis. The predefined analyses, which operate on all analyzed
803 modules, are (analyses marked with (*) are available in func‐
804 tionsmode only):
805 undefined_function_calls(*):
807 Returns a list of calls to undefined functions.
808 undefined_functions:
810 Returns a list of undefined functions.
811 locals_not_used(*):
813 Returns a list of local functions that have not been locally
814 used.
815 exports_not_used:
817 Returns a list of exported functions that have not been
818 externally used.
819 deprecated_function_calls(*):
821 Returns a list of external calls to deprecated functions.
822 {deprecated_function_calls, DeprFlag}(*):
824 Returns a list of external calls to deprecated functions. If
825 DeprFlag is equal to next_version, calls to functions to be
826 removed in next version are returned. If DeprFlag is equal
827 to next_major_release, calls to functions to be removed in
828 next major release are returned as well as calls to func‐
829 tions to be removed in next version. Finally, if DeprFlag is
830 equal to eventually, all calls to functions to be removed
831 are returned, including calls to functions to be removed in
832 next version or next major release.
833 deprecated_functions:
835 Returns a list of externally used deprecated functions.
836 {deprecated_functions, DeprFlag}:
838 Returns a list of externally used deprecated functions. If
839 DeprFlag is equal to next_version, functions to be removed
840 in next version are returned. If DeprFlag is equal to
841 next_major_release, functions to be removed in next major
842 release are returned as well as functions to be removed in
843 next version. Finally, if DeprFlag is equal to eventually,
844 all functions to be removed are returned, including func‐
845 tions to be removed in next version or next major release.
846 {call, FuncSpec}(*):
848 Returns a list of functions called by some of the given
849 functions.
850 {use, FuncSpec}(*):
852 Returns a list of functions that use some of the given func‐
853 tions.
854 {module_call, ModSpec}:
856 Returns a list of modules called by some of the given mod‐
857 ules.
858 {module_use, ModSpec}:
860 Returns a list of modules that use some of the given mod‐
861 ules.
862 {application_call, AppSpec}:
864 Returns a list of applications called by some of the given
865 applications.
866 {application_use, AppSpec}:
868 Returns a list of applications that use some of the given
869 applications.
870 {release_call, RelSpec}:
872 Returns a list of releases called by some of the given
873 releases.
874 {release_use, RelSpec}:
876 Returns a list of releases that use some of the given
877 releases.
878 d(Directory) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
880 Types:
882 Directory = directory()
884 DebugInfoResult = {deprecated, [funcall()]} | {undefined,
885 [funcall()]} | {unused, [mfa()]}
886 Error = {error, module(), Reason}
887 NoDebugInfoResult = {deprecated, [mfa()]} | {undefined,
888 [mfa()]}
889 Reason = {file_error, file(), error()} | {invalid_filename,
890 term()} | {unrecognized_file, file()} | - error from
891 beam_lib:chunks/2 -
892 The modules found in the given directory are checked for calls
894 to deprecated functions, calls to undefined functions, and for
895 unused local functions. The code path is used as library path.
896 If some of the found BEAM files contain debug information, then
898 those modules are checked and a list of tuples is returned. The
899 first element of each tuple is one of:
900 * deprecated, the second element is a sorted list of calls to
902 deprecated functions;
903 * undefined, the second element is a sorted list of calls to
905 undefined functions;
906 * unused, the second element is a sorted list of unused local
908 functions.
909 If no BEAM file contains debug information, then a list of
911 tuples is returned. The first element of each tuple is one of:
912 * deprecated, the second element is a sorted list of exter‐
914 nally used deprecated functions;
915 * undefined, the second element is a sorted list of undefined
917 functions.
918 forget(Xref) -> ok
920 forget(Xref, Variables) -> ok | Error
921 Types:
923 Error = {error, module(), Reason}
925 Reason = {not_user_variable, term()}
926 Variables = [variable()] | variable()
927 Xref = xref()
928 forget/1 and forget/2 remove all or some of the user variables
930 of an xref server.
931 format_error(Error) -> Chars
933 Types:
935 Error = {error, module(), term()}
937 Chars = [char() | Chars]
938 Given the error returned by any function of this module, the
940 function format_error returns a descriptive string of the error
941 in English. For file errors, the function format_error/1 in the
942 file module is called.
943 get_default(Xref) -> [{Option, Value}]
945 get_default(Xref, Option) -> {ok, Value} | Error
946 Types:
948 Error = {error, module(), Reason}
950 Option = builtins | recurse | verbose | warnings
951 Reason = {invalid_options, term()}
952 Value = bool()
953 Xref = xref()
954 Returns the default values of one or more options.
956 get_library_path(Xref) -> {ok, LibraryPath}
958 Types:
960 LibraryPath = library_path()
962 Xref = xref()
963 Returns the library path.
965 info(Xref) -> [Info]
967 info(Xref, Category) -> [{Item, [Info]}]
968 info(Xref, Category, Items) -> [{Item, [Info]}]
969 Types:
971 Application = [] | [application()]
973 Category = modules | applications | releases | libraries
974 Info = {application, Application} | {builtins, bool()} |
975 {directory, directory()} | {library_path, library_path()} |
976 {mode, mode()} | {no_analyzed_modules, int()} | {no_applica‐
977 tions, int()} | {no_calls, {NoResolved, NoUnresolved}} |
978 {no_function_calls, {NoLocal, NoResolvedExternal, NoUnre‐
979 solved}} | {no_functions, {NoLocal, NoExternal}} |
980 {no_inter_function_calls, int()} | {no_releases, int()} |
981 {release, Release} | {version, Version}
982 Item = module() | application() | release() | library()
983 Items = Item | [Item]
984 NoLocal = NoExternal = NoResolvedExternal, NoResolved = NoUn‐
985 resolved = int()
986 Release = [] | [release()]
987 Version = [int()]
988 Xref = xref()
989 The info functions return information as a list of pairs {Tag,
991 term()} in some order about the state and the module data of an
992 Xref server.
993 info/1 returns information with the following tags (tags marked
995 with (*) are available in functions mode only):
996 * library_path, the library path;
998 * mode, the mode;
1000 * no_releases, number of releases;
1002 * no_applications, total number of applications (of all
1004 releases);
1005 * no_analyzed_modules, total number of analyzed modules;
1007 * no_calls (*), total number of calls (in all modules),
1009 regarding instances of one function call in different lines
1010 as separate calls;
1011 * no_function_calls (*), total number of local calls, resolved
1013 external calls and unresolved calls;
1014 * no_functions (*), total number of local and exported func‐
1016 tions;
1017 * no_inter_function_calls (*), total number of calls of the
1019 Inter Call Graph.
1020 info/2 and info/3 return information about all or some of the
1022 analyzed modules, applications, releases or library modules of
1023 an Xref server. The following information is returned for every
1024 analyzed module:
1025 * application, an empty list if the module does not belong to
1027 any application, otherwise a list of the application name;
1028 * builtins, whether calls to BIFs are included in the module's
1030 data;
1031 * directory, the directory where the module's BEAM file is
1033 located;
1034 * no_calls (*), number of calls, regarding instances of one
1036 function call in different lines as separate calls;
1037 * no_function_calls (*), number of local calls, resolved
1039 external calls and unresolved calls;
1040 * no_functions (*), number of local and exported functions;
1042 * no_inter_function_calls (*), number of calls of the Inter
1044 Call Graph;
1045 The following information is returned for every application:
1047 * directory, the directory where the modules' BEAM files are
1049 located;
1050 * no_analyzed_modules, number of analyzed modules;
1052 * no_calls (*), number of calls of the application's modules,
1054 regarding instances of one function call in different lines
1055 as separate calls;
1056 * no_function_calls (*), number of local calls, resolved
1058 external calls and unresolved calls of the application's
1059 modules;
1060 * no_functions (*), number of local and exported functions of
1062 the application's modules;
1063 * no_inter_function_calls (*), number of calls of the Inter
1065 Call Graph of the application's modules;
1066 * release, an empty list if the application does not belong to
1068 any release, otherwise a list of the release name;
1069 * version, the application's version as a list of numbers. For
1071 instance, the directory "kernel-2.6" results in the applica‐
1072 tion name kernel and the application version [2,6]; "kernel"
1073 yields the name kernel and the version [].
1074 The following information is returned for every release:
1076 * directory, the release directory;
1078 * no_analyzed_modules, number of analyzed modules;
1080 * no_applications, number of applications;
1082 * no_calls (*), number of calls of the release's modules,
1084 regarding instances of one function call in different lines
1085 as separate calls;
1086 * no_function_calls (*), number of local calls, resolved
1088 external calls and unresolved calls of the release's mod‐
1089 ules;
1090 * no_functions (*), number of local and exported functions of
1092 the release's modules;
1093 * no_inter_function_calls (*), number of calls of the Inter
1095 Call Graph of the release's modules.
1096 The following information is returned for every library module:
1098 * directory, the directory where the library module's BEAM
1100 file is located.
1101 For every number of calls, functions etc. returned by the no_
1103 tags, there is a query returning the same number. Listed below
1104 are examples of such queries. Some of the queries return the sum
1105 of a two or more of the no_ tags numbers. mod (app, rel) refers
1106 to any module (application, release).
1107 * no_analyzed_modules
1109 * "# AM" (info/1)
1111 * "# (Mod) app:App" (application)
1113 * "# (Mod) rel:Rel" (release)
1115 * no_applications
1117 * "# A" (info/1)
1119 * no_calls. The sum of the number of resolved and unresolved
1121 calls:
1122 * "# (XLin) E + # (LLin) E" (info/1)
1124 * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)
1126 * "T = E | app:App, # (LLin) T + # (XLin) T" (application)
1128 * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)
1130 * no_functions. Functions in library modules and the functions
1132 module_info/0,1 are not counted by info. Assuming that
1133 "Extra := _:module_info/\"(0|1)\" + LM" has been evaluated,
1134 the sum of the number of local and exported functions are:
1135 * "# (F - Extra)" (info/1)
1137 * "# (F * mod:Mod - Extra)" (module)
1139 * "# (F * app:App - Extra)" (application)
1141 * "# (F * rel:Rel - Extra)" (release)
1143 * no_function_calls. The sum of the number of local calls,
1145 resolved external calls and unresolved calls:
1146 * "# LC + # XC" (info/1)
1148 * "# LC | mod:Mod + # XC | mod:Mod" (module)
1150 * "# LC | app:App + # XC | app:App" (application)
1152 * "# LC | rel:Rel + # XC | mod:Rel" (release)
1154 * no_inter_function_calls
1156 * "# EE" (info/1)
1158 * "# EE | mod:Mod" (module)
1160 * "# EE | app:App" (application)
1162 * "# EE | rel:Rel" (release)
1164 * no_releases
1166 * "# R" (info/1)
1168 m(Module) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1170 m(File) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1171 Types:
1173 DebugInfoResult = {deprecated, [funcall()]} | {undefined,
1175 [funcall()]} | {unused, [mfa()]}
1176 Error = {error, module(), Reason}
1177 File = file()
1178 Module = module()
1179 NoDebugInfoResult = {deprecated, [mfa()]} | {undefined,
1180 [mfa()]}
1181 Reason = {file_error, file(), error()} | {interpreted, mod‐
1182 ule()} | {invalid_filename, term()} | {cover_compiled, mod‐
1183 ule()} | {no_such_module, module()} | - error from
1184 beam_lib:chunks/2 -
1185 The given BEAM file (with or without the .beam extension) or the
1187 file found by calling code:which(Module) is checked for calls to
1188 deprecated functions, calls to undefined functions, and for
1189 unused local functions. The code path is used as library path.
1190 If the BEAM file contains debug information, then a list of
1192 tuples is returned. The first element of each tuple is one of:
1193 * deprecated, the second element is a sorted list of calls to
1195 deprecated functions;
1196 * undefined, the second element is a sorted list of calls to
1198 undefined functions;
1199 * unused, the second element is a sorted list of unused local
1201 functions.
1202 If the BEAM file does not contain debug information, then a list
1204 of tuples is returned. The first element of each tuple is one
1205 of:
1206 * deprecated, the second element is a sorted list of exter‐
1208 nally used deprecated functions;
1209 * undefined, the second element is a sorted list of undefined
1211 functions.
1212 q(Xref, Query [, Options]) -> {ok, Answer} | Error
1214 Types:
1216 Answer = false | [constant()] | [Call] | [Component] | int()
1218 | [DefineAt] | [CallAt] | [AllLines]
1219 Call = call() | ComponentCall
1220 ComponentCall = {Component, Component}
1221 Component = [constant()]
1222 DefineAt = {mfa(), LineNumber}
1223 CallAt = {funcall(), LineNumbers}
1224 AllLines = {{DefineAt, DefineAt}, LineNumbers}
1225 Error = {error, module(), Reason}
1226 LineNumbers = [LineNumber]
1227 LineNumber = int()
1228 Options = [Option] | Option
1229 Option = {verbose, bool()}
1230 Query = string() | atom()
1231 Reason = {invalid_options, term()} | {parse_error,
1232 string_position(), term()} | {type_error, string()} |
1233 {type_mismatch, string(), string()} | {unknown_analysis,
1234 term()} | {unknown_constant, string()} | {unknown_variable,
1235 variable()} | {variable_reassigned, string()}
1236 Xref = xref()
1237 Evaluates a query in the context of an Xref server, and returns
1239 the value of the last statement. The syntax of the value depends
1240 on the expression:
1241 * A set of calls is represented by a sorted list without
1243 duplicates of call().
1244 * A set of constants is represented by a sorted list without
1246 duplicates of constant().
1247 * A set of strongly connected components is a sorted list
1249 without duplicates of Component.
1250 * A set of calls between strongly connected components is a
1252 sorted list without duplicates of ComponentCall.
1253 * A chain of calls is represented by a list of constant(). The
1255 list contains the From vertex of every call and the To ver‐
1256 tex of the last call.
1257 * The of operator returns false if no chain of calls between
1259 the given constants can be found.
1260 * The value of the closure operator (the digraph representa‐
1262 tion) is represented by the atom 'closure()'.
1263 * A set of line numbered functions is represented by a sorted
1265 list without duplicates of DefineAt.
1266 * A set of line numbered function calls is represented by a
1268 sorted list without duplicates of CallAt.
1269 * A set of line numbered functions and function calls is rep‐
1271 resented by a sorted list without duplicates of AllLines.
1272 For both CallAt and AllLines it holds that for no list element
1274 is LineNumbers an empty list; such elements have been removed.
1275 The constants of component and the integers of LineNumbers are
1276 sorted and without duplicates.
1277 remove_application(Xref, Applications) -> ok | Error
1279 Types:
1281 Applications = application() | [application()]
1283 Error = {error, module(), Reason}
1284 Reason = {no_such_application, application()}
1285 Xref = xref()
1286 Removes applications and their modules and module data from an
1288 Xref server.
1289 remove_module(Xref, Modules) -> ok | Error
1291 Types:
1293 Error = {error, module(), Reason}
1295 Modules = module() | [module()]
1296 Reason = {no_such_module, module()}
1297 Xref = xref()
1298 Removes analyzed modules and module data from an Xref server.
1300 remove_release(Xref, Releases) -> ok | Error
1302 Types:
1304 Error = {error, module(), Reason}
1306 Reason = {no_such_release, release()}
1307 Releases = release() | [release()]
1308 Xref = xref()
1309 Removes releases and their applications, modules and module data
1311 from an Xref server.
1312 replace_application(Xref, Application, Directory [, Options]) -> {ok,
1314 application()} | Error
1315 Types:
1317 Application = application()
1319 Directory = directory()
1320 Error = {error, module(), Reason}
1321 Options = [Option] | Option
1322 Option = {builtins, bool()} | {verbose, bool()} | {warnings,
1323 bool()}
1324 Reason = {no_such_application, application()} | - see also
1325 add_application -
1326 Xref = xref()
1327 Replaces the modules of an application with other modules read
1329 from an application directory. Release membership of the appli‐
1330 cation is retained. Note that the name of the application is
1331 kept; the name of the given directory is not used.
1332 replace_module(Xref, Module, File [, Options]) -> {ok, module()} |
1334 Error
1335 Types:
1337 Error = {error, module(), Reason}
1339 File = file()
1340 Module = module()
1341 Options = [Option] | Option
1342 Option = {verbose, bool()} | {warnings, bool()}
1343 ReadModule = module()
1344 Reason = {module_mismatch, module(), ReadModule} |
1345 {no_such_module, module()} | - see also add_module -
1346 Xref = xref()
1347 Replaces module data of an analyzed module with data read from a
1349 BEAM file. Application membership of the module is retained, and
1350 so is the value of the builtins option of the module. An error
1351 is returned if the name of the read module differs from the
1352 given module.
1353 The update function is an alternative for updating module data
1355 of recompiled modules.
1356 set_default(Xref, Option, Value) -> {ok, OldValue} | Error
1358 set_default(Xref, OptionValues) -> ok | Error
1359 Types:
1361 Error = {error, module(), Reason}
1363 OptionValues = [OptionValue] | OptionValue
1364 OptionValue = {Option, Value}
1365 Option = builtins | recurse | verbose | warnings
1366 Reason = {invalid_options, term()}
1367 Value = bool()
1368 Xref = xref()
1369 Sets the default value of one or more options. The options that
1371 can be set this way are:
1372 * builtins, with initial default value false;
1374 * recurse, with initial default value false;
1376 * verbose, with initial default value false;
1378 * warnings, with initial default value true.
1380 The initial default values are set when creating an Xref server.
1382 set_library_path(Xref, LibraryPath [, Options]) -> ok | Error
1384 Types:
1386 Error = {error, module(), Reason}
1388 LibraryPath = library_path()
1389 Options = [Option] | Option
1390 Option = {verbose, bool()}
1391 Reason = {invalid_options, term()} | {invalid_path, term()}
1392 Xref = xref()
1393 Sets the library path. If the given path is a list of directo‐
1395 ries, the set of library modules is determined by choosing the
1396 first module encountered while traversing the directories in the
1397 given order, for those modules that occur in more than one
1398 directory. By default, the library path is an empty list.
1399 The library path code_path is used by the functions m/1 and d/1,
1401 but can also be set explicitly. Note however that the code path
1402 will be traversed once for each used library module while set‐
1403 ting up module data. On the other hand, if there are only a few
1404 modules that are used but not analyzed, using code_path may be
1405 faster than setting the library path to code:get_path().
1406 If the library path is set to code_path, the set of library mod‐
1408 ules is not determined, and the info functions will return empty
1409 lists of library modules.
1410 start(NameOrOptions) -> Return
1412 Types:
1414 NameOrOptions = Name | Options
1416 Name = atom()
1417 Options = [Option] | Option
1418 Option = {xref_mode, mode()} | term()
1419 Return = {ok, pid()} | {error, {already_started, pid()}}
1420 Creates an Xref server. The process may optionally be given a
1422 name. The default mode is functions. Options that are not recog‐
1423 nized by Xref are passed on to gen_server:start/4.
1424 start(Name, Options) -> Return
1426 Types:
1428 Name = atom()
1430 Options = [Option] | Option
1431 Option = {xref_mode, mode()} | term()
1432 Return = {ok, pid()} | {error, {already_started, pid()}}
1433 Creates an Xref server with a given name. The default mode is
1435 functions. Options that are not recognized by Xref are passed on
1436 to gen_server:start/4.
1437 stop(Xref)
1439 Types:
1441 Xref = xref()
1443 Stops an Xref server.
1445 update(Xref [, Options]) -> {ok, Modules} | Error
1447 Types:
1449 Error = {error, module(), Reason}
1451 Modules = [module()]
1452 Options = [Option] | Option
1453 Option = {verbose, bool()} | {warnings, bool()}
1454 Reason = {invalid_options, term()} | {module_mismatch, mod‐
1455 ule(), ReadModule} | - see also add_module -
1456 Xref = xref()
1457 Replaces the module data of all analyzed modules the BEAM files
1459 of which have been modified since last read by an add function
1460 or update. Application membership of the modules is retained,
1461 and so is the value of the builtins option. Returns a sorted
1462 list of the names of the replaced modules.
1463 variables(Xref [, Options]) -> {ok, [VariableInfo]}
1465 Types:
1467 Options = [Option] | Option
1469 Option = predefined | user | {verbose, bool()}
1470 Reason = {invalid_options, term()}
1471 VariableInfo = {predefined, [variable()]} | {user, [vari‐
1472 able()]}
1473 Xref = xref()
1474 Returns a sorted lists of the names of the variables of an Xref
1476 server. The default is to return the user variables only.
1477
1479 beam_lib(3), digraph(3), digraph_utils(3), re(3), TOOLS User's Guide
1480Ericsson AB tools 3.3.1 xref(3)