Mix v1.15.0

View Source Mix.Task.Compiler behaviour (Mix v1.15.0)

This module defines the behaviour for a Mix task that does compilation.

A Mix compiler task can be defined by simply using Mix.Task.Compiler in a module whose name starts with Mix.Tasks.Compile. and defining the run/1 function:

defmodule Mix.Tasks.Compile.MyLanguage do
  use Mix.Task.Compiler

  def run(_args) do
    :ok
  end
end

The run/1 function returns an atom indicating the status of the compilation, and optionally can also return a list of "diagnostics" such as warnings or compilation errors. Doing this enables code editors to display issues inline without having to analyze the command-line output.

If the compiler uses manifest files to track stale sources, it should define manifests/0, and if it writes any output to disk it should also define clean/0.

A compiler supports the same attributes for configuration and documentation as a regular Mix task. See Mix.Task for more information.

Link to this section Summary

Types

status()

Callbacks

clean()

Removes build artifacts and manifests.

manifests()

Lists manifest files for the compiler.

run(list)

Receives command-line arguments and performs compilation. If it produces errors, warnings, or any other diagnostic information, it should return a tuple with the status and a list of diagnostics.

Functions

after_compiler(name, fun)

Adds a callback that runs after a given compiler.

Link to this section Types

Link to this type

status()

View Source 
@type status() :: :ok | :noop | :error

Link to this section Callbacks

Link to this callback

clean()

View Source (optional) 
@callback clean() :: any()

Removes build artifacts and manifests.

Link to this callback

manifests()

View Source (optional) 
@callback manifests() :: [Path.t()]

Lists manifest files for the compiler.

Link to this callback

run(list)

View Source 
@callback run([binary()]) :: status() | {status(), [Mix.Task.Compiler.Diagnostic.t()]}

Receives command-line arguments and performs compilation. If it produces errors, warnings, or any other diagnostic information, it should return a tuple with the status and a list of diagnostics.

Link to this section Functions

Link to this function

after_compiler(name, fun)

View Source (since 1.10.0) 
@spec after_compiler(
  atom(),
  ({status(), [Mix.Task.Compiler.Diagnostic.t()]} ->
     {status(), [Mix.Task.Compiler.Diagnostic.t()]})
) :: :ok

Adds a callback that runs after a given compiler.

The callback is invoked after the compiler runs and it receives a tuple with current status and the list of diagnostic. It must return the updated status and diagnostics.

If the given compiler does not run (for instance, because an earlier compiler in the stack has aborted), the callback will not be executed.