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.Mixfile do
  use Mix.Project

  def project do
    [app: :my_app,
     version: "0.6.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 here 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 single tasks with the @preferred_cli_env attribute (see 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 based on :apps_path and :apps configurations
build_path(config \\ config()): Returns the build path for this project
build_structure(config \\ config(), opts \\ []): Builds the project structure for the current application
compile(args, config \\ config()): Compiles the given project
compile_path(config \\ config()): Returns the paths this 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 this project
deps_paths(): Returns the full path of all dependencies as a map
ensure_structure(config \\ config(), opts \\ []): Ensures the project structure 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 this project
manifest_path(config \\ config()): Returns the path where manifests are stored
umbrella?(config \\ config()): Returns true if project is an umbrella project

Functions

app_path(config \\ config())

app_path(Keyword.t) :: 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 based on :apps_path and :apps configurations.

Returns nil if not an umbrella project.

build_path(config \\ config())

build_path(Keyword.t) :: Path.t

Returns the build path for this project.

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.t, Keyword.t) :: :ok

Builds the project structure for the current application.

Options

:symlink_ebin - symlink ebin instead of copying it

compile(args, config \\ config())

compile([term], Keyword.t) :: term

Compiles the given project.

It will run the compile task unless the project is in build embedded mode, which may fail as an explicit command to mix compile is required.

compile_path(config \\ config())

compile_path(Keyword.t) :: Path.t

Returns the paths this project compiles to.

The returned path will be expanded.

Examples

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

config()

config() :: Keyword.t

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.

By default it includes the mix.exs file, the lock manifest and all config files in the config directory.

consolidation_path(config \\ config())

Returns the path where protocol consolidations are stored.

deps_path(config \\ config())

deps_path(Keyword.t) :: Path.t

Returns the path where dependencies are stored for this project.

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.t, Keyword.t) :: :ok

Ensures the project structure 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.

Otherwise nil is returned. It may happen in cases there is no mixfile 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 Mix.NoProjectError in case no project is available.

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

in_project(atom, Path.t, Keyword.t, (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.Mixfile"

load_paths(config \\ config())

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

Returns all load paths for this project.

manifest_path(config \\ config())

manifest_path(Keyword.t) :: 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"

umbrella?(config \\ config())

Returns true if project is an umbrella project.