mix xref

Performs cross reference checks between modules.

The unreachable and deprecated checks below happen every time your project is compiled via mix compile.xref. See Mix.Tasks.Compile.Xref for more information.

This task is automatically reenabled, so you can perform multiple cross reference checks in the same Mix invocation.

Xref modes

The xref task expects a mode as first argument:

mix xref MODE

All available modes are discussed below.

unreachable

Prints all unreachable "file:line: module.function/arity" entries:

mix xref unreachable

The "file:line" represents the file and line a call to an unknown "module.function/arity" is made.

The option --abort-if-any can be used for the command to fail if unreachable calls exist.

deprecated

Prints all deprecated "file:line: module.function/arity" entries:

mix xref deprecated

The "file:line" represents the file and line a call to a deprecated "module.function/arity" is made. This operation does not show deprecated local calls (a call to a deprecated function or macro in the same module) nor calls to deprecated functionality in Elixir itself.

The option --abort-if-any can be used for the command to fail if deprecated calls exist.

callers CALLEE

Prints all callers of the given CALLEE, which can be one of: Module, Module.function, or Module.function/arity. Examples:

mix xref callers MyMod
mix xref callers MyMod.fun
mix xref callers MyMod.fun/3

graph

Prints a file dependency graph where an edge from A to B indicates that A (source) depends on B (sink).

mix xref graph --format stats

The following options are accepted:

• --exclude - paths to exclude

• --label - only shows relationships with the given label The labels are "compile", "struct" and "runtime"

• --only-nodes - only shows the node names (no edges)

• --source - displays all files that the given source file references (directly or indirectly)

• --sink - displays all files that reference the given file (directly or indirectly)

• --format - can be set to one of:

  • pretty - prints the graph to the terminal using Unicode characters. Each prints each file followed by the files it depends on. This is the default except on Windows;

  • plain - the same as pretty except ASCII characters are used instead of Unicode characters. This is the default on Windows;

  • stats - prints general statistics about the graph;

  • dot - produces a DOT graph description in xref_graph.dot in the current directory. Warning: this will override any previously generated file

The --source and --sink options are particularly useful when trying to understand how the modules in a particular file interact with the whole system. You can combine those options with --label and --only-nodes to get all files that exhibit a certain property, for example:

# To get all files that depend on lib/foo.ex
mix xref graph --sink lib/foo.ex --only-nodes

# To get all files that depend on lib/foo.ex at compile time
mix xref graph --label compile --sink lib/foo.ex --only-nodes

# To show general statistics about the graph
mix xref graph --format stats

# To limit statistics only to certain labels
mix xref graph --format stats --label compile

Shared options

Those options are shared across all modes:

• --include-siblings - includes dependencies that have :in_umbrella set to true in the current project in the reports. This can be used to find callers or to analyze graphs between projects

• --no-compile - does not compile even if files require compilation

• --no-deps-check - does not check dependencies

• --no-archives-check - does not check archives

• --no-elixir-version-check - does not check the Elixir version from mix.exs

Configuration

All configuration for Xref should be placed under the key :xref.

• :exclude - a list of modules and {module, function, arity} tuples to ignore when checking cross references. For example: [MissingModule, {MissingModule2, :missing_func, 2}]

Summary

Functions

calls(opts \\ [])

Returns a list of information of all the function calls in the project.

Functions

calls(opts \\ [])

calls(keyword()) :: [
  %{
    callee: {module(), atom(), arity()},
    caller_module: module(),
    line: integer(),
    file: String.t()
  }
]

Returns a list of information of all the function calls in the project.

Each item in the list is a map with the following keys:

• :callee - a tuple containing the module, function, and arity of the call
• :line - an integer representing the line where the function is called
• :file - a binary representing the file where the function is called
• :caller_module - the module where the function is called

This function returns an empty list when used at the root of an umbrella project because there is no compile manifest to extract the function call information from. To get the function calls of each child in an umbrella, execute the function at the root of each individual application.