`mix_project`

Compiles a first-party Mix project against separately cached Elixir applications.

Description#

mix_project runs the compiler pipeline registered by mix.exs, including project compilers that direct elixirc cannot reproduce. Dependencies arrive through elixir_app providers and are loaded before compilation. The action does not compile dependencies. It stages their declared source trees inside an isolated workspace so compile-time macros and path dependencies observe the same relative layout as the original workspace.

The build captures the project-owned Mix environment, including the application directory, compiler manifests, protocol consolidation, and outputs produced by registered project compilers. Dependency applications remain separately cached targets and are linked into consumer layouts. Declared source, configuration, data, private, include, and tool inputs participate in the cache key.

The optional run capability consumes the existing build output. Set run_task for one task, use run_tasks for an ordered list of exact task argument vectors, or supply an unconfigured task with once run <target> -- <task>. Server and interactive runs are uncached by default. Deterministic checks can opt into action caching with run_cacheable = true. Uncached runs inherit their parent environment so development applications can launch locally installed tools and read user-level configuration. Explicit target environment values take precedence. Cacheable runs retain the constrained compiler path and scratch home.

Attributes#

Attribute	Type	Required	Default	Description
`app_name`	string	no	target name	Mix application name
`mix_env`	string	no	`prod`	Mix environment used for compilation and run tasks
`manifest`	string	no	`mix.exs`	Package-relative Mix project manifest
`lockfile`	string	no	`mix.lock`	Package-relative lockfile staged when present
`config`	list<string>	no	`["config/*/.exs"]`	Configuration file globs included in the build
`config_files`	list<string>	no	`[]`	Additional configuration file globs
`data`	list<string>	no	`[]`	Data file globs available to project compilers
`priv`	list<string>	no	`[]`	Private application files copied into the application output
`resources`	list<string>	no	`[]`	Additional private application files
`include`	list<string>	no	`["include/*/.hrl"]`	Erlang header files copied into the application output
`tools`	list<string>	no	`[]`	Workspace files read or executed by custom project compilers
`os_env`	map<string, string>	no	`{}`	Environment values exported during build and run actions
`env_inherit`	list<string>	no	`[]`	Host environment names inherited by build and run actions
`env`	map<string, string>	no	`{}`	Explicit environment values exported during build and run actions
`compile_args`	list<string>	no	`[]`	Additional arguments for the compiler pipeline
`run_task`	string	no	empty	Mix task exposed through `once run`; when empty, the caller may supply the task after `--`
`run_tasks`	list<list<string>>	no	`[]`	Ordered Mix tasks and their exact arguments; mutually exclusive with `run_task`
`run_no_compile`	bool	no	`true`	Pass `--no-compile` to the run task
`run_no_deps_check`	bool	no	`true`	Pass `--no-deps-check` to the run task
`run_args`	list<string>	no	`[]`	Arguments passed before caller-supplied arguments
`run_cacheable`	bool	no	`false`	Whether a successful run action can be restored from the action cache; uncached runs inherit their parent environment

Dependency Edges#

Edge	Accepts	Description
`deps`	`elixir_app`	Compiled applications loaded before the project compiler pipeline

Providers#

The target emits elixir_app and mix_project. Its provider includes app_name, mix_env, mix_config, source_root, source_inputs, build_env_dir, app_dir, ebin_dir, priv_dir, include_dir, compile_metadata, compile_warnings, transitive_elixir_apps, and transitive_sources.

Capabilities#

Capability	Output groups
`build`	`bytecode`
`run`	`default`; requires `bytecode`

Example#

toml

[[target]]
name = "application"
kind = "mix_project"
srcs = ["lib/**/*"]
deps = ["./mix_dependencies"]

[target.attrs]
app_name = "greeting"
mix_env = "dev"
manifest = "mix.exs"
run_task = "phx.server"

The same target can leave run_task empty and select the task at invocation time:

bash

once run application -- phx.server

When run_task is set, arguments after -- are appended to that task. A target with run_tasks rejects caller-supplied arguments because it would be ambiguous which task should receive them.

Use run_no_compile = false or run_no_deps_check = false only when the selected Mix task rejects those switches or must perform its own checks.

For ordered checks, declare each task and its arguments as a nested list:

toml

run_tasks = [
  ["deps.unlock", "--check-unused"],
  ["format", "--check-formatted"],
  ["credo"],
]
run_cacheable = true

Sources#

Mix compilation defines the registered compiler pipeline.
Mix project configuration documents application metadata, environments, and build paths.