Mix.Task behaviour View Source

A simple module that provides conveniences for creating, loading and manipulating tasks.

A Mix task can be defined by simply using Mix.Task in a module starting with Mix.Tasks. and defining the run/1 function:

defmodule Mix.Tasks.Echo do
  use Mix.Task

  @impl Mix.Task
  def run(args) do
    Mix.shell.info Enum.join(args, " ")
  end
end

The run/1 function will receive a list of all arguments passed to the command line.

Attributes

There are a few attributes available in Mix tasks to configure them in Mix:

  • @shortdoc - makes the task public with a short description that appears on mix help
  • @recursive - runs the task recursively in umbrella projects
  • @preferred_cli_env - recommends environment to run task. It is used in absence of a Mix project recommendation, or explicit MIX_ENV, and it only works for tasks in the current project. @preferred_cli_env is not loaded from dependencies as we need to know the environment before dependencies are loaded.

Documentation

Users can read the documentation for public Mix tasks by running mix help my_task. The documentation that will be shown is the @moduledoc of the task's module.

Link to this section Summary

Functions

Checks if an alias called task exists

Returns all loaded task modules

Clears all invoked tasks, allowing them to be reinvoked

Receives a task name and returns the task module if found

Receives a task name and retrieves the task module

Loads all tasks in all code paths

Loads all tasks in the given paths

Gets the moduledoc for the given task module

Gets preferred CLI environment for the task

Indicates if the current task is recursing

Checks if the task should be run recursively for all sub-apps in umbrella projects

Reenables a given task so it can be executed again down the stack

Reruns task with the given arguments

Runs a task with the given args

Gets the shortdoc for the given task module

Returns true if given module is a task

Returns the task name for the given module

Callbacks

A task needs to implement run which receives a list of command line args

Link to this section Types

Link to this type

task_module() View Source
task_module() :: atom()

Link to this type

task_name() View Source
task_name() :: String.t() | atom()

Link to this section Functions

Checks if an alias called task exists.

For more information about task aliasing, take a look at the "Aliasing" section in the docs for Mix.

Link to this function

all_modules() View Source
all_modules() :: [task_module()]

Returns all loaded task modules.

Modules that are not yet loaded won't show up. Check load_all/0 if you want to preload all tasks.

Clears all invoked tasks, allowing them to be reinvoked.

This operation is not recursive.

Receives a task name and returns the task module if found.

Otherwise returns nil in case the module exists, but it isn't a task or cannot be found.

Receives a task name and retrieves the task module.

Exceptions

Loads all tasks in all code paths.

Link to this function

load_tasks(dirs) View Source
load_tasks([List.Chars.t()]) :: [task_module()]

Loads all tasks in the given paths.

Link to this function

moduledoc(module) View Source
moduledoc(task_module()) :: String.t() | nil | false

Gets the moduledoc for the given task module.

Returns the moduledoc or nil.

Link to this function

preferred_cli_env(task) View Source
preferred_cli_env(task_name()) :: atom() | nil

Gets preferred CLI environment for the task.

Returns environment (for example, :test, or :prod), or nil.

Link to this function

recursing?() View Source (since 1.8.0)
recursing?() :: boolean()

Indicates if the current task is recursing.

This returns true if a task is marked as recursive and it is being executed inside an umbrella project.

Link to this function

recursive(module) View Source
recursive(task_module()) :: boolean()

Checks if the task should be run recursively for all sub-apps in umbrella projects.

Returns true or false.

Link to this function

reenable(task) View Source
reenable(task_name()) :: :ok

Reenables a given task so it can be executed again down the stack.

Both alias and the regular stack are reenabled when this function is called.

If an umbrella project reenables a task, it is reenabled for all child projects.

Link to this function

rerun(task, args \\ []) View Source
rerun(task_name(), [any()]) :: any()

Reruns task with the given arguments.

This function reruns the given task; to do that, it first re-enables the task and then runs it as normal.

Link to this function

run(task, args \\ []) View Source
run(task_name(), [any()]) :: any()

Runs a task with the given args.

If the task was not yet invoked, it runs the task and returns the result.

If there is an alias with the same name, the alias will be invoked instead of the original task.

If the task or alias were already invoked, it does not run them again and simply aborts with :noop.

It may raise an exception if an alias or a task can't be found or the task is invalid. Check get!/1 for more information.

Link to this function

shortdoc(module) View Source
shortdoc(task_module()) :: String.t() | nil

Gets the shortdoc for the given task module.

Returns the shortdoc or nil.

Returns true if given module is a task.

Returns the task name for the given module.

Link to this section Callbacks

Link to this callback

run(command_line_args) View Source
run(command_line_args :: [binary()]) :: any()

A task needs to implement run which receives a list of command line args.