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, in‐
15 clude 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). Un‐
21 resolved calls are calls to apply or spawn with variable module, vari‐
22 able function, or variable arguments. Examples are M:F(a), apply(M, f,
23 [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 ap‐
39 plication. Releases are collections of applications located in the lib
40 subdirectory of the release directory. There is more to read about ap‐
41 plications 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 de‐
51 bug_info contain so called debug information, which is an abstract rep‐
52 resentation of the code. In functions mode, which is the default mode,
53 function calls and line numbers are extracted from debug information.
54 In modules mode, debug information is ignored if present, but dependen‐
55 cies between modules are extracted from other parts of the BEAM files.
56 The modules mode is significantly less time and space consuming than
57 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 no‐
69 tion, 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 un‐
84 used 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 in‐
108 stance, the cross reference and the unknown functions are computed when
109 all module data are known. The functions that need complete data (ana‐
110 lyze, q, variables) take care of setting up data automatically. Module
111 data need to be set up (again) after calls to any of the add, replace,
112 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 ex‐
122 ported functions, but only when called from some module. The edges are
123 the function calls of all module data. A consequence of the edges being
124 a set is that there is only one edge if a function is locally or exter‐
125 nally 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 ac‐
208 tual chain of calls of some graph). Assigning a type to a list or tuple
209 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 as‐
230 signed 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 lo‐
284 cal 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 in‐
405 terpretation of the expression. If the named type is more special than
406 the expression type, say Fun and Mod, then the interpretation is the
407 set of all the functions of the modules (in modules mode, the conver‐
408 sion is partial since the local functions are not known). The conver‐
409 sions to and from applications and releases work analogously. For in‐
410 stance, (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 re‐
435 spectively: 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 re‐
465 striction 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 re‐
576 placing the function call with a line numbered function call, that is,
577 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 de‐
584 fined 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 re‐
635 moved by calls to forget. There are no user variables when module data
636 need to be set up again; if any of the functions that make it necessary
637 to set up module data again is called, all user variables are forgot‐
638 ten.
639
641 application() = atom()
642 call() = {atom(), atom()} | funcall()
644 constant() = xmfa() | module() | application() | release()
646 directory() = atom() | file:filename()
648 file() = file:filename()
650 file_error() = atom()
652 funcall() = {xmfa(), xmfa()}
654 function_name() = atom()
656 library() = atom()
658 library_path() = path() | code_path
660 mode() = functions | modules
662 path() = [file()]
664 release() = atom()
666 string_position() = integer() >= 1
668 variable() = atom()
670 xarity() = arity() | -1
672 xmfa() = {module(), function_name(), xarity()}
674 xref() = atom() | pid()
676
678 add_application(XrefServer, Directory) ->
679 {ok, application()} | {error, module(), Reason}
680 add_application(XrefServer, Directory, Options) ->
682 {ok, application()} | {error, module(), Reason}
683 Types:
685 XrefServer = xref()
687 Directory = directory()
688 Options = Option | [Option]
689 Option =
690 {builtins, boolean()} |
691 {name, application()} |
692 {verbose, boolean()} |
693 {warnings, boolean()} |
694 builtins | verbose | warnings
695 Reason =
696 {application_clash, {application(), directory(), direc‐
697 tory()}} |
698 add_dir_rsn()
699 add_dir_rsn() =
700 {file_error, file(), file_error()} |
701 {invalid_filename, term()} |
702 {invalid_options, term()} |
703 {unrecognized_file, file()} |
704 beam_lib:chnk_rsn()
705 Adds an application, the modules of the application and module
707 data of the modules to an Xref server. The modules will be mem‐
708 bers of the application. The default is to use the base name of
709 the directory with the version removed as application name, but
710 this can be overridden by the name option. Returns the name of
711 the application.
712 If the given directory has a subdirectory named ebin, modules
714 (BEAM files) are searched for in that directory, otherwise mod‐
715 ules are searched for in the given directory.
716 If the mode of the Xref server is functions, BEAM files that
718 contain no debug information are ignored.
719 add_directory(XrefServer, Directory) ->
721 {ok, Modules} | {error, module(), Reason}
722 add_directory(XrefServer, Directory, Options) ->
724 {ok, Modules} | {error, module(), Reason}
725 Types:
727 XrefServer = xref()
729 Directory = directory()
730 Options = Option | [Option]
731 Option =
732 {builtins, boolean()} |
733 {recurse, boolean()} |
734 {verbose, boolean()} |
735 {warnings, boolean()} |
736 builtins | recurse | verbose | warnings
737 Modules = [module()]
738 Reason = add_dir_rsn()
739 add_dir_rsn() =
740 {file_error, file(), file_error()} |
741 {invalid_filename, term()} |
742 {invalid_options, term()} |
743 {unrecognized_file, file()} |
744 beam_lib:chnk_rsn()
745 Adds the modules found in the given directory and the modules'
747 data to an Xref server. The default is not to examine subdirec‐
748 tories, but if the option recurse has the value true, modules
749 are searched for in subdirectories on all levels as well as in
750 the given directory. Returns a sorted list of the names of the
751 added modules.
752 The modules added will not be members of any applications.
754 If the mode of the Xref server is functions, BEAM files that
756 contain no debug information are ignored.
757 add_module(XrefServer, File) ->
759 {ok, module()} | {error, module(), Reason}
760 add_module(XrefServer, File, Options) ->
762 {ok, module()} | {error, module(), Reason}
763 Types:
765 XrefServer = xref()
767 File = file:filename()
768 Options = Option | [Option]
769 Option =
770 {builtins, boolean()} |
771 {verbose, boolean()} |
772 {warnings, boolean()} |
773 builtins | verbose | warnings
774 Reason = add_mod_rsn()
775 add_mod_rsn() =
776 {file_error, file(), file_error()} |
777 {invalid_filename, term()} |
778 {invalid_options, term()} |
779 {module_clash, {module(), file(), file()}} |
780 {no_debug_info, file()} |
781 beam_lib:chnk_rsn()
782 Adds a module and its module data to an Xref server. The module
784 will not be member of any application. Returns the name of the
785 module.
786 If the mode of the Xref server is functions, and the BEAM file
788 contains no debug information, the error message no_debug_info
789 is returned.
790 add_release(XrefServer, Directory) ->
792 {ok, release()} | {error, module(), Reason}
793 add_release(XrefServer, Directory, Options) ->
795 {ok, release()} | {error, module(), Reason}
796 Types:
798 XrefServer = xref()
800 Directory = directory()
801 Options = Option | [Option]
802 Option =
803 {builtins, boolean()} |
804 {name, release()} |
805 {verbose, boolean()} |
806 {warnings, boolean()} |
807 builtins | verbose | warnings
808 Reason =
809 {application_clash, {application(), directory(), direc‐
810 tory()}} |
811 {release_clash, {release(), directory(), directory()}} |
812 add_dir_rsn()
813 add_dir_rsn() =
814 {file_error, file(), file_error()} |
815 {invalid_filename, term()} |
816 {invalid_options, term()} |
817 {unrecognized_file, file()} |
818 beam_lib:chnk_rsn()
819 Adds a release, the applications of the release, the modules of
821 the applications, and module data of the modules to an Xref
822 server. The applications will be members of the release, and the
823 modules will be members of the applications. The default is to
824 use the base name of the directory as release name, but this can
825 be overridden by the name option. Returns the name of the re‐
826 lease.
827 If the given directory has a subdirectory named lib, the direc‐
829 tories in that directory are assumed to be application directo‐
830 ries, otherwise all subdirectories of the given directory are
831 assumed to be application directories. If there are several ver‐
832 sions of some application, the one with the highest version is
833 chosen.
834 If the mode of the Xref server is functions, BEAM files that
836 contain no debug information are ignored.
837 analyze(XrefServer, Analysis) ->
839 {ok, Answer} | {error, module(), Reason}
840 analyze(XrefServer, Analysis, Options) ->
842 {ok, Answer} | {error, module(), Reason}
843 Types:
845 XrefServer = xref()
847 Analysis = analysis()
848 Options = Option | [Option]
849 Option = {verbose, boolean()} | verbose
850 Answer = [term()]
851 Reason = analyze_rsn()
852 analysis() =
853 undefined_function_calls | undefined_functions |
854 locals_not_used | exports_not_used |
855 deprecated_function_calls |
856 {deprecated_function_calls, DeprFlag :: depr_flag()} |
857 deprecated_functions |
858 {deprecated_functions, DeprFlag :: depr_flag()} |
859 {call, FuncSpec :: func_spec()} |
860 {use, FuncSpec :: func_spec()} |
861 {module_call, ModSpec :: mod_spec()} |
862 {module_use, ModSpec :: mod_spec()} |
863 {application_call, AppSpec :: app_spec()} |
864 {application_use, AppSpec :: app_spec()} |
865 {release_call, RelSpec :: rel_spec()} |
866 {release_use, RelSpec :: rel_spec()}
867 app_spec() = application() | [application()]
868 depr_flag() = next_version | next_major_release | eventually
869 func_spec() = xmfa() | [xmfa()]
870 mod_spec() = module() | [module()]
871 rel_spec() = release() | [release()]
872 analyze_rsn() =
873 {invalid_options, term()} |
874 {parse_error, string_position(), term()} |
875 {unavailable_analysis, term()} |
876 {unknown_analysis, term()} |
877 {unknown_constant, string()} |
878 {unknown_variable, variable()}
879 Evaluates a predefined analysis. Returns a sorted list without
881 duplicates of call() or constant(), depending on the chosen
882 analysis. The predefined analyses, which operate on all analyzed
883 modules, are (analyses marked with (*) are available in func‐
884 tionsmode only):
885 undefined_function_calls(*):
887 Returns a list of calls to undefined functions.
888 undefined_functions:
890 Returns a list of undefined functions.
891 locals_not_used(*):
893 Returns a list of local functions that have not been locally
894 used.
895 exports_not_used:
897 Returns a list of exported functions that have not been ex‐
898 ternally used. Note that in modules mode, M:behaviour_info/1
899 is never reported as unused.
900 deprecated_function_calls(*):
902 Returns a list of external calls to deprecated functions.
903 {deprecated_function_calls, DeprFlag}(*):
905 Returns a list of external calls to deprecated functions. If
906 DeprFlag is equal to next_version, calls to functions to be
907 removed in next version are returned. If DeprFlag is equal
908 to next_major_release, calls to functions to be removed in
909 next major release are returned as well as calls to func‐
910 tions to be removed in next version. Finally, if DeprFlag is
911 equal to eventually, all calls to functions to be removed
912 are returned, including calls to functions to be removed in
913 next version or next major release.
914 deprecated_functions:
916 Returns a list of externally used deprecated functions.
917 {deprecated_functions, DeprFlag}:
919 Returns a list of externally used deprecated functions. If
920 DeprFlag is equal to next_version, functions to be removed
921 in next version are returned. If DeprFlag is equal to
922 next_major_release, functions to be removed in next major
923 release are returned as well as functions to be removed in
924 next version. Finally, if DeprFlag is equal to eventually,
925 all functions to be removed are returned, including func‐
926 tions to be removed in next version or next major release.
927 {call, FuncSpec}(*):
929 Returns a list of functions called by some of the given
930 functions.
931 {use, FuncSpec}(*):
933 Returns a list of functions that use some of the given func‐
934 tions.
935 {module_call, ModSpec}:
937 Returns a list of modules called by some of the given mod‐
938 ules.
939 {module_use, ModSpec}:
941 Returns a list of modules that use some of the given mod‐
942 ules.
943 {application_call, AppSpec}:
945 Returns a list of applications called by some of the given
946 applications.
947 {application_use, AppSpec}:
949 Returns a list of applications that use some of the given
950 applications.
951 {release_call, RelSpec}:
953 Returns a list of releases called by some of the given re‐
954 leases.
955 {release_use, RelSpec}:
957 Returns a list of releases that use some of the given re‐
958 leases.
959 d(Directory) ->
961 [DebugInfoResult] |
962 [NoDebugInfoResult] |
963 {error, module(), Reason}
964 Types:
966 Directory = directory()
968 DebugInfoResult =
969 {deprecated, [funcall()]} |
970 {undefined, [funcall()]} |
971 {unused, [mfa()]}
972 NoDebugInfoResult =
973 {deprecated, [xmfa()]} | {undefined, [xmfa()]}
974 Reason =
975 {file_error, file(), file_error()} |
976 {invalid_filename, term()} |
977 {unrecognized_file, file()} |
978 beam_lib:chnk_rsn()
979 The modules found in the given directory are checked for calls
981 to deprecated functions, calls to undefined functions, and for
982 unused local functions. The code path is used as library path.
983 If some of the found BEAM files contain debug information, then
985 those modules are checked and a list of tuples is returned. The
986 first element of each tuple is one of:
987 * deprecated, the second element is a sorted list of calls to
989 deprecated functions;
990 * undefined, the second element is a sorted list of calls to
992 undefined functions;
993 * unused, the second element is a sorted list of unused local
995 functions.
996 If no BEAM file contains debug information, then a list of tu‐
998 ples is returned. The first element of each tuple is one of:
999 * deprecated, the second element is a sorted list of exter‐
1001 nally used deprecated functions;
1002 * undefined, the second element is a sorted list of undefined
1004 functions.
1005 forget(XrefServer) -> ok
1007 forget(XrefServer, Variables) -> ok | {error, module(), Reason}
1009 Types:
1011 XrefServer = xref()
1013 Variables = variable() | [variable()]
1014 Reason = {not_user_variable, term()}
1015 forget/1 and forget/2 remove all or some of the user variables
1017 of an Xref server.
1018 format_error(Error) -> io_lib:chars()
1020 Types:
1022 Error = {error, module(), Reason :: term()}
1024 Given the error returned by any function of this module, the
1026 function format_error returns a descriptive string of the error
1027 in English. For file errors, the function file:format_error/1 is
1028 called.
1029 get_default(XrefServer) -> [{Option, Value}]
1031 get_default(XrefServer, Option) ->
1033 {ok, Value} | {error, module(), Reason}
1034 Types:
1036 XrefServer = xref()
1038 Option = builtins | recurse | verbose | warnings
1039 Value = boolean()
1040 Reason = {invalid_options, term()}
1041 Returns the default values of one or more options.
1043 get_library_path(XrefServer) -> {ok, LibraryPath}
1045 Types:
1047 XrefServer = xref()
1049 LibraryPath = library_path()
1050 Returns the library path.
1052 info(XrefServer) -> [Info]
1054 info(XrefServer, Category) ->
1056 [{Item, [Info]}] |
1057 {error, module(), {no_such_info, Category}}
1058 info(XrefServer, Category, Items) ->
1060 [{Item, [Info]}] | {error, module(), Reason}
1061 Types:
1063 XrefServer = xref()
1065 Category = modules | applications | releases | libraries
1066 Items = Item | [Item]
1067 Item = module() | application() | release() | library()
1068 Info = info()
1069 Reason =
1070 {no_such_application, Item} |
1071 {no_such_info, Category} |
1072 {no_such_library, Item} |
1073 {no_such_module, Item} |
1074 {no_such_release, Item}
1075 info() =
1076 {application, Application :: [application()]} |
1077 {builtins, boolean()} |
1078 {directory, directory()} |
1079 {library_path, library_path()} |
1080 {mode, mode()} |
1081 {no_analyzed_modules, integer() >= 0} |
1082 {no_applications, integer() >= 0} |
1083 {no_calls,
1084 {NoResolved :: integer() >= 0,
1085 NoUnresolved :: integer() >= 0}} |
1086 {no_function_calls,
1087 {NoLocal :: integer() >= 0,
1088 NoResolvedExternal :: integer() >= 0,
1089 NoUnresolved :: integer() >= 0}} |
1090 {no_functions,
1091 {NoLocal :: integer() >= 0,
1092 NoExternal :: integer() >= 0}} |
1093 {no_inter_function_calls, integer() >= 0} |
1094 {no_releases, integer() >= 0} |
1095 {release, Release :: [release()]} |
1096 {version, Version :: [integer() >= 0]}
1097 The info functions return information as a list of pairs {Tag,
1099 term()} in some order about the state and the module data of an
1100 Xref server.
1101 info/1 returns information with the following tags (tags marked
1103 with (*) are available in functions mode only):
1104 * library_path, the library path;
1106 * mode, the mode;
1108 * no_releases, number of releases;
1110 * no_applications, total number of applications (of all re‐
1112 leases);
1113 * no_analyzed_modules, total number of analyzed modules;
1115 * no_calls (*), total number of calls (in all modules), re‐
1117 garding instances of one function call in different lines as
1118 separate calls;
1119 * no_function_calls (*), total number of local calls, resolved
1121 external calls and unresolved calls;
1122 * no_functions (*), total number of local and exported func‐
1124 tions;
1125 * no_inter_function_calls (*), total number of calls of the
1127 Inter Call Graph.
1128 info/2 and info/3 return information about all or some of the
1130 analyzed modules, applications, releases or library modules of
1131 an Xref server. The following information is returned for every
1132 analyzed module:
1133 * application, an empty list if the module does not belong to
1135 any application, otherwise a list of the application name;
1136 * builtins, whether calls to BIFs are included in the module's
1138 data;
1139 * directory, the directory where the module's BEAM file is lo‐
1141 cated;
1142 * no_calls (*), number of calls, regarding instances of one
1144 function call in different lines as separate calls;
1145 * no_function_calls (*), number of local calls, resolved ex‐
1147 ternal calls and unresolved calls;
1148 * no_functions (*), number of local and exported functions;
1150 * no_inter_function_calls (*), number of calls of the Inter
1152 Call Graph;
1153 The following information is returned for every application:
1155 * directory, the directory where the modules' BEAM files are
1157 located;
1158 * no_analyzed_modules, number of analyzed modules;
1160 * no_calls (*), number of calls of the application's modules,
1162 regarding instances of one function call in different lines
1163 as separate calls;
1164 * no_function_calls (*), number of local calls, resolved ex‐
1166 ternal calls and unresolved calls of the application's mod‐
1167 ules;
1168 * no_functions (*), number of local and exported functions of
1170 the application's modules;
1171 * no_inter_function_calls (*), number of calls of the Inter
1173 Call Graph of the application's modules;
1174 * release, an empty list if the application does not belong to
1176 any release, otherwise a list of the release name;
1177 * version, the application's version as a list of numbers. For
1179 instance, the directory "kernel-2.6" results in the applica‐
1180 tion name kernel and the application version [2,6]; "kernel"
1181 yields the name kernel and the version [].
1182 The following information is returned for every release:
1184 * directory, the release directory;
1186 * no_analyzed_modules, number of analyzed modules;
1188 * no_applications, number of applications;
1190 * no_calls (*), number of calls of the release's modules, re‐
1192 garding instances of one function call in different lines as
1193 separate calls;
1194 * no_function_calls (*), number of local calls, resolved ex‐
1196 ternal calls and unresolved calls of the release's modules;
1197 * no_functions (*), number of local and exported functions of
1199 the release's modules;
1200 * no_inter_function_calls (*), number of calls of the Inter
1202 Call Graph of the release's modules.
1203 The following information is returned for every library module:
1205 * directory, the directory where the library module's BEAM
1207 file is located.
1208 For every number of calls, functions etc. returned by the no_
1210 tags, there is a query returning the same number. Listed below
1211 are examples of such queries. Some of the queries return the sum
1212 of a two or more of the no_ tags numbers. mod (app, rel) refers
1213 to any module (application, release).
1214 * no_analyzed_modules
1216 * "# AM" (info/1)
1218 * "# (Mod) app:App" (application)
1220 * "# (Mod) rel:Rel" (release)
1222 * no_applications
1224 * "# A" (info/1)
1226 * no_calls. The sum of the number of resolved and unresolved
1228 calls:
1229 * "# (XLin) E + # (LLin) E" (info/1)
1231 * "T = E | mod:Mod, # (LLin) T + # (XLin) T" (module)
1233 * "T = E | app:App, # (LLin) T + # (XLin) T" (application)
1235 * "T = E | rel:Rel, # (LLin) T + # (XLin) T" (release)
1237 * no_functions. Functions in library modules and the functions
1239 module_info/0,1 are not counted by info. Assuming that "Ex‐
1240 tra := _:module_info/\"(0|1)\" + LM" has been evaluated, the
1241 sum of the number of local and exported functions are:
1242 * "# (F - Extra)" (info/1)
1244 * "# (F * mod:Mod - Extra)" (module)
1246 * "# (F * app:App - Extra)" (application)
1248 * "# (F * rel:Rel - Extra)" (release)
1250 * no_function_calls. The sum of the number of local calls, re‐
1252 solved external calls and unresolved calls:
1253 * "# LC + # XC" (info/1)
1255 * "# LC | mod:Mod + # XC | mod:Mod" (module)
1257 * "# LC | app:App + # XC | app:App" (application)
1259 * "# LC | rel:Rel + # XC | mod:Rel" (release)
1261 * no_inter_function_calls
1263 * "# EE" (info/1)
1265 * "# EE | mod:Mod" (module)
1267 * "# EE | app:App" (application)
1269 * "# EE | rel:Rel" (release)
1271 * no_releases
1273 * "# R" (info/1)
1275 m(FileOrModule) ->
1277 [DebugInfoResult] |
1278 [NoDebugInfoResult] |
1279 {error, module(), Reason}
1280 Types:
1282 FileOrModule = file:filename() | module()
1284 DebugInfoResult =
1285 {deprecated, [funcall()]} |
1286 {undefined, [funcall()]} |
1287 {unused, [mfa()]}
1288 NoDebugInfoResult =
1289 {deprecated, [xmfa()]} | {undefined, [xmfa()]}
1290 Reason =
1291 {cover_compiled, Module} |
1292 {file_error, file(), file_error()} |
1293 {interpreted, Module} |
1294 {invalid_filename, term()} |
1295 {no_such_module, Module} |
1296 beam_lib:chnk_rsn()
1297 The given BEAM file (with or without the .beam extension) or the
1299 file found by calling code:which(Module) is checked for calls to
1300 deprecated functions, calls to undefined functions, and for un‐
1301 used local functions. The code path is used as library path.
1302 If the BEAM file contains debug information, then a list of tu‐
1304 ples is returned. The first element of each tuple is one of:
1305 * deprecated, the second element is a sorted list of calls to
1307 deprecated functions;
1308 * undefined, the second element is a sorted list of calls to
1310 undefined functions;
1311 * unused, the second element is a sorted list of unused local
1313 functions.
1314 If the BEAM file does not contain debug information, then a list
1316 of tuples is returned. The first element of each tuple is one
1317 of:
1318 * deprecated, the second element is a sorted list of exter‐
1320 nally used deprecated functions;
1321 * undefined, the second element is a sorted list of undefined
1323 functions.
1324 q(XrefServer, Query) -> {ok, Answer} | {error, module(), Reason}
1326 q(XrefServer, Query, Options) ->
1328 {ok, Answer} | {error, module(), Reason}
1329 Types:
1331 XrefServer = xref()
1333 Query = string() | atom()
1334 Options = Option | [Option]
1335 Option = {verbose, boolean()} | verbose
1336 Answer = answer()
1337 Reason = q_rsn()
1338 answer() =
1339 false |
1340 [constant()] |
1341 [(Call :: call()) |
1342 (ComponentCall :: {component(), component()})] |
1343 [Component :: component()] |
1344 integer() >= 0 |
1345 [DefineAt :: define_at()] |
1346 [CallAt :: {funcall(), LineNumbers :: [integer() >= 0]}] |
1347 [AllLines ::
1348 {{define_at(), define_at()},
1349 LineNumbers :: [integer() >= 0]}]
1350 define_at() = {xmfa(), LineNumber :: integer() >= 0}
1351 component() = [constant()]
1352 q_rsn() =
1353 {invalid_options, term()} |
1354 {parse_error, string_position(), term()} |
1355 {type_error, string()} |
1356 {type_mismatch, string(), string()} |
1357 {unknown_analysis, term()} |
1358 {unknown_constant, string()} |
1359 {unknown_variable, variable()} |
1360 {variable_reassigned, string()}
1361 Evaluates a query in the context of an Xref server, and returns
1363 the value of the last statement. The syntax of the value depends
1364 on the expression:
1365 * A set of calls is represented by a sorted list without du‐
1367 plicates of call().
1368 * A set of constants is represented by a sorted list without
1370 duplicates of constant().
1371 * A set of strongly connected components is a sorted list
1373 without duplicates of Component.
1374 * A set of calls between strongly connected components is a
1376 sorted list without duplicates of ComponentCall.
1377 * A chain of calls is represented by a list of constant(). The
1379 list contains the From vertex of every call and the To ver‐
1380 tex of the last call.
1381 * The of operator returns false if no chain of calls between
1383 the given constants can be found.
1384 * The value of the closure operator (the digraph representa‐
1386 tion) is represented by the atom 'closure()'.
1387 * A set of line numbered functions is represented by a sorted
1389 list without duplicates of DefineAt.
1390 * A set of line numbered function calls is represented by a
1392 sorted list without duplicates of CallAt.
1393 * A set of line numbered functions and function calls is rep‐
1395 resented by a sorted list without duplicates of AllLines.
1396 For both CallAt and AllLines it holds that for no list element
1398 is LineNumbers an empty list; such elements have been removed.
1399 The constants of component and the integers of LineNumbers are
1400 sorted and without duplicates.
1401 remove_application(XrefServer, Applications) ->
1403 ok | {error, module(), Reason}
1404 Types:
1406 XrefServer = xref()
1408 Applications = application() | [application()]
1409 Reason = {no_such_application, application()}
1410 Removes applications and their modules and module data from an
1412 Xref server.
1413 remove_module(XrefServer, Modules) ->
1415 ok | {error, module(), Reason}
1416 Types:
1418 XrefServer = xref()
1420 Modules = module() | [module()]
1421 Reason = {no_such_module, module()}
1422 Removes analyzed modules and module data from an Xref server.
1424 remove_release(XrefServer, Releases) ->
1426 ok | {error, module(), Reason}
1427 Types:
1429 XrefServer = xref()
1431 Releases = release() | [release()]
1432 Reason = {no_such_release, release()}
1433 Removes releases and their applications, modules and module data
1435 from an Xref server.
1436 replace_application(XrefServer, Application, Directory) ->
1438 {ok, Application} |
1439 {error, module(), Reason}
1440 replace_application(XrefServer, Application, Directory, Options) ->
1442 {ok, Application} |
1443 {error, module(), Reason}
1444 Types:
1446 XrefServer = xref()
1448 Application = application()
1449 Directory = directory()
1450 Options = Option | [Option]
1451 Option =
1452 {builtins, boolean()} |
1453 {verbose, boolean()} |
1454 {warnings, boolean()} |
1455 builtins | verbose | warnings
1456 Reason =
1457 {application_clash, {application(), directory(), direc‐
1458 tory()}} |
1459 {no_such_application, Application} |
1460 add_dir_rsn()
1461 add_dir_rsn() =
1462 {file_error, file(), file_error()} |
1463 {invalid_filename, term()} |
1464 {invalid_options, term()} |
1465 {unrecognized_file, file()} |
1466 beam_lib:chnk_rsn()
1467 Replaces the modules of an application with other modules read
1469 from an application directory. Release membership of the appli‐
1470 cation is retained. Note that the name of the application is
1471 kept; the name of the given directory is not used.
1472 replace_module(XrefServer, Module, File) ->
1474 {ok, Module} | {error, module(), Reason}
1475 replace_module(XrefServer, Module, File, Options) ->
1477 {ok, Module} | {error, module(), Reason}
1478 Types:
1480 XrefServer = xref()
1482 Module = module()
1483 File = file()
1484 Options = Option | [Option]
1485 Option =
1486 {verbose, boolean()} |
1487 {warnings, boolean()} |
1488 verbose | warnings
1489 Reason =
1490 {module_mismatch, Module, ReadModule :: module()} |
1491 {no_such_module, Module} |
1492 add_mod_rsn()
1493 add_mod_rsn() =
1494 {file_error, file(), file_error()} |
1495 {invalid_filename, term()} |
1496 {invalid_options, term()} |
1497 {module_clash, {module(), file(), file()}} |
1498 {no_debug_info, file()} |
1499 beam_lib:chnk_rsn()
1500 Replaces module data of an analyzed module with data read from a
1502 BEAM file. Application membership of the module is retained, and
1503 so is the value of the builtins option of the module. An error
1504 is returned if the name of the read module differs from the
1505 given module.
1506 The update function is an alternative for updating module data
1508 of recompiled modules.
1509 set_default(XrefServer, Option, Value) ->
1511 {ok, OldValue} | {error, module(), Reason}
1512 set_default(XrefServer, OptionValues) ->
1514 ok | {error, module(), Reason}
1515 Types:
1517 XrefServer = xref()
1519 OptionValues = OptionValue | [OptionValue]
1520 OptionValue = {Option, Value}
1521 Option = builtins | recurse | verbose | warnings
1522 Value = boolean()
1523 Reason = {invalid_options, term()}
1524 Sets the default value of one or more options. The options that
1526 can be set this way are:
1527 * builtins, with initial default value false;
1529 * recurse, with initial default value false;
1531 * verbose, with initial default value false;
1533 * warnings, with initial default value true.
1535 The initial default values are set when creating an Xref server.
1537 set_library_path(XrefServer, LibraryPath) ->
1539 ok | {error, module(), Reason}
1540 set_library_path(XrefServer, LibraryPath, Options) ->
1542 ok | {error, module(), Reason}
1543 Types:
1545 XrefServer = xref()
1547 LibraryPath = library_path()
1548 Options = Option | [Option]
1549 Option = {verbose, boolean()} | verbose
1550 Reason = {invalid_options, term()} | {invalid_path, term()}
1551 Sets the library path. If the given path is a list of directo‐
1553 ries, the set of library modules is determined by choosing the
1554 first module encountered while traversing the directories in the
1555 given order, for those modules that occur in more than one di‐
1556 rectory. By default, the library path is an empty list.
1557 The library path code_path is used by the functions m/1 and d/1,
1559 but can also be set explicitly. Note however that the code path
1560 will be traversed once for each used library module while set‐
1561 ting up module data. On the other hand, if there are only a few
1562 modules that are used but not analyzed, using code_path may be
1563 faster than setting the library path to code:get_path().
1564 If the library path is set to code_path, the set of library mod‐
1566 ules is not determined, and the info functions will return empty
1567 lists of library modules.
1568 start(NameOrOptions) ->
1570 {ok, pid()} | {error, {already_started, pid()}}
1571 Types:
1573 NameOrOptions = Name | Options
1575 Name = atom()
1576 Options = Option | [Option]
1577 Option = {xref_mode, mode()} | term()
1578 Creates an Xref server. The process may optionally be given a
1580 name. The default mode is functions. Options that are not recog‐
1581 nized by Xref are passed on to gen_server:start/4.
1582 start(Name, Options) ->
1584 {ok, pid()} | {error, {already_started, pid()}}
1585 Types:
1587 Name = atom()
1589 Options = Option | [Option]
1590 Option = {xref_mode, mode()} | term()
1591 Creates an Xref server with a given name. The default mode is
1593 functions. Options that are not recognized by Xref are passed on
1594 to gen_server:start/4.
1595 stop(XrefServer) -> stopped
1597 Types:
1599 XrefServer = xref()
1601 Stops an Xref server.
1603 update(XrefServer) -> {ok, Modules} | {error, module(), Reason}
1605 update(XrefServer, Options) ->
1607 {ok, Modules} | {error, module(), Reason}
1608 Types:
1610 XrefServer = xref()
1612 Options = Option | [Option]
1613 Option =
1614 {verbose, boolean()} |
1615 {warnings, boolean()} |
1616 verbose | warnings
1617 Modules = [module()]
1618 Reason =
1619 {module_mismatch, module(), ReadModule :: module()} |
1620 add_mod_rsn()
1621 add_mod_rsn() =
1622 {file_error, file(), file_error()} |
1623 {invalid_filename, term()} |
1624 {invalid_options, term()} |
1625 {module_clash, {module(), file(), file()}} |
1626 {no_debug_info, file()} |
1627 beam_lib:chnk_rsn()
1628 Replaces the module data of all analyzed modules the BEAM files
1630 of which have been modified since last read by an add function
1631 or update. Application membership of the modules is retained,
1632 and so is the value of the builtins option. Returns a sorted
1633 list of the names of the replaced modules.
1634 variables(XrefServer) -> {ok, [VariableInfo]}
1636 variables(XrefServer, Options) -> {ok, [VariableInfo]}
1638 Types:
1640 XrefServer = xref()
1642 Options = Option | [Option]
1643 Option = predefined | user | {verbose, boolean()} | verbose
1644 VariableInfo =
1645 {predefined, [variable()]} | {user, [variable()]}
1646 Returns a sorted lists of the names of the variables of an Xref
1648 server. The default is to return the user variables only.
1649
1651 beam_lib(3), digraph(3), digraph_utils(3), re(3), TOOLS User's Guide
1652Ericsson AB tools 3.5.1 xref(3)