A module for working with applications and defining application callbacks.

Applications are the idiomatic way to package software in Erlang/OTP. To get the idea, they are similar to the "library" concept common in other programming languages, but with some additional characteristics.

An application is a component implementing some specific functionality, with a standardized directory structure, configuration, and life cycle. Applications are loaded, started, and stopped. Each application also has its own environment, which provides a unified API for configuring each application.

Developers typically interact with the application environment and its callback module. Therefore those will be the topics we will cover first before jumping into details about the application resource file and life-cycle.

The application environment

Each application has its own environment. The environment is a keyword list that maps atoms to terms. Note that this environment is unrelated to the operating system environment.

By default, the environment of an application is an empty list. In a Mix project's mix.exs file, you can set the :env key in application/0:

def application do
  [env: [db_host: "localhost"]]
end

Now, in your application, you can read this environment by using functions such as fetch_env!/2 and friends:

defmodule MyApp.DBClient do
  def start_link() do
    SomeLib.DBClient.start_link(host: db_host())
  end

  defp db_host do
    Application.fetch_env!(:my_app, :db_host)
  end
end

In Mix projects, the environment of the application and its dependencies can be overridden via the config/config.exs and config/runtime.exs files. The former is loaded at build-time, before your code compiles, and the latter at runtime, just before your app starts. For example, someone using your application can override its :db_host environment variable as follows:

import Config
config :my_app, :db_host, "db.local"

See the "Configuration" section in the Mix module for more information. You can also change the application environment dynamically by using functions such as put_env/3 and delete_env/2.

Environment in libraries

The config files config/config.exs and config/runtime.exs are rarely used by libraries. Libraries typically define their environment in the application/0 function of their mix.exs. Configuration files are rather used by applications to configure their libraries.

Reading the environment of other applications

Each application is responsible for its own environment. Do not use the functions in this module for directly accessing or modifying the environment of other applications. Whenever you change the application environment, Elixir's build tool will only recompile the files that belong to that application. So if you read the application environment of another application, there is a chance you will be depending on outdated configuration, as your file won't be recompiled as it changes.

Compile-time environment

In the previous example, we read the application environment at runtime:

defmodule MyApp.DBClient do
  def start_link() do
    SomeLib.DBClient.start_link(host: db_host())
  end

  defp db_host do
    Application.fetch_env!(:my_app, :db_host)
  end
end

In other words, the environment key :db_host for application :my_app will only be read when MyApp.DBClient effectively starts. While reading the application environment at runtime is the preferred approach, in some rare occasions you may want to use the application environment to configure the compilation of a certain project. However, if you try to access Application.fetch_env!/2 outside of a function:

defmodule MyApp.DBClient do
  @db_host Application.fetch_env!(:my_app, :db_host)

  def start_link() do
    SomeLib.DBClient.start_link(host: @db_host)
  end
end

You might see warnings and errors:

warning: Application.fetch_env!/2 is discouraged in the module body,
use Application.compile_env/3 instead
  iex:3: MyApp.DBClient

** (ArgumentError) could not fetch application environment :db_host
for application :my_app because the application was not loaded nor
configured

This happens because, when defining modules, the application environment is not yet available. Luckily, the warning tells us how to solve this issue, by using Application.compile_env/3 instead:

defmodule MyApp.DBClient do
  @db_host Application.compile_env(:my_app, :db_host, "db.local")

  def start_link() do
    SomeLib.DBClient.start_link(host: @db_host)
  end
end

The difference here is that compile_env expects the default value to be given as an argument, instead of using the def application function of your mix.exs. Furthermore, by using compile_env/3, tools like Mix will store the values used during compilation and compare the compilation values with the runtime values whenever your system starts, raising an error in case they differ.

In any case, compile-time environments should be avoided. Whenever possible, reading the application environment at runtime should be the first choice.

The application callback module

Applications can be loaded, started, and stopped. Generally, build tools like Mix take care of starting an application and all of its dependencies for you, but you can also do it manually by calling:

{:ok, _} = Application.ensure_all_started(:some_app)

When an application starts, developers may configure a callback module that executes custom code. Developers use this callback to start the application supervision tree.

The first step to do so is to add a :mod key to the application/0 definition in your mix.exs file. It expects a tuple, with the application callback module and start argument (commonly an empty list):

def application do
  [mod: {MyApp, []}]
end

The MyApp module given to :mod needs to implement the Application behaviour. This can be done by putting use Application in that module and implementing the start/2 callback, for example:

