# Mix v1.10.3 Mix.Project View Source

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 `use`s `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 is specified by the tasks with the `@preferred_cli_env` attribute (see the docs for `Mix.Task`). Defaults to `[]`.

- `:preferred_cli_target` - a keyword list of `{task, target}` tuples where `task` is the task name as an atom (for example, `:test`) and `target` is the preferred target (for example, `:host`). 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.

# Link to this section 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.

clear_deps_cache()

Clears the dependency for the current environment.

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.

config_mtime()

Returns the latest modification time from config files.

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(opts \\ [])

Returns the full path of all dependencies as a map.

deps_scms(opts \\ [])

Returns the SCMs 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()) deprecated
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.

# Link to this section Functions

Link to this function

# app_path(config \\ config())

View Source

## Specs

    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"

Link to this function

# apps_paths(config \\ config())

View Source (since 1.4.0)

## Specs

    apps_paths(keyword()) :: %{optional(atom()) => Path.t()} | nil

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"}

Link to this function

# build_path(config \\ config())

View Source

## Specs

    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"

Link to this function

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

View Source

## Specs

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

Builds the project structure for the given application.

## Options

- `:symlink_ebin` - symlink ebin instead of copying it

Link to this function

# clear_deps_cache()

View Source (since 1.7.0)

## Specs

    clear_deps_cache() :: :ok

Clears the dependency for the current environment.

Useful when dependencies need to be reloaded due to change of global state.

Link to this function

# compile(args, config \\ [])

View Source

## Specs

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

Compiles the given project.

Link to this function

# compile_path(config \\ config())

View Source

## Specs

    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"

Link to this function

# config()

View Source

## Specs

    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.

Link to this function

# config_files()

View Source

## Specs

    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 leading period (for example, `.my_config.exs`).

Link to this function

# config_mtime()

View Source (since 1.7.0)

## Specs

    config_mtime() :: posix_mtime when posix_mtime: integer()

Returns the latest modification time from config files.

This function is usually used in compilation tasks to trigger a full recompilation whenever such configuration files change. For this reason, the mtime is cached to avoid file system lookups.

Link to this function

# consolidation_path(config \\ config())

View Source

## Specs

    consolidation_path(keyword()) :: Path.t()

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"

Link to this function

# deps_path(config \\ config())

View Source

## Specs

    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"

Link to this function

# deps_paths(opts \\ [])

View Source

## Specs

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

Returns the full path of all dependencies as a map.

## Options

- `:depth` - only returns dependencies to the depth level, a depth of 1 will only return top-level dependencies
- `:parents` - starts the dependency traversal from the given parents instead of the application root

## Examples

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

Link to this function

# deps_scms(opts \\ [])

View Source (since 1.10.0)

## Specs

    deps_scms(keyword()) :: %{optional(atom()) => Mix.SCM.t()}

Returns the SCMs of all dependencies as a map.

See `Mix.SCM` module documentation to learn more about SCMs.

## Options

- `:depth` - only returns dependencies to the depth level, a depth of 1 will only return top-level dependencies
- `:parents` - starts the dependency traversal from the given parents instead of the application root

## Examples

    Mix.Project.deps_scms()
    #=> %{foo: Mix.SCM.Path, bar: Mix.SCM.Git}

Link to this function

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

View Source

## Specs

    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.

Link to this function

# get()

View Source

## Specs

    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.

Link to this function

# get!()

View Source

## Specs

    get!() :: module()

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.

Link to this function

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

View Source

## Specs

    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 ->
      "Mix project is: #{inspect(module)}"
    end)
    #=> "Mix project is: MyApp.MixProject"

Link to this function

# load_paths(config \\ config())

View Source
This function is deprecated. Use Mix.Project.compile_path/1 instead.
Link to this function

# manifest_path(config \\ config())

View Source

## Specs

    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"

Link to this function

# umbrella?(config \\ config())

View Source

## Specs

    umbrella?(keyword()) :: boolean()

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.