Mix.Project

Defines and manipulates Mix projects.

A Mix project is defined by calling use Mix.Project in a module, usually placed in mix.exs:

defmodule MyApp.MixProject do
  use Mix.Project

  def project do
    [
      app: :my_app,
      version: "1.0.0"
    ]
  end
end

Configuration

In order to configure Mix, the module that uses Mix.Project should export a project/0 function that returns a keyword list representing configuration for the project.

This configuration can be read using Mix.Project.config/0. Note that config/0 won’t fail if a project is not defined; this allows many Mix tasks to work without a project.

If a task requires a project to be defined or needs to access a special function within the project, the task can call Mix.Project.get!/0 which fails with Mix.NoProjectError in the case a project is not defined.

There isn’t a comprehensive list of all the options that can be returned by project/0 since many Mix tasks define their own options that they read from this configuration. For example, look at the “Configuration” section in the documentation for the Mix.Tasks.Compile task.

These are a few options that are not used by just one Mix task (and will thus be documented here):

• :build_per_environment - if true, builds will be per-environment. If false, builds will go in _build/shared regardless of the Mix environment. Defaults to true.

• :aliases - a list of task aliases. For more information, check out the “Aliases” section in the documentation for the Mix module. Defaults to [].

• :config_path - a string representing the path of the main config file. See config_files/0 for more information. Defaults to "config/config.exs".

• :default_task - a string representing the default task to be run by mix when no task is specified. Defaults to "run".

• :deps - a list of dependencies of this project. Refer to the documentation for the Mix.Tasks.Deps task for more information. Defaults to [].

• :deps_path - directory where dependencies are stored. Also see deps_path/1. Defaults to "deps".

• :lockfile - the name of the lockfile used by the mix deps.* family of tasks. Defaults to "mix.lock".

• :preferred_cli_env - a keyword list of {task, env} tuples where task is the task name as an atom (for example, :"deps.get") and env is the preferred environment (for example, :test). This option overrides what specified by the tasks with the @preferred_cli_env attribute (see the docs for Mix.Task). Defaults to [].

For more options, keep an eye on the documentation for single Mix tasks; good examples are the Mix.Tasks.Compile task and all the specific compiler tasks (such as Mix.Tasks.Compile.Elixir or Mix.Tasks.Compile.Erlang).

Note that sometimes the same configuration option is mentioned in the documentation for different tasks; this is just because it’s common for many tasks to read and use the same configuration option (for example, :erlc_paths is used by mix compile.erlang, mix compile.yecc, and other tasks).

Erlang projects

Mix can be used to manage Erlang projects that don’t have any Elixir code. To ensure Mix tasks work correctly for an Erlang project, language: :erlang has to be part of the configuration returned by project/0. This setting also makes sure Elixir is not added as a dependency to the generated .app file or to the escript generated with mix escript.build, and so on.

Summary

Functions

app_path(config \\ config())

Returns the application path inside the build

apps_paths(config \\ config())

Returns a map with the umbrella child applications paths

build_path(config \\ config())

Returns the build path for the given project

build_structure(config \\ config(), opts \\ [])

Builds the project structure for the given application

compile(args, config \\ [])

Compiles the given project

compile_path(config \\ config())

Returns the paths the given project compiles to

config()

Returns the project configuration

config_files()

Returns a list of project configuration files for this project

consolidation_path(config \\ config())

Returns the path where protocol consolidations are stored

deps_path(config \\ config())

Returns the path where dependencies are stored for the given project

deps_paths()

Returns the full path of all dependencies as a map

ensure_structure(config \\ config(), opts \\ [])

Ensures the project structure for the given project exists

get()

Retrieves the current project if there is one

get!()

Same as get/0, but raises an exception if there is no current project

in_project(app, path, post_config \\ [], fun)

Runs the given fun inside the given project

load_paths(config \\ config())

Returns all load paths for the given project

manifest_path(config \\ config())

Returns the path where manifests are stored

umbrella?(config \\ config())

Returns true if config is the configuration for an umbrella project

Functions

app_path(config \\ config())

app_path(keyword()) :: Path.t()

Returns the application path inside the build.

The returned path will be expanded.

Examples

Mix.Project.app_path
#=> "/path/to/project/_build/shared/lib/app"

apps_paths(config \\ config())

Returns a map with the umbrella child applications paths.

These paths are based on the :apps_path and :apps configurations.

If the given project configuration identifies an umbrella project, the return value is a map of app => path where app is a child app of the umbrella and path is its path relative to the root of the umbrella project.

If the given project configuration does not identify an umbrella project, nil is returned.

Examples

