Mix.Project

Defines and manipulate Mix projects.

In order to configure Mix, a developer needs to use Mix.Project in a module and define a function named project that returns a keyword list with configuration.

defmodule MyApp do
  use Mix.Project

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

After being defined, the configuration for this project can be read as Mix.Project.config/0. Notice that config/0 won’t fail if a project is not defined; this allows many Mix tasks to work without a project.

In case the developer needs a project or wants to access a special function in the project, the developer can call Mix.Project.get!/0 which fails with Mix.NoProjectError in case a project is not defined.

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 added to project.

The 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, etc.

Summary

Functions

app_path(config \\ config()): Returns the application path inside the build
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()): The path where protocol consolidations are stored
deps_path(config \\ config()): Returns the path to store dependencies 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()): The path to store manifests
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"

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 (the default), 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 into the stack. Calling it multiple times won’t cause it to be recomputed.

Do not use Mix.Project.config/0 to rely on 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())

The path where protocol consolidations are stored.

deps_path(config \\ config())

deps_path(Keyword.t) :: Path.t

Returns the path to store dependencies 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 Mixfile of the given project as its argument. The return value of this function is the return value of fun.

Examples

Mix.Project.in_project :my_app, "/path/to/my_app", fn mixfile ->
  "Mixfile is: #{inspect mixfile}"
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

The path to store manifests.

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.