View Source Mix.Task behaviour (Mix v1.10.4)
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
endThe 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 onmix 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 explicitMIX_ENV, and it only works for tasks in the current project.@preferred_cli_envis 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
Callbacks
A task needs to implement run which receives
a list of command line args.
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.
Link to this section Types
@type task_module() :: atom()
Link to this section Callbacks
A task needs to implement run which receives
a list of command line args.
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.
@spec 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.
@spec clear() :: :ok
Clears all invoked tasks, allowing them to be reinvoked.
This operation is not recursive.
@spec get(task_name()) :: task_module() | nil
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.
@spec get!(task_name()) :: task_module()
Receives a task name and retrieves the task module.
Exceptions
Mix.NoTaskError- raised if the task could not be foundMix.InvalidTaskError- raised if the task is not a validMix.Task
@spec load_all() :: [task_module()]
Loads all tasks in all code paths.
@spec load_tasks([List.Chars.t()]) :: [task_module()]
Loads all tasks in the given paths.
@spec moduledoc(task_module()) :: String.t() | nil | false
Gets the moduledoc for the given task module.
Returns the moduledoc or nil.
Gets preferred CLI environment for the task.
Returns environment (for example, :test, or :prod), or nil.
@spec 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.
@spec recursive(task_module()) :: boolean()
Checks if the task should be run recursively for all sub-apps in umbrella projects.
Returns true or false.
@spec 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.
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.
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.
@spec shortdoc(task_module()) :: String.t() | nil
Gets the shortdoc for the given task module.
Returns the shortdoc or nil.
@spec task?(task_module()) :: boolean()
Returns true if given module is a task.
@spec task_name(task_module()) :: task_name()
Returns the task name for the given module.