Mix.Project.apps_paths()
#=> %{my_app1: "apps/my_app1", my_app2: "apps/my_app2"}

build_path(config \\ config())

build_path(keyword()) :: Path.t()

Returns the build path for the given project.

If no configuration is given, the one for the current project is used.

The returned path will be expanded.

Examples

Mix.Project.build_path
#=> "/path/to/project/_build/shared"

If :build_per_environment is set to true, it will create a new build per environment:

Mix.env
#=> :dev
Mix.Project.build_path
#=> "/path/to/project/_build/dev"

build_structure(config \\ config(), opts \\ [])

build_structure(keyword(), keyword()) :: :ok

Builds the project structure for the given application.

Options

• :symlink_ebin - symlink ebin instead of copying it

compile(args, config \\ [])

compile([term()], keyword()) :: term()

Compiles the given project.

compile_path(config \\ config())

compile_path(keyword()) :: Path.t()

Returns the paths the given project compiles to.

If no configuration is given, the one for the current project will be used.

The returned path will be expanded.

Examples

Mix.Project.compile_path
#=> "/path/to/project/_build/dev/lib/app/ebin"

config()

config() :: keyword()

Returns the project configuration.

If there is no project defined, it still returns a keyword list with default values. This allows many Mix tasks to work without the need for an underlying project.

Note this configuration is cached once the project is pushed onto the stack. Calling it multiple times won’t cause it to be recomputed.

Do not use Mix.Project.config/0 to find the runtime configuration. Use it only to configure aspects of your project (like compilation directories) and not your application runtime.

config_files()

config_files() :: [Path.t()]

Returns a list of project configuration files for this project.

This function is usually used in compilation tasks to trigger a full recompilation whenever such configuration files change.

It returns the mix.exs file, the lock manifest, and all config files in the config directory that do not start with a trailing period (for example, .my_config.exs).

consolidation_path(config \\ config())

Returns the path where protocol consolidations are stored.

The returned path will be expanded.

Examples

Mix.Project.consolidation_path
#=> "/path/to/project/_build/dev/lib/my_app/consolidated"

Inside umbrellas:

Mix.Project.consolidation_path
#=> "/path/to/project/_build/dev/consolidated"

deps_path(config \\ config())

deps_path(keyword()) :: Path.t()

Returns the path where dependencies are stored for the given project.

If no configuration is given, the one for the current project is used.

The returned path will be expanded.

Examples

Mix.Project.deps_path
#=> "/path/to/project/deps"

deps_paths()

deps_paths() :: %{optional(atom()) => Path.t()}

Returns the full path of all dependencies as a map.

Examples

Mix.Project.deps_paths
#=> %{foo: "deps/foo", bar: "custom/path/dep"}

ensure_structure(config \\ config(), opts \\ [])

ensure_structure(keyword(), keyword()) :: :ok

Ensures the project structure for the given project exists.

In case it does exist, it is a no-op. Otherwise, it is built.

get()

get() :: module() | nil

Retrieves the current project if there is one.

If there is no current project, nil is returned. This may happen in cases there is no mix.exs in the current directory.

If you expect a project to be defined, i.e., it is a requirement of the current task, you should call get!/0 instead.

get!()

get!() :: module() | no_return()

Same as get/0, but raises an exception if there is no current project.

This is usually called by tasks that need additional functions on the project to be defined. Since such tasks usually depend on a project being defined, this function raises a Mix.NoProjectError exception in case no project is available.

in_project(app, path, post_config \\ [], fun)

in_project(atom(), Path.t(), keyword(), (module() -> result)) :: result
when result: term()

Runs the given fun inside the given project.

This function changes the current working directory and loads the project at the given directory onto the project stack.

A post_config can be passed that will be merged into the project configuration.

fun is called with the module name of the given Mix.Project. The return value of this function is the return value of fun.

Examples

Mix.Project.in_project :my_app, "/path/to/my_app", fn module ->
  "Mixfile is: #{inspect module}"
end
#=> "Mixfile is: MyApp.MixProject"

load_paths(config \\ config())

load_paths(keyword()) :: [Path.t()]

Returns all load paths for the given project.

manifest_path(config \\ config())

manifest_path(keyword()) :: Path.t()

Returns the path where manifests are stored.

By default they are stored in the app path inside the build directory. Umbrella applications have the manifest path set to the root of the build directory. Directories may be changed in future releases.

The returned path will be expanded.

Examples

Mix.Project.manifest_path
#=> "/path/to/project/_build/shared/lib/app/.mix"

umbrella?(config \\ config())

Returns true if config is the configuration for an umbrella project.

When called with no arguments, tells whether the current project is an umbrella project.