defmodule MyApp do
  use Application

  def start(_type, _args) do
    children = []
    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

use Application

When you use Application, the Application module will set @behaviour Application and define an overridable definition for the stop/1 function, which is required by Erlang/OTP.

The start/2 callback has to spawn and link a supervisor and return {:ok, pid} or {:ok, pid, state}, where pid is the PID of the supervisor, and state is an optional application state. args is the second element of the tuple given to the :mod option.

The type argument passed to start/2 is usually :normal unless in a distributed setup where application takeovers and failovers are configured. Distributed applications are beyond the scope of this documentation.

When an application is shutting down, its stop/1 callback is called after the supervision tree has been stopped by the runtime. This callback allows the application to do any final cleanup. The argument is the state returned by start/2, if it did, or [] otherwise. The return value of stop/1 is ignored.

By using Application, modules get a default implementation of stop/1 that ignores its argument and returns :ok, but it can be overridden.

Application callback modules may also implement the optional callback prep_stop/1. If present, prep_stop/1 is invoked before the supervision tree is terminated. Its argument is the state returned by start/2, if it did, or [] otherwise, and its return value is passed to stop/1.

The application resource file

In the sections above, we have configured an application in the application/0 section of the mix.exs file. Ultimately, Mix will use this configuration to create an application resource file, which is a file called APP_NAME.app. For example, the application resource file of the OTP application ex_unit is called ex_unit.app.

You can learn more about the generation of application resource files in the documentation of Mix.Tasks.Compile.App, available as well by running mix help compile.app.

The application life cycle

Loading applications

Applications are loaded, which means that the runtime finds and processes their resource files:

Application.load(:ex_unit)
#=> :ok

When an application is loaded, the environment specified in its resource file is merged with any overrides from config files.

Loading an application does not load its modules.

In practice, you rarely load applications by hand because that is part of the start process, explained next.

Starting applications

Applications are also started:

Application.start(:ex_unit)
#=> :ok

Once your application is compiled, running your system is a matter of starting your current application and its dependencies. Differently from other languages, Elixir does not have a main procedure that is responsible for starting your system. Instead, you start one or more applications, each with their own initialization and termination logic.

When an application is started, the Application.load/1 is automatically invoked if it hasn't been done yet. Then, it checks if the dependencies listed in the applications key of the resource file are already started. Having at least one dependency not started is an error condition. Functions like ensure_all_started/1 takes care of starting an application and all of its dependencies for you.

If the application does not have a callback module configured, starting is done at this point. Otherwise, its start/2 callback is invoked. The PID of the top-level supervisor returned by this function is stored by the runtime for later use, and the returned application state is saved too, if any.

Stopping applications

Started applications are, finally, stopped:

Application.stop(:ex_unit)
#=> :ok

Stopping an application without a callback module is defined, but except for some system tracing, it is in practice a no-op.

Stopping an application with a callback module has three steps:

1. If present, invoke the optional callback prep_stop/1.
2. Terminate the top-level supervisor.
3. Invoke the required callback stop/1.

The arguments passed to the callbacks are related to the state optionally returned by start/2, and are documented in the section about the callback module above.

It is important to highlight that step 2 is a blocking one. Termination of a supervisor triggers a recursive chain of children terminations, therefore orderly shutting down all descendant processes. The stop/1 callback is invoked only after termination of the whole supervision tree.

Shutting down a live system cleanly can be done by calling System.stop/1. It will shut down every application in the opposite order they had been started.

By default, a SIGTERM from the operating system will automatically translate to System.stop/0. You can also have more explicit control over operating system signals via the :os.set_signal/2 function.

Tooling

The Mix build tool automates most of the application management tasks. For example, mix test automatically starts your application dependencies and your application itself before your test runs. mix run --no-halt boots your current project and can be used to start a long running system. See mix help run.

Developers can also use mix release to build releases. Releases are able to package all of your source code as well as the Erlang VM into a single directory. Releases also give you explicit control over how each application is started and in which order. They also provide a more streamlined mechanism for starting and stopping systems, debugging, logging, as well as system monitoring.

Finally, Elixir provides tools such as escripts and archives, which are different mechanisms for packaging your application. Those are typically used when tools must be shared between developers and not as deployment options. See mix help archive.build and mix help escript.build for more detail.

Further information

For further details on applications please check the documentation of the :application Erlang module, and the Applications section of the OTP Design Principles User's Guide.