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 (BIF) are ignored, but
17 if 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,1,"Use g/1 instead"}).:
83 As above but with a descriptive string. The string is currently
84 unused by xref but other tools can make use of it.
85 -deprecated({f,'_'}).:
87 All exported functions f/0, f/1 and so on are deprecated.
88 -deprecated(module).:
90 All exported functions in the module are deprecated. Equivalent to
91 -deprecated({'_','_'})..
92 -deprecated([{g,1,next_version}]).:
94 The function g/1 is deprecated and will be removed in next version.
95 -deprecated([{g,2,next_major_release}]).:
97 The function g/2 is deprecated and will be removed in next major
98 release.
99 -deprecated([{g,3,eventually}]).:
101 The function g/3 is deprecated and will eventually be removed.
102 -deprecated({'_','_',eventually}).:
104 All exported functions in the module are deprecated and will even‐
105 tually be removed.
106 Before any analysis can take place, module data must be set up. For
108 instance, the cross reference and the unknown functions are computed
109 when all module data are known. The functions that need complete data
110 (analyze, q, variables) take care of setting up data automatically.
111 Module data need to be set up (again) after calls to any of the add,
112 replace, remove, set_library_path or update functions.
113 The result of setting up module data is the Call Graph. A (directed)
115 graph consists of a set of vertices and a set of (directed) edges. The
116 edges represent calls (From, To) between functions, modules, applica‐
117 tions or releases. From is said to call To, and To is said to be used
118 by From. The vertices of the Call Graph are the functions of all module
119 data: local and exported functions of analyzed modules; used BIFs; used
120 exported functions of library modules; and unknown functions. The func‐
121 tions module_info/0,1 added by the compiler are included among the
122 exported functions, but only when called from some module. The edges
123 are the function calls of all module data. A consequence of the edges
124 being a set is that there is only one edge if a function is locally or
125 externally used several times on one and the same line of code.
126 The Call Graph is represented by Erlang terms (the sets are lists),
128 which is suitable for many analyses. But for analyses that look at
129 chains of calls, a list representation is much too slow. Instead the
130 representation offered by the digraph module is used. The translation
131 of the list representation of the Call Graph - or a subgraph thereof -
132 to the digraph representation does not come for free, so the language
133 used for expressing queries to be described below has a special opera‐
134 tor for this task and a possibility to save the digraph representation
135 for subsequent analyses.
136 In addition to the Call Graph there is a graph called the Inter Call
138 Graph. This is a graph of calls (From, To) such that there is a chain
139 of calls from From to To in the Call Graph, and every From and To is an
140 exported function or an unused local function. The vertices are the
141 same as for the Call Graph.
142 Calls between modules, applications and releases are also directed
144 graphs. The types of the vertices and edges of these graphs are (rang‐
145 ing from the most special to the most general): Fun for functions; Mod
146 for modules; App for applications; and Rel for releases. The following
147 paragraphs will describe the different constructs of the language used
148 for selecting and analyzing parts of the graphs, beginning with the
149 constants:
150 * Expression ::= Constants
152 * Constants ::= Consts | Consts : Type | RegExpr
154 * Consts ::= Constant | [Constant, ...] | {Constant, ...}
156 * Constant ::= Call | Const
158 * Call ::= FunSpec -> FunSpec | {MFA, MFA} | AtomConst -> AtomConst |
160 {AtomConst, AtomConst}
161 * Const ::= AtomConst | FunSpec | MFA
163 * AtomConst ::= Application | Module | Release
165 * FunSpec ::= Module : Function / Arity
167 * MFA ::= {Module, Function, Arity}
169 * RegExpr ::= RegString : Type | RegFunc | RegFunc : Type
171 * RegFunc ::= RegModule : RegFunction / RegArity
173 * RegModule ::= RegAtom
175 * RegFunction ::= RegAtom
177 * RegArity ::= RegString | Number | _ | -1
179 * RegAtom ::= RegString | Atom | _
181 * RegString ::= - a regular expression, as described in the re mod‐
183 ule, enclosed in double quotes -
184 * Type ::= Fun | Mod | App | Rel
186 * Function ::= Atom
188 * Application ::= Atom
190 * Module ::= Atom
192 * Release ::= Atom
194 * Arity ::= Number | -1
196 * Atom ::= - same as Erlang atoms -
198 * Number ::= - same as non-negative Erlang integers -
200 Examples of constants are: kernel, kernel->stdlib, [kernel, sasl], [pg
202 -> mnesia, {tv, mnesia}] : Mod. It is an error if an instance of Const
203 does not match any vertex of any graph. If there are more than one ver‐
204 tex matching an untyped instance of AtomConst, then the one of the most
205 general type is chosen. A list of constants is interpreted as a set of
206 constants, all of the same type. A tuple of constants constitute a
207 chain of calls (which may, but does not have to, correspond to an
208 actual chain of calls of some graph). Assigning a type to a list or
209 tuple of Constant is equivalent to assigning the type to each Constant.
210 Regular expressions are used as a means to select some of the vertices
212 of a graph. A RegExpr consisting of a RegString and a type - an example
213 is "xref_.*" : Mod - is interpreted as those modules (or applications
214 or releases, depending on the type) that match the expression. Simi‐
215 larly, a RegFunc is interpreted as those vertices of the Call Graph
216 that match the expression. An example is "xref_.*":"add_.*"/"(2|3)",
217 which matches all add functions of arity two or three of any of the
218 xref modules. Another example, one that matches all functions of arity
219 10 or more: _:_/"[1-9].+". Here _ is an abbreviation for ".*", that is,
220 the regular expression that matches anything.
221 The syntax of variables is simple:
223 * Expression ::= Variable
225 * Variable ::= - same as Erlang variables -
227 There are two kinds of variables: predefined variables and user vari‐
229 ables. Predefined variables hold set up module data, and cannot be
230 assigned to but only used in queries. User variables on the other hand
231 can be assigned to, and are typically used for temporary results while
232 evaluating a query, and for keeping results of queries for use in sub‐
233 sequent queries. The predefined variables are (variables marked with
234 (*) are available in functions mode only):
235 E:
237 Call Graph Edges (*).
238 V:
240 Call Graph Vertices (*).
241 M:
243 Modules. All modules: analyzed modules, used library modules, and
244 unknown modules.
245 A:
247 Applications.
248 R:
250 Releases.
251 ME:
253 Module Edges. All module calls.
254 AE:
256 Application Edges. All application calls.
257 RE:
259 Release Edges. All release calls.
260 L:
262 Local Functions (*). All local functions of analyzed modules.
263 X:
265 Exported Functions. All exported functions of analyzed modules and
266 all used exported functions of library modules.
267 F:
269 Functions (*).
270 B:
272 Used BIFs. B is empty if builtins is false for all analyzed mod‐
273 ules.
274 U:
276 Unknown Functions.
277 UU:
279 Unused Functions (*). All local and exported functions of analyzed
280 modules that have not been used.
281 XU:
283 Externally Used Functions. Functions of all modules - including
284 local functions - that have been used in some external call.
285 LU:
287 Locally Used Functions (*). Functions of all modules that have been
288 used in some local call.
289 OL:
291 Functions with an attribute tag on_load (*).
292 LC:
294 Local Calls (*).
295 XC:
297 External Calls (*).
298 AM:
300 Analyzed Modules.
301 UM:
303 Unknown Modules.
304 LM:
306 Used Library Modules.
307 UC:
309 Unresolved Calls. Empty in modules mode.
310 EE:
312 Inter Call Graph Edges (*).
313 DF:
315 Deprecated Functions. All deprecated exported functions and all
316 used deprecated BIFs.
317 DF_1:
319 Deprecated Functions. All deprecated functions to be removed in
320 next version.
321 DF_2:
323 Deprecated Functions. All deprecated functions to be removed in
324 next version or next major release.
325 DF_3:
327 Deprecated Functions. All deprecated functions to be removed in
328 next version, next major release, or later.
329 These are a few facts about the predefined variables (the set operators
331 + (union) and - (difference) as well as the cast operator (Type) are
332 described below):
333 * F is equal to L + X.
335 * V is equal to X + L + B + U, where X, L, B and U are pairwise dis‐
337 joint (that is, have no elements in common).
338 * UU is equal to V - (XU + LU), where LU and XU may have elements in
340 common. Put in another way:
341 * V is equal to UU + XU + LU.
343 * OL is a subset of F.
345 * E is equal to LC + XC. Note that LC and XC may have elements in
347 common, namely if some function is locally and externally used from
348 one and the same function.
349 * U is a subset of XU.
351 * B is a subset of XU.
353 * LU is equal to range LC.
355 * XU is equal to range XC.
357 * LU is a subset of F.
359 * UU is a subset of F.
361 * range UC is a subset of U.
363 * M is equal to AM + LM + UM, where AM, LM and UM are pairwise dis‐
365 joint.
366 * ME is equal to (Mod) E.
368 * AE is equal to (App) E.
370 * RE is equal to (Rel) E.
372 * (Mod) V is a subset of M. Equality holds if all analyzed modules
374 have some local, exported, or unknown function.
375 * (App) M is a subset of A. Equality holds if all applications have
377 some module.
378 * (Rel) A is a subset of R. Equality holds if all releases have some
380 application.
381 * DF_1 is a subset of DF_2.
383 * DF_2 is a subset of DF_3.
385 * DF_3 is a subset of DF.
387 * DF is a subset of X + B.
389 An important notion is that of conversion of expressions. The syntax of
391 a cast expression is:
392 * Expression ::= ( Type ) Expression
394 The interpretation of the cast operator depends on the named type Type,
396 the type of Expression, and the structure of the elements of the inter‐
397 pretation of Expression. If the named type is equal to the expression
398 type, no conversion is done. Otherwise, the conversion is done one step
399 at a time; (Fun) (App) RE, for instance, is equivalent to (Fun) (Mod)
400 (App) RE. Now assume that the interpretation of Expression is a set of
401 constants (functions, modules, applications or releases). If the named
402 type is more general than the expression type, say Mod and Fun respec‐
403 tively, then the interpretation of the cast expression is the set of
404 modules that have at least one of their functions mentioned in the
405 interpretation of the expression. If the named type is more special
406 than the expression type, say Fun and Mod, then the interpretation is
407 the set of all the functions of the modules (in modules mode, the con‐
408 version is partial since the local functions are not known). The con‐
409 versions to and from applications and releases work analogously. For
410 instance, (App) "xref_.*" : Mod returns all applications containing at
411 least one module such that xref_ is a prefix of the module name.
412 Now assume that the interpretation of Expression is a set of calls. If
414 the named type is more general than the expression type, say Mod and
415 Fun respectively, then the interpretation of the cast expression is the
416 set of calls (M1, M2) such that the interpretation of the expression
417 contains a call from some function of M1 to some function of M2. If the
418 named type is more special than the expression type, say Fun and Mod,
419 then the interpretation is the set of all function calls (F1, F2) such
420 that the interpretation of the expression contains a call (M1, M2) and
421 F1 is a function of M1 and F2 is a function of M2 (in modules mode,
422 there are no functions calls, so a cast to Fun always yields an empty
423 set). Again, the conversions to and from applications and releases work
424 analogously.
425 The interpretation of constants and variables are sets, and those sets
427 can be used as the basis for forming new sets by the application of set
428 operators. The syntax:
429 * Expression ::= Expression BinarySetOp Expression
431 * BinarySetOp ::= + | * | -
433 +, * and - are interpreted as union, intersection and difference
435 respectively: the union of two sets contains the elements of both sets;
436 the intersection of two sets contains the elements common to both sets;
437 and the difference of two sets contains the elements of the first set
438 that are not members of the second set. The elements of the two sets
439 must be of the same structure; for instance, a function call cannot be
440 combined with a function. But if a cast operator can make the elements
441 compatible, then the more general elements are converted to the less
442 general element type. For instance, M + F is equivalent to (Fun) M + F,
443 and E - AE is equivalent to E - (Fun) AE. One more example: X * xref :
444 Mod is interpreted as the set of functions exported by the module xref;
445 xref : Mod is converted to the more special type of X (Fun, that is)
446 yielding all functions of xref, and the intersection with X (all func‐
447 tions exported by analyzed modules and library modules) is interpreted
448 as those functions that are exported by some module and functions of
449 xref.
450 There are also unary set operators:
452 * Expression ::= UnarySetOp Expression
454 * UnarySetOp ::= domain | range | strict
456 Recall that a call is a pair (From, To). domain applied to a set of
458 calls is interpreted as the set of all vertices From, and range as the
459 set of all vertices To. The interpretation of the strict operator is
460 the operand with all calls on the form (A, A) removed.
461 The interpretation of the restriction operators is a subset of the
463 first operand, a set of calls. The second operand, a set of vertices,
464 is converted to the type of the first operand. The syntax of the
465 restriction operators:
466 * Expression ::= Expression RestrOp Expression
468 * RestrOp ::= |
470 * RestrOp ::= ||
472 * RestrOp ::= |||
474 The interpretation in some detail for the three operators:
476 |:
478 The subset of calls from any of the vertices.
479 ||:
481 The subset of calls to any of the vertices.
482 |||:
484 The subset of calls to and from any of the vertices. For all sets
485 of calls CS and all sets of vertices VS, CS ||| VS is equivalent
486 to CS | VS * CS || VS.
487 Two functions (modules, applications, releases) belong to the same
489 strongly connected component if they call each other (in)directly. The
490 interpretation of the components operator is the set of strongly con‐
491 nected components of a set of calls. The condensation of a set of calls
492 is a new set of calls between the strongly connected components such
493 that there is an edge between two components if there is some constant
494 of the first component that calls some constant of the second compo‐
495 nent.
496 The interpretation of the of operator is a chain of calls of the second
498 operand (a set of calls) that passes throw all of the vertices of the
499 first operand (a tuple of constants), in the given order. The second
500 operand is converted to the type of the first operand. For instance,
501 the of operator can be used for finding out whether a function calls
502 another function indirectly, and the chain of calls demonstrates how.
503 The syntax of the graph analyzing operators:
504 * Expression ::= Expression BinaryGraphOp Expression
506 * Expression ::= UnaryGraphOp Expression
508 * UnaryGraphOp ::= components | condensation
510 * BinaryGraphOp ::= of
512 As was mentioned before, the graph analyses operate on the digraph rep‐
514 resentation of graphs. By default, the digraph representation is cre‐
515 ated when needed (and deleted when no longer used), but it can also be
516 created explicitly by use of the closure operator:
517 * Expression ::= ClosureOp Expression
519 * ClosureOp ::= closure
521 The interpretation of the closure operator is the transitive closure of
523 the operand.
524 The restriction operators are defined for closures as well; closure E |
526 xref : Mod is interpreted as the direct or indirect function calls from
527 the xref module, while the interpretation of E | xref : Mod is the set
528 of direct calls from xref. If some graph is to be used in several graph
529 analyses, it saves time to assign the digraph representation of the
530 graph to a user variable, and then make sure that every graph analysis
531 operates on that variable instead of the list representation of the
532 graph.
533 The lines where functions are defined (more precisely: where the first
535 clause begins) and the lines where functions are used are available in
536 functions mode. The line numbers refer to the files where the functions
537 are defined. This holds also for files included with the -include and
538 -include_lib directives, which may result in functions defined appar‐
539 ently in the same line. The line operators are used for assigning line
540 numbers to functions and for assigning sets of line numbers to function
541 calls. The syntax is similar to the one of the cast operator:
542 * Expression ::= ( LineOp) Expression
544 * Expression ::= ( XLineOp) Expression
546 * LineOp ::= Lin | ELin | LLin | XLin
548 * XLineOp ::= XXL
550 The interpretation of the Lin operator applied to a set of functions
552 assigns to each function the line number where the function is defined.
553 Unknown functions and functions of library modules are assigned the
554 number 0.
555 The interpretation of some LineOp operator applied to a set of function
557 calls assigns to each call the set of line numbers where the first
558 function calls the second function. Not all calls are assigned line
559 numbers by all operators:
560 * the Lin operator is defined for Call Graph Edges;
562 * the LLin operator is defined for Local Calls.
564 * the XLin operator is defined for External Calls.
566 * the ELin operator is defined for Inter Call Graph Edges.
568 The Lin (LLin, XLin) operator assigns the lines where calls (local
570 calls, external calls) are made. The ELin operator assigns to each call
571 (From, To), for which it is defined, every line L such that there is a
572 chain of calls from From to To beginning with a call on line L.
573 The XXL operator is defined for the interpretation of any of the LineOp
575 operators applied to a set of function calls. The result is that of
576 replacing the function call with a line numbered function call, that
577 is, each of the two functions of the call is replaced by a pair of the
578 function and the line where the function is defined. The effect of the
579 XXL operator can be undone by the LineOp operators. For instance, (Lin)
580 (XXL) (Lin) E is equivalent to (Lin) E.
581 The +, -, * and # operators are defined for line number expressions,
583 provided the operands are compatible. The LineOp operators are also
584 defined for modules, applications, and releases; the operand is implic‐
585 itly converted to functions. Similarly, the cast operator is defined
586 for the interpretation of the LineOp operators.
587 The interpretation of the counting operator is the number of elements
589 of a set. The operator is undefined for closures. The +, - and * opera‐
590 tors are interpreted as the obvious arithmetical operators when applied
591 to numbers. The syntax of the counting operator:
592 * Expression ::= CountOp Expression
594 * CountOp ::= #
596 All binary operators are left associative; for instance, A | B || C is
598 equivalent to (A | B) || C. The following is a list of all operators,
599 in increasing order of precedence:
600 * +, -
602 * *
604 * #
606 * |, ||, |||
608 * of
610 * (Type)
612 * closure, components, condensation, domain, range, strict
614 Parentheses are used for grouping, either to make an expression more
616 readable or to override the default precedence of operators:
617 * Expression ::= ( Expression )
619 A query is a non-empty sequence of statements. A statement is either an
621 assignment of a user variable or an expression. The value of an assign‐
622 ment is the value of the right hand side expression. It makes no sense
623 to put a plain expression anywhere else but last in queries. The syntax
624 of queries is summarized by these productions:
625 * Query ::= Statement, ...
627 * Statement ::= Assignment | Expression
629 * Assignment ::= Variable := Expression | Variable = Expression
631 A variable cannot be assigned a new value unless first removed. Vari‐
633 ables assigned to by the = operator are removed at the end of the
634 query, while variables assigned to by the := operator can only be
635 removed by calls to forget. There are no user variables when module
636 data need to be set up again; if any of the functions that make it nec‐
637 essary to set up module data again is called, all user variables are
638 forgotten.
639 Types
641 application() = atom()
643 arity() = int() | -1
644 bool() = true | false
645 call() = {atom(), atom()} | funcall()
646 constant() = mfa() | module() | application() | release()
647 directory() = string()
648 file() = string()
649 funcall() = {mfa(), mfa()}
650 function() = atom()
651 int() = integer() >= 0
652 library() = atom()
653 library_path() = path() | code_path
654 mfa() = {module(), function(), arity()}
655 mode() = functions | modules
656 module() = atom()
657 release() = atom()
658 string_position() = int() | at_end
659 variable() = atom()
660 xref() = atom() | pid()
661
663 add_application(Xref, Directory [, Options]) -> {ok, application()} |
664 Error
665 Types:
667 Directory = directory()
669 Error = {error, module(), Reason}
670 Options = [Option] | Option
671 Option = {builtins, bool()} | {name, application()} | {ver‐
672 bose, bool()} | {warnings, bool()}
673 Reason = {application_clash, {application(), directory(),
674 directory()}} | {file_error, file(), error()} |
675 {invalid_filename, term()} | {invalid_options, term()} | -
676 see also add_directory -
677 Xref = xref()
678 Adds an application, the modules of the application and module
680 data of the modules to an Xref server. The modules will be mem‐
681 bers of the application. The default is to use the base name of
682 the directory with the version removed as application name, but
683 this can be overridden by the name option. Returns the name of
684 the application.
685 If the given directory has a subdirectory named ebin, modules
687 (BEAM files) are searched for in that directory, otherwise mod‐
688 ules are searched for in the given directory.
689 If the mode of the Xref server is functions, BEAM files that
691 contain no debug information are ignored.
692 add_directory(Xref, Directory [, Options]) -> {ok, Modules} | Error
694 Types:
696 Directory = directory()
698 Error = {error, module(), Reason}
699 Modules = [module()]
700 Options = [Option] | Option
701 Option = {builtins, bool()} | {recurse, bool()} | {verbose,
702 bool()} | {warnings, bool()}
703 Reason = {file_error, file(), error()} | {invalid_filename,
704 term()} | {invalid_options, term()} | {unrecognized_file,
705 file()} | - error from beam_lib:chunks/2 -
706 Xref = xref()
707 Adds the modules found in the given directory and the modules'
709 data to an Xref server. The default is not to examine subdirec‐
710 tories, but if the option recurse has the value true, modules
711 are searched for in subdirectories on all levels as well as in
712 the given directory. Returns a sorted list of the names of the
713 added modules.
714 The modules added will not be members of any applications.
716 If the mode of the Xref server is functions, BEAM files that
718 contain no debug information are ignored.
719 add_module(Xref, File [, Options]) -> {ok, module()} | Error
721 Types:
723 Error = {error, module(), Reason}
725 File = file()
726 Options = [Option] | Option
727 Option = {builtins, bool()} | {verbose, bool()} | {warnings,
728 bool()}
729 Reason = {file_error, file(), error()} | {invalid_filename,
730 term()} | {invalid_options, term()} | {module_clash, {mod‐
731 ule(), file(), file()}} | {no_debug_info, file()} | - error
732 from beam_lib:chunks/2 -
733 Xref = xref()
734 Adds a module and its module data to an Xref server. The module
736 will not be member of any application. Returns the name of the
737 module.
738 If the mode of the Xref server is functions, and the BEAM file
740 contains no debug information, the error message no_debug_info
741 is returned.
742 add_release(Xref, Directory [, Options]) -> {ok, release()} | Error
744 Types:
746 Directory = directory()
748 Error = {error, module(), Reason}
749 Options = [Option] | Option
750 Option = {builtins, bool()} | {name, release()} | {verbose,
751 bool()} | {warnings, bool()}
752 Reason = {application_clash, {application(), directory(),
753 directory()}} | {file_error, file(), error()} |
754 {invalid_filename, term()} | {invalid_options, term()} |
755 {release_clash, {release(), directory(), directory()}} | -
756 see also add_directory -
757 Xref = xref()
758 Adds a release, the applications of the release, the modules of
760 the applications, and module data of the modules to an Xref
761 server. The applications will be members of the release, and the
762 modules will be members of the applications. The default is to
763 use the base name of the directory as release name, but this can
764 be overridden by the name option. Returns the name of the
765 release.
766 If the given directory has a subdirectory named lib, the direc‐
768 tories in that directory are assumed to be application directo‐
769 ries, otherwise all subdirectories of the given directory are
770 assumed to be application directories. If there are several ver‐
771 sions of some application, the one with the highest version is
772 chosen.
773 If the mode of the Xref server is functions, BEAM files that
775 contain no debug information are ignored.
776 analyze(Xref, Analysis [, Options]) -> {ok, Answer} | Error
778 Types:
780 Analysis = undefined_function_calls | undefined_functions |
782 locals_not_used | exports_not_used | deprecated_func‐
783 tion_calls | {deprecated_function_calls, DeprFlag} | depre‐
784 cated_functions | {deprecated_functions, DeprFlag} | {call,
785 FuncSpec} | {use, FuncSpec} | {module_call, ModSpec} | {mod‐
786 ule_use, ModSpec} | {application_call, AppSpec} | {applica‐
787 tion_use, AppSpec} | {release_call, RelSpec} | {release_use,
788 RelSpec}
789 Answer = [term()]
790 AppSpec = application() | [application()]
791 DeprFlag = next_version | next_major_release | eventually
792 Error = {error, module(), Reason}
793 FuncSpec = mfa() | [mfa()]
794 ModSpec = module() | [module()]
795 Options = [Option] | Option
796 Option = {verbose, bool()}
797 RelSpec = release() | [release()]
798 Reason = {invalid_options, term()} | {parse_error,
799 string_position(), term()} | {unavailable_analysis, term()} |
800 {unknown_analysis, term()} | {unknown_constant, string()} |
801 {unknown_variable, variable()}
802 Xref = xref()
803 Evaluates a predefined analysis. Returns a sorted list without
805 duplicates of call() or constant(), depending on the chosen
806 analysis. The predefined analyses, which operate on all analyzed
807 modules, are (analyses marked with (*) are available in func‐
808 tionsmode only):
809 undefined_function_calls(*):
811 Returns a list of calls to undefined functions.
812 undefined_functions:
814 Returns a list of undefined functions.
815 locals_not_used(*):
817 Returns a list of local functions that have not been locally
818 used.
819 exports_not_used:
821 Returns a list of exported functions that have not been
822 externally used. Note that in modules mode, M:behav‐
823 iour_info/1 is never reported as unused.
824 deprecated_function_calls(*):
826 Returns a list of external calls to deprecated functions.
827 {deprecated_function_calls, DeprFlag}(*):
829 Returns a list of external calls to deprecated functions. If
830 DeprFlag is equal to next_version, calls to functions to be
831 removed in next version are returned. If DeprFlag is equal
832 to next_major_release, calls to functions to be removed in
833 next major release are returned as well as calls to func‐
834 tions to be removed in next version. Finally, if DeprFlag is
835 equal to eventually, all calls to functions to be removed
836 are returned, including calls to functions to be removed in
837 next version or next major release.
838 deprecated_functions:
840 Returns a list of externally used deprecated functions.
841 {deprecated_functions, DeprFlag}:
843 Returns a list of externally used deprecated functions. If
844 DeprFlag is equal to next_version, functions to be removed
845 in next version are returned. If DeprFlag is equal to
846 next_major_release, functions to be removed in next major
847 release are returned as well as functions to be removed in
848 next version. Finally, if DeprFlag is equal to eventually,
849 all functions to be removed are returned, including func‐
850 tions to be removed in next version or next major release.
851 {call, FuncSpec}(*):
853 Returns a list of functions called by some of the given
854 functions.
855 {use, FuncSpec}(*):
857 Returns a list of functions that use some of the given func‐
858 tions.
859 {module_call, ModSpec}:
861 Returns a list of modules called by some of the given mod‐
862 ules.
863 {module_use, ModSpec}:
865 Returns a list of modules that use some of the given mod‐
866 ules.
867 {application_call, AppSpec}:
869 Returns a list of applications called by some of the given
870 applications.
871 {application_use, AppSpec}:
873 Returns a list of applications that use some of the given
874 applications.
875 {release_call, RelSpec}:
877 Returns a list of releases called by some of the given
878 releases.
879 {release_use, RelSpec}:
881 Returns a list of releases that use some of the given
882 releases.
883 d(Directory) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
885 Types:
887 Directory = directory()
889 DebugInfoResult = {deprecated, [funcall()]} | {undefined,
890 [funcall()]} | {unused, [mfa()]}
891 Error = {error, module(), Reason}
892 NoDebugInfoResult = {deprecated, [mfa()]} | {undefined,
893 [mfa()]}
894 Reason = {file_error, file(), error()} | {invalid_filename,
895 term()} | {unrecognized_file, file()} | - error from
896 beam_lib:chunks/2 -
897 The modules found in the given directory are checked for calls
899 to deprecated functions, calls to undefined functions, and for
900 unused local functions. The code path is used as library path.
901 If some of the found BEAM files contain debug information, then
903 those modules are checked and a list of tuples is returned. The
904 first element of each tuple is one of:
905 * deprecated, the second element is a sorted list of calls to
907 deprecated functions;
908 * undefined, the second element is a sorted list of calls to
910 undefined functions;
911 * unused, the second element is a sorted list of unused local
913 functions.
914 If no BEAM file contains debug information, then a list of
916 tuples is returned. The first element of each tuple is one of:
917 * deprecated, the second element is a sorted list of exter‐
919 nally used deprecated functions;
920 * undefined, the second element is a sorted list of undefined
922 functions.
923 forget(Xref) -> ok
925 forget(Xref, Variables) -> ok | Error
926 Types:
928 Error = {error, module(), Reason}
930 Reason = {not_user_variable, term()}
931 Variables = [variable()] | variable()
932 Xref = xref()
933 forget/1 and forget/2 remove all or some of the user variables
935 of an xref server.
936 format_error(Error) -> Chars
938 Types:
940 Error = {error, module(), term()}
942 Chars = [char() | Chars]
943 Given the error returned by any function of this module, the
945 function format_error returns a descriptive string of the error
946 in English. For file errors, the function format_error/1 in the
947 file module is called.
948 get_default(Xref) -> [{Option, Value}]
950 get_default(Xref, Option) -> {ok, Value} | Error
951 Types:
953 Error = {error, module(), Reason}
955 Option = builtins | recurse | verbose | warnings
956 Reason = {invalid_options, term()}
957 Value = bool()
958 Xref = xref()
959 Returns the default values of one or more options.
961 get_library_path(Xref) -> {ok, LibraryPath}
963 Types:
965 LibraryPath = library_path()
967 Xref = xref()
968 Returns the library path.
970 info(Xref) -> [Info]
972 info(Xref, Category) -> [{Item, [Info]}]
973 info(Xref, Category, Items) -> [{Item, [Info]}]
974 Types:
976 Application = [] | [application()]
978 Category = modules | applications | releases | libraries
979 Info = {application, Application} | {builtins, bool()} |
980 {directory, directory()} | {library_path, library_path()} |
981 {mode, mode()} | {no_analyzed_modules, int()} | {no_applica‐
982 tions, int()} | {no_calls, {NoResolved, NoUnresolved}} |
983 {no_function_calls, {NoLocal, NoResolvedExternal, NoUnre‐
984 solved}} | {no_functions, {NoLocal, NoExternal}} |
985 {no_inter_function_calls, int()} | {no_releases, int()} |
986 {release, Release} | {version, Version}
987 Item = module() | application() | release() | library()
988 Items = Item | [Item]
989 NoLocal = NoExternal = NoResolvedExternal, NoResolved = NoUn‐
990 resolved = int()
991 Release = [] | [release()]
992 Version = [int()]
993 Xref = xref()
994 The info functions return information as a list of pairs {Tag,
996 term()} in some order about the state and the module data of an
997 Xref server.
998 info/1 returns information with the following tags (tags marked
1000 with (*) are available in functions mode only):
1001 * library_path, the library path;
1003 * mode, the mode;
1005 * no_releases, number of releases;
1007 * no_applications, total number of applications (of all
1009 releases);
1010 * no_analyzed_modules, total number of analyzed modules;
1012 * no_calls (*), total number of calls (in all modules),
1014 regarding instances of one function call in different lines
1015 as separate calls;
1016 * no_function_calls (*), total number of local calls, resolved
1018 external calls and unresolved calls;
1019 * no_functions (*), total number of local and exported func‐
1021 tions;
1022 * no_inter_function_calls (*), total number of calls of the
1024 Inter Call Graph.
1025 info/2 and info/3 return information about all or some of the
1027 analyzed modules, applications, releases or library modules of
1028 an Xref server. The following information is returned for every
1029 analyzed module:
1030 * application, an empty list if the module does not belong to
1032 any application, otherwise a list of the application name;
1033 * builtins, whether calls to BIFs are included in the module's
1035 data;
1036 * directory, the directory where the module's BEAM file is
1038 located;
1039 * no_calls (*), number of calls, regarding instances of one
1041 function call in different lines as separate calls;
1042 * no_function_calls (*), number of local calls, resolved
1044 external calls and unresolved calls;
1045 * no_functions (*), number of local and exported functions;
1047 * no_inter_function_calls (*), number of calls of the Inter
1049 Call Graph;
1050 The following information is returned for every application:
1052 * directory, the directory where the modules' BEAM files are
1054 located;
1055 * no_analyzed_modules, number of analyzed modules;
1057 * no_calls (*), number of calls of the application's modules,
1059 regarding instances of one function call in different lines
1060 as separate calls;
1061 * no_function_calls (*), number of local calls, resolved
1063 external calls and unresolved calls of the application's
1064 modules;
1065 * no_functions (*), number of local and exported functions of
1067 the application's modules;
1068 * no_inter_function_calls (*), number of calls of the Inter
1070 Call Graph of the application's modules;
1071 * release, an empty list if the application does not belong to
1073 any release, otherwise a list of the release name;
1074 * version, the application's version as a list of numbers. For
1076 instance, the directory "kernel-2.6" results in the applica‐
1077 tion name kernel and the application version [2,6]; "kernel"
1078 yields the name kernel and the version [].
1079 The following information is returned for every release:
1081 * directory, the release directory;
1083 * no_analyzed_modules, number of analyzed modules;
1085 * no_applications, number of applications;
1087 * no_calls (*), number of calls of the release's modules,
1089 regarding instances of one function call in different lines
1090 as separate calls;
1091 * no_function_calls (*), number of local calls, resolved
1093 external calls and unresolved calls of the release's mod‐
1094 ules;
1095 * no_functions (*), number of local and exported functions of
1097 the release's modules;
1098 * no_inter_function_calls (*), number of calls of the Inter
1100 Call Graph of the release's modules.
1101 The following information is returned for every library module:
1103 * directory, the directory where the library module's BEAM
1105 file is located.
1106 For every number of calls, functions etc. returned by the no_
1108 tags, there is a query returning the same number. Listed below
1109 are examples of such queries. Some of the queries return the sum
1110 of a two or more of the no_ tags numbers. mod (app, rel) refers
1111 to any module (application, release).
1112 * no_analyzed_modules
1114 * "# AM" (info/1)
1116 * "# (Mod) app:App" (application)
1118 * "# (Mod) rel:Rel" (release)
1120 * no_applications
1122 * "# A" (info/1)
1124 * no_calls. The sum of the number of resolved and unresolved
1126 calls:
1127 * "# (XLin) E + # (LLin) E" (info/1)
1129 * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)
1131 * "T = E | app:App, # (LLin) T + # (XLin) T" (application)
1133 * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)
1135 * no_functions. Functions in library modules and the functions
1137 module_info/0,1 are not counted by info. Assuming that
1138 "Extra := _:module_info/\"(0|1)\" + LM" has been evaluated,
1139 the sum of the number of local and exported functions are:
1140 * "# (F - Extra)" (info/1)
1142 * "# (F * mod:Mod - Extra)" (module)
1144 * "# (F * app:App - Extra)" (application)
1146 * "# (F * rel:Rel - Extra)" (release)
1148 * no_function_calls. The sum of the number of local calls,
1150 resolved external calls and unresolved calls:
1151 * "# LC + # XC" (info/1)
1153 * "# LC | mod:Mod + # XC | mod:Mod" (module)
1155 * "# LC | app:App + # XC | app:App" (application)
1157 * "# LC | rel:Rel + # XC | mod:Rel" (release)
1159 * no_inter_function_calls
1161 * "# EE" (info/1)
1163 * "# EE | mod:Mod" (module)
1165 * "# EE | app:App" (application)
1167 * "# EE | rel:Rel" (release)
1169 * no_releases
1171 * "# R" (info/1)
1173 m(Module) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1175 m(File) -> [DebugInfoResult] | [NoDebugInfoResult] | Error
1176 Types:
1178 DebugInfoResult = {deprecated, [funcall()]} | {undefined,
1180 [funcall()]} | {unused, [mfa()]}
1181 Error = {error, module(), Reason}
1182 File = file()
1183 Module = module()
1184 NoDebugInfoResult = {deprecated, [mfa()]} | {undefined,
1185 [mfa()]}
1186 Reason = {file_error, file(), error()} | {interpreted, mod‐
1187 ule()} | {invalid_filename, term()} | {cover_compiled, mod‐
1188 ule()} | {no_such_module, module()} | - error from
1189 beam_lib:chunks/2 -
1190 The given BEAM file (with or without the .beam extension) or the
1192 file found by calling code:which(Module) is checked for calls to
1193 deprecated functions, calls to undefined functions, and for
1194 unused local functions. The code path is used as library path.
1195 If the BEAM file contains debug information, then a list of
1197 tuples is returned. The first element of each tuple is one of:
1198 * deprecated, the second element is a sorted list of calls to
1200 deprecated functions;
1201 * undefined, the second element is a sorted list of calls to
1203 undefined functions;
1204 * unused, the second element is a sorted list of unused local
1206 functions.
1207 If the BEAM file does not contain debug information, then a list
1209 of tuples is returned. The first element of each tuple is one
1210 of:
1211 * deprecated, the second element is a sorted list of exter‐
1213 nally used deprecated functions;
1214 * undefined, the second element is a sorted list of undefined
1216 functions.
1217 q(Xref, Query [, Options]) -> {ok, Answer} | Error
1219 Types:
1221 Answer = false | [constant()] | [Call] | [Component] | int()
1223 | [DefineAt] | [CallAt] | [AllLines]
1224 Call = call() | ComponentCall
1225 ComponentCall = {Component, Component}
1226 Component = [constant()]
1227 DefineAt = {mfa(), LineNumber}
1228 CallAt = {funcall(), LineNumbers}
1229 AllLines = {{DefineAt, DefineAt}, LineNumbers}
1230 Error = {error, module(), Reason}
1231 LineNumbers = [LineNumber]
1232 LineNumber = int()
1233 Options = [Option] | Option
1234 Option = {verbose, bool()}
1235 Query = string() | atom()
1236 Reason = {invalid_options, term()} | {parse_error,
1237 string_position(), term()} | {type_error, string()} |
1238 {type_mismatch, string(), string()} | {unknown_analysis,
1239 term()} | {unknown_constant, string()} | {unknown_variable,
1240 variable()} | {variable_reassigned, string()}
1241 Xref = xref()
1242 Evaluates a query in the context of an Xref server, and returns
1244 the value of the last statement. The syntax of the value depends
1245 on the expression:
1246 * A set of calls is represented by a sorted list without
1248 duplicates of call().
1249 * A set of constants is represented by a sorted list without
1251 duplicates of constant().
1252 * A set of strongly connected components is a sorted list
1254 without duplicates of Component.
1255 * A set of calls between strongly connected components is a
1257 sorted list without duplicates of ComponentCall.
1258 * A chain of calls is represented by a list of constant(). The
1260 list contains the From vertex of every call and the To ver‐
1261 tex of the last call.
1262 * The of operator returns false if no chain of calls between
1264 the given constants can be found.
1265 * The value of the closure operator (the digraph representa‐
1267 tion) is represented by the atom 'closure()'.
1268 * A set of line numbered functions is represented by a sorted
1270 list without duplicates of DefineAt.
1271 * A set of line numbered function calls is represented by a
1273 sorted list without duplicates of CallAt.
1274 * A set of line numbered functions and function calls is rep‐
1276 resented by a sorted list without duplicates of AllLines.
1277 For both CallAt and AllLines it holds that for no list element
1279 is LineNumbers an empty list; such elements have been removed.
1280 The constants of component and the integers of LineNumbers are
1281 sorted and without duplicates.
1282 remove_application(Xref, Applications) -> ok | Error
1284 Types:
1286 Applications = application() | [application()]
1288 Error = {error, module(), Reason}
1289 Reason = {no_such_application, application()}
1290 Xref = xref()
1291 Removes applications and their modules and module data from an
1293 Xref server.
1294 remove_module(Xref, Modules) -> ok | Error
1296 Types:
1298 Error = {error, module(), Reason}
1300 Modules = module() | [module()]
1301 Reason = {no_such_module, module()}
1302 Xref = xref()
1303 Removes analyzed modules and module data from an Xref server.
1305 remove_release(Xref, Releases) -> ok | Error
1307 Types:
1309 Error = {error, module(), Reason}
1311 Reason = {no_such_release, release()}
1312 Releases = release() | [release()]
1313 Xref = xref()
1314 Removes releases and their applications, modules and module data
1316 from an Xref server.
1317 replace_application(Xref, Application, Directory [, Options]) -> {ok,
1319 application()} | Error
1320 Types:
1322 Application = application()
1324 Directory = directory()
1325 Error = {error, module(), Reason}
1326 Options = [Option] | Option
1327 Option = {builtins, bool()} | {verbose, bool()} | {warnings,
1328 bool()}
1329 Reason = {no_such_application, application()} | - see also
1330 add_application -
1331 Xref = xref()
1332 Replaces the modules of an application with other modules read
1334 from an application directory. Release membership of the appli‐
1335 cation is retained. Note that the name of the application is
1336 kept; the name of the given directory is not used.
1337 replace_module(Xref, Module, File [, Options]) -> {ok, module()} |
1339 Error
1340 Types:
1342 Error = {error, module(), Reason}
1344 File = file()
1345 Module = module()
1346 Options = [Option] | Option
1347 Option = {verbose, bool()} | {warnings, bool()}
1348 ReadModule = module()
1349 Reason = {module_mismatch, module(), ReadModule} |
1350 {no_such_module, module()} | - see also add_module -
1351 Xref = xref()
1352 Replaces module data of an analyzed module with data read from a
1354 BEAM file. Application membership of the module is retained, and
1355 so is the value of the builtins option of the module. An error
1356 is returned if the name of the read module differs from the
1357 given module.
1358 The update function is an alternative for updating module data
1360 of recompiled modules.
1361 set_default(Xref, Option, Value) -> {ok, OldValue} | Error
1363 set_default(Xref, OptionValues) -> ok | Error
1364 Types:
1366 Error = {error, module(), Reason}
1368 OptionValues = [OptionValue] | OptionValue
1369 OptionValue = {Option, Value}
1370 Option = builtins | recurse | verbose | warnings
1371 Reason = {invalid_options, term()}
1372 Value = bool()
1373 Xref = xref()
1374 Sets the default value of one or more options. The options that
1376 can be set this way are:
1377 * builtins, with initial default value false;
1379 * recurse, with initial default value false;
1381 * verbose, with initial default value false;
1383 * warnings, with initial default value true.
1385 The initial default values are set when creating an Xref server.
1387 set_library_path(Xref, LibraryPath [, Options]) -> ok | Error
1389 Types:
1391 Error = {error, module(), Reason}
1393 LibraryPath = library_path()
1394 Options = [Option] | Option
1395 Option = {verbose, bool()}
1396 Reason = {invalid_options, term()} | {invalid_path, term()}
1397 Xref = xref()
1398 Sets the library path. If the given path is a list of directo‐
1400 ries, the set of library modules is determined by choosing the
1401 first module encountered while traversing the directories in the
1402 given order, for those modules that occur in more than one
1403 directory. By default, the library path is an empty list.
1404 The library path code_path is used by the functions m/1 and d/1,
1406 but can also be set explicitly. Note however that the code path
1407 will be traversed once for each used library module while set‐
1408 ting up module data. On the other hand, if there are only a few
1409 modules that are used but not analyzed, using code_path may be
1410 faster than setting the library path to code:get_path().
1411 If the library path is set to code_path, the set of library mod‐
1413 ules is not determined, and the info functions will return empty
1414 lists of library modules.
1415 start(NameOrOptions) -> Return
1417 Types:
1419 NameOrOptions = Name | Options
1421 Name = atom()
1422 Options = [Option] | Option
1423 Option = {xref_mode, mode()} | term()
1424 Return = {ok, pid()} | {error, {already_started, pid()}}
1425 Creates an Xref server. The process may optionally be given a
1427 name. The default mode is functions. Options that are not recog‐
1428 nized by Xref are passed on to gen_server:start/4.
1429 start(Name, Options) -> Return
1431 Types:
1433 Name = atom()
1435 Options = [Option] | Option
1436 Option = {xref_mode, mode()} | term()
1437 Return = {ok, pid()} | {error, {already_started, pid()}}
1438 Creates an Xref server with a given name. The default mode is
1440 functions. Options that are not recognized by Xref are passed on
1441 to gen_server:start/4.
1442 stop(Xref)
1444 Types:
1446 Xref = xref()
1448 Stops an Xref server.
1450 update(Xref [, Options]) -> {ok, Modules} | Error
1452 Types:
1454 Error = {error, module(), Reason}
1456 Modules = [module()]
1457 Options = [Option] | Option
1458 Option = {verbose, bool()} | {warnings, bool()}
1459 Reason = {invalid_options, term()} | {module_mismatch, mod‐
1460 ule(), ReadModule} | - see also add_module -
1461 Xref = xref()
1462 Replaces the module data of all analyzed modules the BEAM files
1464 of which have been modified since last read by an add function
1465 or update. Application membership of the modules is retained,
1466 and so is the value of the builtins option. Returns a sorted
1467 list of the names of the replaced modules.
1468 variables(Xref [, Options]) -> {ok, [VariableInfo]}
1470 Types:
1472 Options = [Option] | Option
1474 Option = predefined | user | {verbose, bool()}
1475 Reason = {invalid_options, term()}
1476 VariableInfo = {predefined, [variable()]} | {user, [vari‐
1477 able()]}
1478 Xref = xref()
1479 Returns a sorted lists of the names of the variables of an Xref
1481 server. The default is to return the user variables only.
1482
1484 beam_lib(3), digraph(3), digraph_utils(3), re(3), TOOLS User's Guide
1485Ericsson AB tools 3.4.4 xref(3)