MBU: Mix Build Utilities v0.2.4 MBU.TaskUtils

Utilities for project build tasks.

Summary

Types

A watch specification or program specification that is used internally to keep track of running programs and watches

Functions

Start an external program with apprunner

Kill a running program or watch

Listen to messages from the given specs and print them to the screen

Print file size of given file in human readable form

Run the given functions in parallel and wait for them all to stop before returning

Run the given Mix task and wait for it to stop before returning

Run the given tasks in parallel and wait for them all to stop before returning

Wait for user’s enter key and send a message :user_input_received to the given target process when enter was pressed

Start watching a path. Name is used for prefixing logs

Types

buildspec()
buildspec ::
  %MBU.TaskUtils.WatchSpec{callback: term, events: term, name: term, name_atom: term, path: term, pid: term, waiting_to_trigger: term} |
  %MBU.TaskUtils.ProgramSpec{name: term, pending_output: term, port: term}

A watch specification or program specification that is used internally to keep track of running programs and watches.

Functions

exec(executable, args, opts \\ [])
exec(String.t, list, list) :: %MBU.TaskUtils.ProgramSpec{name: term, pending_output: term, port: term}

Start an external program with apprunner.

Apprunner handles killing the program if BEAM is abruptly shut down. Name is used as a prefix for logging output.

Options that can be given:

  • name: Use as name for logging, otherwise name of binary is used.
  • cd: Directory to change to before executing.

Returns ProgramSpec for the started program.

kill(spec)
kill(buildspec) :: any

Kill a running program or watch.

listen(specs, opts \\ [])
listen(buildspec | [buildspec], list) :: any

Listen to messages from the given specs and print them to the screen.

If watch: true is given in the options, will listen for user’s enter key and kill programs/watches if enter is pressed.

run_funs(funs, timeout \\ 60000)
run_funs([(... -> any) | {module, (... -> any), [...]}], integer) :: any

Run the given functions in parallel and wait for them all to stop before returning.

Functions can either be anonymous functions or tuples of {module, fun, args}.

Can be given optional timeout, how long to wait for the execution of a task. By default it’s 60 seconds.

run_task(task, args \\ [])
run_task(task_name, [...]) :: any

Run the given Mix task and wait for it to stop before returning.

See run_tasks/2 for the argument description.

run_tasks(tasks)
run_tasks(task_list) :: any

Run the given tasks in parallel and wait for them all to stop before returning.

Valid task types:

  • {task_name, args}, where task_name is a Mix task name or module,
  • task_name, where task_name is a Mix task name or module to call without arguments, or
  • task_function where task_function is a function to call without arguments.

Arguments should be keyword lists. If an argument deps: false is given to a task that is an MBU.BuildTask, its dependencies will not be executed.

wait_for_input(target)
wait_for_input(pid) :: any

Wait for user’s enter key and send a message :user_input_received to the given target process when enter was pressed.

This is exposed due to internal code structure and is not really useful to call yourself.

watch(name, path, fun_or_mod)
watch(String.t, String.t, ([{String.t, [atom]}] -> any) | module) :: %MBU.TaskUtils.WatchSpec{callback: term, events: term, name: term, name_atom: term, path: term, pid: term, waiting_to_trigger: term}

Start watching a path. Name is used for prefixing logs.

Path must point to a directory. All subdirs will be watched automatically.

The callback function is called whenever changes occur in the watched directory. It will receive a list of 2-tuples, each tuple describing one change. Each tuple has two elements: path to the changed file and a list of change events for that file (returned from :fs).

Instead of a callback function, you can also give a module name of an MBU.BuildTask. In that case, the specified task will be called without arguments and with deps: false.

Watch events are combined so that all events occurring in ~200 milliseconds are sent in the same call. This is to avoid running the watch callback many times when a bunch of files change.

NOTE: Never add multiple watches to the same path, or you may end up with unexpected issues!

Returns a WatchSpec.