Mix.Task behaviour
Provides conveniences for creating, loading, and manipulating Mix tasks.
A Mix task can be defined by using Mix.Task
in a module whose name begins with Mix.Tasks.
and which defines the run/1
function. Typically, task modules live inside the lib/mix/tasks/
directory, and their file names use dot separators instead of underscores (e.g. deps.clean.ex
) - although ultimately the file name is not relevant.
For example:
# lib/mix/tasks/echo.ex defmodule Mix.Tasks.Echo do @moduledoc "Printed when the user requests `mix help echo`" @shortdoc "Echoes arguments" use Mix.Task @impl Mix.Task def run(args) do Mix.shell().info(Enum.join(args, " ")) end end
The command name will correspond to the portion of the module name following Mix.Tasks.
. For example, a module name of Mix.Tasks.Deps.Clean
corresponds to a task name of deps.clean
.
The run/1
function will receive a list of all command line arguments passed, according to the user's terminal.
For example, if the args
in the above echo
task were inspected, you might see something like this:
mix echo 'A and B' C --test ["A and B", "C", "--test"]
Define the @shortdoc
attribute if you wish to make the task publicly visible on mix help
. Omit this attribute if you do not want your task to be listed via mix help
.
If a task has requirements, they can be listed using the @requirements
attribute. For example:
@requirements ["app.config"]
Tasks typically depend on the "app.config"
task, when they need to access code from the current project with all apps already configured, or the "app.start" task, when they also need those apps to be already started:
@requirements ["app.start"]
You can also run tasks directly with run/2
.
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 -
@requirements
- list of required tasks to be run before the task -
@preferred_cli_env
- recommends an environment in which to run the task. It is used only ifMIX_ENV
is not yet set. Note@preferred_cli_env
is not loaded from dependencies as we need to know the environment in order to load the dependencies themselves. In those cases, you can set thepreferred_cli_env
configuration underdef project
in yourmix.exs
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.
Summary
Types
Functions
- alias?(task)
Checks if the given
task
name is an alias.- all_modules()
Returns all loaded task modules.
- clear()
Clears all invoked tasks, allowing them to be reinvoked.
- get(task)
Receives a task name and returns the corresponding task module if one exists.
- get!(task)
Receives a task name and retrieves the corresponding task module.
- load_all()
Loads all tasks in all code paths.
- load_tasks(dirs)
Loads all tasks in the given
paths
.- moduledoc(module)
Gets the moduledoc for the given task
module
.- preferred_cli_env(task)
Gets preferred CLI environment for the task.
- recursing?()
Indicates if the current task is recursing.
- recursive(module)
Checks if the task should be run recursively for all sub-apps in umbrella projects.
- reenable(task)
Reenables a given task so it can be executed again down the stack.
- requirements(module)
Gets the list of requirements for the given task.
- rerun(task, args \\ [])
Reruns
task
with the given arguments.- run(task, args \\ [])
Conditionally runs the task (or alias) with the given
args
.- shortdoc(module)
Gets the shortdoc for the given task
module
.- task?(module)
Returns
true
if given module is a task.- task_name(module)
Returns the task name for the given
module
.
Callbacks
- run(command_line_args)
A task needs to implement
run
which receives a list of command line args.
Types
Functions
alias?(task)Source
Specs
alias?(task_name()) :: boolean()
Checks if the given task
name is an alias.
Returns false if the given name is not an alias or if it is not a task.
For more information about task aliasing, take a look at the "Aliases" section in the docs for Mix
.
all_modules()Source
Specs
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.
clear()Source
Specs
clear() :: :ok
Clears all invoked tasks, allowing them to be reinvoked.
This operation is not recursive.
get(task)Source
Specs
get(task_name()) :: task_module() | nil
Receives a task name and returns the corresponding task module if one exists.
Returns nil
if the module cannot be found, if it is an alias, or if it is not a valid Mix.Task
.
get!(task)Source
Specs
get!(task_name()) :: task_module()
Receives a task name and retrieves the corresponding task module.
Exceptions
-
Mix.NoTaskError
- raised if the task could not be found -
Mix.InvalidTaskError
- raised if the task is not a validMix.Task
load_all()Source
Specs
load_all() :: [task_module()]
Loads all tasks in all code paths.
load_tasks(dirs)Source
Specs
load_tasks([List.Chars.t()]) :: [task_module()]
Loads all tasks in the given paths
.
moduledoc(module)Source
Specs
moduledoc(task_module()) :: String.t() | nil | false
Gets the moduledoc for the given task module
.
Returns the moduledoc or nil
.
preferred_cli_env(task)Source
Specs
preferred_cli_env(task_name()) :: atom() | nil
Gets preferred CLI environment for the task.
Returns environment (for example, :test
, or :prod
), or nil
.
recursing?()Source
Specs
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.
recursive(module)Source
Specs
recursive(task_module()) :: boolean()
Checks if the task should be run recursively for all sub-apps in umbrella projects.
Returns true
or false
.
reenable(task)Source
Specs
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.
requirements(module)Source
Specs
requirements(task_module()) :: []
Gets the list of requirements for the given task.
Returns a list of strings, where the string is expected to be a task optionally followed by its arguments.
rerun(task, args \\ [])Source
Specs
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.
run(task, args \\ [])Source
Specs
run(task_name(), [any()]) :: any()
Conditionally runs the task (or alias) with the given args
.
If there exists a task matching the given task name and it has not yet been invoked, this will run the task with the given args
and return the result.
If there is an alias defined for the given task name, the alias will be invoked instead of the original task.
If the task or alias has already been invoked, subsequent calls to run/2
will abort without executing and return :noop
.
Remember: by default, tasks will only run once, even when called repeatedly! If you need to run a task multiple times, you need to re-enable it via reenable/1
or call it using rerun/2
.
run/2
raises an exception if an alias or a task cannot be found or if the task is invalid. See get!/1
for more information.
shortdoc(module)Source
Specs
shortdoc(task_module()) :: String.t() | nil
Gets the shortdoc for the given task module
.
Returns the shortdoc or nil
.
task?(module)Source
Specs
task?(task_module()) :: boolean()
Returns true
if given module is a task.
task_name(module)Source
Specs
task_name(task_module()) :: task_name()
Returns the task name for the given module
.
Examples
iex> Mix.Task.task_name(Mix.Tasks.Test) "test"
Callbacks
run(command_line_args)Source
Specs
run(command_line_args :: [binary()]) :: any()
A task needs to implement run
which receives a list of command line args.
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/mix/1.12.0/Mix.Task.html