<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>Application – Elixir v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/elixir/v1.7/Application.html" />
<script src="dist/sidebar_items-cdf4e58b19.js"></script>
</head>
<body data-type="modules">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
Elixir </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="Elixir" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
<li><a id="exceptions-list" href="#full-list">Exceptions</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">Elixir v1.7.2</small>
Application <small>behaviour</small>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>A module for working with applications and defining application callbacks.</p>
<p>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.</p>
<p>An application is a component implementing some specific functionality, with a
standardized directory structure, configuration, and lifecycle. Applications
are <em>loaded</em>, <em>started</em>, and <em>stopped</em>.</p>
<h2 id="module-the-application-resource-file" class="section-heading">
<a href="#module-the-application-resource-file" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The application resource file
</h2>
<p>Applications are specified in their <a href="http://erlang.org/doc/man/app.html"><em>resource
file</em></a>, which is a file called <code class="inline">APP.app</code>,
where <code class="inline">APP</code> is the application name. For example, the application resource
file of the OTP application <code class="inline">ex_unit</code> is called <code class="inline">ex_unit.app</code>.</p>
<p>You’ll find the resource file of an application in its <code class="inline">ebin</code> directory, it is
generated automatically by Mix. Some of its keys are taken from the keyword
lists returned by the <code class="inline">project/0</code> and <code class="inline">application/0</code> functions defined in
<code class="inline">mix.exs</code>, and others are generated by Mix itself.</p>
<p>You can learn more about the generation of application resource files in the
documentation of <code class="inline">Mix.Tasks.Compile.App</code>, available as well by running <code class="inline">mix
help compile.app</code>.</p>
<h2 id="module-the-application-environment" class="section-heading">
<a href="#module-the-application-environment" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The application environment
</h2>
<p>The key <code class="inline">env</code> of an application resource file has a list of tuples that map
atoms to terms, and its contents are known as the application <em>environment</em>.
Note that this environment is unrelated to the operating system environment.</p>
<p>By default, the environment of an application is an empty list. In a Mix
project you can set that key in <code class="inline">application/0</code>:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">application</span><span class="w"> </span><span class="k" data-group-id="3937130923-1">do</span><span class="w">
</span><span class="p" data-group-id="3937130923-2">[</span><span class="ss">env</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="3937130923-3">[</span><span class="ss">redis_host</span><span class="p">:</span><span class="w"> </span><span class="s">"localhost"</span><span class="p" data-group-id="3937130923-3">]</span><span class="p" data-group-id="3937130923-2">]</span><span class="w">
</span><span class="k" data-group-id="3937130923-1">end</span></code></pre>
<p>and the generated application resource file is going to have it included.</p>
<p>The environment is available after loading the application, which is a process
explained later:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">Application</span><span class="o">.</span><span class="n">load</span><span class="p" data-group-id="7659611981-1">(</span><span class="ss">:APP_NAME</span><span class="p" data-group-id="7659611981-1">)</span><span class="w">
</span><span class="c1">#=> :ok</span><span class="w">
</span><span class="nc">Application</span><span class="o">.</span><span class="n">get_env</span><span class="p" data-group-id="7659611981-2">(</span><span class="ss">:APP_NAME</span><span class="p">,</span><span class="w"> </span><span class="ss">:redis_host</span><span class="p" data-group-id="7659611981-2">)</span><span class="w">
</span><span class="c1">#=> "localhost"</span></code></pre>
<p>In Mix projects, the environment of the application and its dependencies can
be overridden via the <code class="inline">config/config.exs</code> file. If you start the application
with Mix, that configuration is available at compile time, and at runtime too,
but take into account it is not included in the generated application resource
file, and it is not available if you start the application without Mix.</p>
<p>For example, someone using your application can override its <code class="inline">:redis_host</code>
environment variable as follows:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:APP_NAME</span><span class="p">,</span><span class="w"> </span><span class="ss">redis_host</span><span class="p">:</span><span class="w"> </span><span class="s">"redis.local"</span></code></pre>
<p>The function <a href="#put_env/3"><code class="inline">put_env/3</code></a> allows dynamic configuration of the application
environment, but as a rule of thumb each application is responsible for its
own environment. Please do not use the functions in this module for directly
accessing or modifying the environment of other applications.</p>
<p>The application environment can be overriden via the <code class="inline">-config</code> option of
<code class="inline">erl</code>, as well as command-line flags, as we are going to see below.</p>
<h2 id="module-the-application-callback-module" class="section-heading">
<a href="#module-the-application-callback-module" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The application callback module
</h2>
<p>The <code class="inline">mod</code> key of an application resource file configures an application
callback module and start argument:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">application</span><span class="w"> </span><span class="k" data-group-id="0563809342-1">do</span><span class="w">
</span><span class="p" data-group-id="0563809342-2">[</span><span class="ss">mod</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="0563809342-3">{</span><span class="nc">MyApp</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="0563809342-4">[</span><span class="p" data-group-id="0563809342-4">]</span><span class="p" data-group-id="0563809342-3">}</span><span class="p" data-group-id="0563809342-2">]</span><span class="w">
</span><span class="k" data-group-id="0563809342-1">end</span></code></pre>
<p>This key is optional, only needed for applications that start a supervision tree.</p>
<p>The <code class="inline">MyApp</code> module given to <code class="inline">:mod</code> needs to implement the <a href="Application.html#content"><code class="inline">Application</code></a> behaviour.
This can be done by putting <code class="inline">use Application</code> in that module and implementing the
<a href="#c:start/2"><code class="inline">start/2</code></a> callback, for example:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyApp</span><span class="w"> </span><span class="k" data-group-id="6429258319-1">do</span><span class="w">
</span><span class="kn">use</span><span class="w"> </span><span class="nc">Application</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">start</span><span class="p" data-group-id="6429258319-2">(</span><span class="c">_type</span><span class="p">,</span><span class="w"> </span><span class="c">_args</span><span class="p" data-group-id="6429258319-2">)</span><span class="w"> </span><span class="k" data-group-id="6429258319-3">do</span><span class="w">
</span><span class="n">children</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="6429258319-4">[</span><span class="p" data-group-id="6429258319-4">]</span><span class="w">
</span><span class="nc">Supervisor</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="6429258319-5">(</span><span class="n">children</span><span class="p">,</span><span class="w"> </span><span class="ss">strategy</span><span class="p">:</span><span class="w"> </span><span class="ss">:one_for_one</span><span class="p" data-group-id="6429258319-5">)</span><span class="w">
</span><span class="k" data-group-id="6429258319-3">end</span><span class="w">
</span><span class="k" data-group-id="6429258319-1">end</span></code></pre>
<p>The <a href="#c:start/2"><code class="inline">start/2</code></a> callback has to spawn and link a supervisor and return <code class="inline">{:ok,
pid}</code> or <code class="inline">{:ok, pid, state}</code>, where <code class="inline">pid</code> is the PID of the supervisor, and
<code class="inline">state</code> is an optional application state. <code class="inline">args</code> is the second element of the
tuple given to the <code class="inline">:mod</code> option.</p>
<p>The <code class="inline">type</code> argument passed to <a href="#c:start/2"><code class="inline">start/2</code></a> is usually <code class="inline">:normal</code> unless in a
distributed setup where application takeovers and failovers are configured.
Distributed applications are beyond the scope of this documentation.</p>
<p>When an application is shutting down, its <a href="#c:stop/1"><code class="inline">stop/1</code></a> 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
<a href="#c:start/2"><code class="inline">start/2</code></a>, if it did, or <code class="inline">[]</code> otherwise. The return value of <a href="#c:stop/1"><code class="inline">stop/1</code></a> is
ignored.</p>
<p>By using <a href="Application.html#content"><code class="inline">Application</code></a>, modules get a default implementation of <a href="#c:stop/1"><code class="inline">stop/1</code></a>
that ignores its argument and returns <code class="inline">:ok</code>, but it can be overridden.</p>
<p>Application callback modules may also implement the optional callback
<a href="#c:prep_stop/1"><code class="inline">prep_stop/1</code></a>. If present, <a href="#c:prep_stop/1"><code class="inline">prep_stop/1</code></a> is invoked before the supervision
tree is terminated. Its argument is the state returned by <a href="#c:start/2"><code class="inline">start/2</code></a>, if it did,
or <code class="inline">[]</code> otherwise, and its return value is passed to <a href="#c:stop/1"><code class="inline">stop/1</code></a>.</p>
<h2 id="module-the-application-lifecycle" class="section-heading">
<a href="#module-the-application-lifecycle" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The application lifecycle
</h2>
<h3 id="module-loading-applications" class="section-heading">
<a href="#module-loading-applications" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Loading applications
</h3>
<p>Applications are <em>loaded</em>, which means that the runtime finds and processes
their resource files:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">Application</span><span class="o">.</span><span class="n">load</span><span class="p" data-group-id="9399245244-1">(</span><span class="ss">:ex_unit</span><span class="p" data-group-id="9399245244-1">)</span><span class="w">
</span><span class="c1">#=> :ok</span></code></pre>
<p>If an application has included applications, they are also loaded. And the
procedure recurses if they in turn have included applications. Included
applications are unrelated to applications in Mix umbrella projects, they are
an Erlang/OTP concept that has to do with coordinated starts.</p>
<p>When an application is loaded, the environment specified in its resource file
is merged with any overrides from config files passed to <code class="inline">erl</code> via the
<code class="inline">-config</code> option. It is worth highlighting that releases pass <code class="inline">sys.config</code>
this way. The resulting environment can still be overridden again via specific
<code class="inline">-Application</code> flags passed to <code class="inline">erl</code>.</p>
<p>Loading an application <em>does not</em> load its modules.</p>
<p>In practice, you rarely load applications by hand because that is part of the
start process, explained next.</p>
<h3 id="module-starting-applications" class="section-heading">
<a href="#module-starting-applications" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Starting applications
</h3>
<p>Applications are also <em>started</em>:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">Application</span><span class="o">.</span><span class="n">start</span><span class="p" data-group-id="8343852987-1">(</span><span class="ss">:ex_unit</span><span class="p" data-group-id="8343852987-1">)</span><span class="w">
</span><span class="c1">#=> :ok</span></code></pre>
<p>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 <code class="inline">main</code> procedure that is responsible for starting your
system. Instead, you start one or more applications, each with their own
initialization and termination logic.</p>
<p>When an application is started, the runtime loads it if it hasn’t been loaded
yet (in the technical sense described above). Then, it checks if the
dependencies listed in the <code class="inline">applications</code> key of the resource file are already
started. Having at least one dependency not started is an error condition, but
when you start an application with <code class="inline">mix run</code>, Mix takes care of starting all
the dependencies for you, so in practice you don’t need to worry about it
unless you are starting applications manually with the API provided by this
module.</p>
<p>If the application does not have a callback module configured, starting is
done at this point. Otherwise, its <a href="#c:start/2"><code class="inline">start/2</code></a> callback if 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.</p>
<h3 id="module-stopping-applications" class="section-heading">
<a href="#module-stopping-applications" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Stopping applications
</h3>
<p>Started applications are, finally, <em>stopped</em>:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">Application</span><span class="o">.</span><span class="n">stop</span><span class="p" data-group-id="0324404027-1">(</span><span class="ss">:ex_unit</span><span class="p" data-group-id="0324404027-1">)</span><span class="w">
</span><span class="c1">#=> :ok</span></code></pre>
<p>Stopping an application without a callback module is defined, but except for
some system tracing, it is in practice a no-op.</p>
<p>Stopping an application with a callback module has three steps:</p>
<ol>
<li>If present, invoke the optional callback <a href="#c:prep_stop/1"><code class="inline">prep_stop/1</code></a>.
</li>
<li>Terminate the top-level supervisor.
</li>
<li>Invoke the required callback <a href="#c:stop/1"><code class="inline">stop/1</code></a>.
</li>
</ol>
<p>The arguments passed to the callbacks are related to the state optionally
returned by <a href="#c:start/2"><code class="inline">start/2</code></a>, and are documented in the section about the callback
module above.</p>
<p>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 <a href="#c:stop/1"><code class="inline">stop/1</code></a> callback is
invoked only after termination of the whole supervision tree.</p>
<p>Shutting down a live system cleanly can be done by calling <a href="System.html#stop/1"><code class="inline">System.stop/1</code></a>. It
will shut down every application in the opposite order they had been started.</p>
<p>From Erlang/OTP 19.1, a SIGTERM from the operating system will automatically
translate to <a href="System.html#stop/0"><code class="inline">System.stop/0</code></a>. Erlang/OTP 20 gives user more explicit control
over OS signals via the <a href="http://www.erlang.org/doc/man/os.html#set_signal-2"><code class="inline">:os.set_signal/2</code></a> function.</p>
<h2 id="module-tooling" class="section-heading">
<a href="#module-tooling" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Tooling
</h2>
<p>The Mix build tool can also be used to start your applications. For example,
<code class="inline">mix test</code> automatically starts your application dependencies and your application
itself before your test runs. <code class="inline">mix run --no-halt</code> boots your current project and
can be used to start a long running system. See <code class="inline">mix help run</code>.</p>
<p>Developers can also use tools like <a href="https://github.com/bitwalker/distillery">Distillery</a>
that build <strong>releases</strong>. 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.</p>
<p>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 <code class="inline">mix help archive.build</code> and <code class="inline">mix help escript.build</code> for more detail.</p>
<h2 id="module-further-information" class="section-heading">
<a href="#module-further-information" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Further information
</h2>
<p>For further details on applications please check the documentation of the
<a href="http://www.erlang.org/doc/man/application.html"><code class="inline">application</code></a> Erlang module,
and the
<a href="http://www.erlang.org/doc/design_principles/applications.html">Applications</a>
section of the <a href="http://erlang.org/doc/design_principles/users_guide.html">OTP Design Principles User’s
Guide</a>.</p>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-types summary">
<h2>
<a href="#types">Types</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:app/0">app()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:key/0">key()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:restart_type/0">restart_type()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:start_type/0">start_type()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:state/0">state()</a>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#t:value/0">value()</a>
</div>
</div>
</div>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#app_dir/1">app_dir(app)</a>
</div>
<div class="summary-synopsis"><p>Gets the directory for app</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#app_dir/2">app_dir(app, path)</a>
</div>
<div class="summary-synopsis"><p>Returns the given path inside <a href="#app_dir/1"><code class="inline">app_dir/1</code></a></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#delete_env/3">delete_env(app, key, opts \\ [])</a>
</div>
<div class="summary-synopsis"><p>Deletes the <code class="inline">key</code> from the given <code class="inline">app</code> environment</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#ensure_all_started/2">ensure_all_started(app, type \\ :temporary)</a>
</div>
<div class="summary-synopsis"><p>Ensures the given <code class="inline">app</code> and its applications are started</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#ensure_started/2">ensure_started(app, type \\ :temporary)</a>
</div>
<div class="summary-synopsis"><p>Ensures the given <code class="inline">app</code> is started</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#fetch_env!/2">fetch_env!(app, key)</a>
</div>
<div class="summary-synopsis"><p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#fetch_env/2">fetch_env(app, key)</a>
</div>
<div class="summary-synopsis"><p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment in a tuple</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#format_error/1">format_error(reason)</a>
</div>
<div class="summary-synopsis"><p>Formats the error reason returned by <a href="#start/2"><code class="inline">start/2</code></a>,
<a href="#ensure_started/2"><code class="inline">ensure_started/2</code></a>, <a href="#stop/1"><code class="inline">stop/1</code></a>, <a href="#load/1"><code class="inline">load/1</code></a> and <a href="#unload/1"><code class="inline">unload/1</code></a>,
returns a string</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get_all_env/1">get_all_env(app)</a>
</div>
<div class="summary-synopsis"><p>Returns all key-value pairs for <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get_application/1">get_application(module)</a>
</div>
<div class="summary-synopsis"><p>Gets the application for the given module</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#get_env/3">get_env(app, key, default \\ nil)</a>
</div>
<div class="summary-synopsis"><p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#load/1">load(app)</a>
</div>
<div class="summary-synopsis"><p>Loads the given <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#loaded_applications/0">loaded_applications()</a>
</div>
<div class="summary-synopsis"><p>Returns a list with information about the applications which have been loaded</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#put_env/4">put_env(app, key, value, opts \\ [])</a>
</div>
<div class="summary-synopsis"><p>Puts the <code class="inline">value</code> in <code class="inline">key</code> for the given <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#spec/1">spec(app)</a>
</div>
<div class="summary-synopsis"><p>Returns the spec for <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#spec/2">spec(app, key)</a>
</div>
<div class="summary-synopsis"><p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s specification</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#start/2">start(app, type \\ :temporary)</a>
</div>
<div class="summary-synopsis"><p>Starts the given <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#started_applications/1">started_applications(timeout \\ 5000)</a>
</div>
<div class="summary-synopsis"><p>Returns a list with information about the applications which are currently running</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#stop/1">stop(app)</a>
</div>
<div class="summary-synopsis"><p>Stops the given <code class="inline">app</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#unload/1">unload(app)</a>
</div>
<div class="summary-synopsis"><p>Unloads the given <code class="inline">app</code></p>
</div>
</div>
</div>
<div class="summary-callbacks summary">
<h2>
<a href="#callbacks">Callbacks</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:prep_stop/1">prep_stop(state)</a>
</div>
<div class="summary-synopsis"><p>Called before stopping the application</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:start/2">start(start_type, start_args)</a>
</div>
<div class="summary-synopsis"><p>Called when an application is started</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:start_phase/3">start_phase(phase, start_type, phase_args)</a>
</div>
<div class="summary-synopsis"><p>Start an application in synchronous phases</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:stop/1">stop(state)</a>
</div>
<div class="summary-synopsis"><p>Called after an application has been stopped</p>
</div>
</div>
</div>
</section>
<section id="types" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#types">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Types
</h1>
<div class="types-list">
<div class="detail" id="t:app/0">
<div class="detail-header">
<a href="#t:app/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">app()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L325" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>app() :: <a href="typespecs.html#basic-types">atom</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:key/0">
<div class="detail-header">
<a href="#t:key/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">key()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L326" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>key() :: <a href="typespecs.html#basic-types">atom</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:restart_type/0">
<div class="detail-header">
<a href="#t:restart_type/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">restart_type()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L330" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>restart_type() :: :permanent | :transient | :temporary</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:start_type/0">
<div class="detail-header">
<a href="#t:start_type/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">start_type()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L329" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start_type() :: :normal | {:takeover, <a href="typespecs.html#built-in-types">node</a>()} | {:failover, <a href="typespecs.html#built-in-types">node</a>()}</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:state/0">
<div class="detail-header">
<a href="#t:state/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">state()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L328" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>state() :: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
<div class="detail" id="t:value/0">
<div class="detail-header">
<a href="#t:value/0" class="detail-link" title="Link to this type">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this type</span>
</a>
<span class="signature">value()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L327" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>value() :: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
</section>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Functions
</h1>
<div class="detail" id="app_dir/1">
<div class="detail-header">
<a href="#app_dir/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">app_dir(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L651" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>app_dir(<a href="#t:app/0">app</a>()) :: <a href="String.html#t:t/0">String.t</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Gets the directory for app.</p>
<p>This information is returned based on the code path. Here is an
example:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">File</span><span class="o">.</span><span class="n">mkdir_p!</span><span class="p" data-group-id="3387993807-1">(</span><span class="s">"foo/ebin"</span><span class="p" data-group-id="3387993807-1">)</span><span class="w">
</span><span class="nc">Code</span><span class="o">.</span><span class="n">prepend_path</span><span class="p" data-group-id="3387993807-2">(</span><span class="s">"foo/ebin"</span><span class="p" data-group-id="3387993807-2">)</span><span class="w">
</span><span class="nc">Application</span><span class="o">.</span><span class="n">app_dir</span><span class="p" data-group-id="3387993807-3">(</span><span class="ss">:foo</span><span class="p" data-group-id="3387993807-3">)</span><span class="w">
</span><span class="c1">#=> "foo"</span></code></pre>
<p>Even though the directory is empty and there is no <code class="inline">.app</code> file
it is considered the application directory based on the name
“foo/ebin”. The name may contain a dash <code class="inline">-</code> which is considered
to be the app version and it is removed for the lookup purposes:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">File</span><span class="o">.</span><span class="n">mkdir_p!</span><span class="p" data-group-id="5743797359-1">(</span><span class="s">"bar-123/ebin"</span><span class="p" data-group-id="5743797359-1">)</span><span class="w">
</span><span class="nc">Code</span><span class="o">.</span><span class="n">prepend_path</span><span class="p" data-group-id="5743797359-2">(</span><span class="s">"bar-123/ebin"</span><span class="p" data-group-id="5743797359-2">)</span><span class="w">
</span><span class="nc">Application</span><span class="o">.</span><span class="n">app_dir</span><span class="p" data-group-id="5743797359-3">(</span><span class="ss">:bar</span><span class="p" data-group-id="5743797359-3">)</span><span class="w">
</span><span class="c1">#=> "bar-123"</span></code></pre>
<p>For more information on code paths, check the <a href="Code.html"><code class="inline">Code</code></a> module in
Elixir and also Erlang’s <a href="http://www.erlang.org/doc/man/code.html"><code class="inline">:code</code> module</a>.</p>
</section>
</div>
<div class="detail" id="app_dir/2">
<div class="detail-header">
<a href="#app_dir/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">app_dir(app, path)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L684" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>app_dir(<a href="#t:app/0">app</a>(), <a href="String.html#t:t/0">String.t</a>() | [<a href="String.html#t:t/0">String.t</a>()]) :: <a href="String.html#t:t/0">String.t</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Returns the given path inside <a href="#app_dir/1"><code class="inline">app_dir/1</code></a>.</p>
<p>If <code class="inline">path</code> is a string, then it will be used as the path inside <a href="#app_dir/1"><code class="inline">app_dir/1</code></a>. If
<code class="inline">path</code> is a list of strings, it will be joined (see <a href="Path.html#join/1"><code class="inline">Path.join/1</code></a>) and the result
will be used as the path inside <a href="#app_dir/1"><code class="inline">app_dir/1</code></a>.</p>
<h2 id="app_dir/2-examples" class="section-heading">
<a href="#app_dir/2-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<pre><code class="nohighlight makeup elixir"><span class="nc">File</span><span class="o">.</span><span class="n">mkdir_p!</span><span class="p" data-group-id="6230944988-1">(</span><span class="s">"foo/ebin"</span><span class="p" data-group-id="6230944988-1">)</span><span class="w">
</span><span class="nc">Code</span><span class="o">.</span><span class="n">prepend_path</span><span class="p" data-group-id="6230944988-2">(</span><span class="s">"foo/ebin"</span><span class="p" data-group-id="6230944988-2">)</span><span class="w">
</span><span class="nc">Application</span><span class="o">.</span><span class="n">app_dir</span><span class="p" data-group-id="6230944988-3">(</span><span class="ss">:foo</span><span class="p">,</span><span class="w"> </span><span class="s">"my_path"</span><span class="p" data-group-id="6230944988-3">)</span><span class="w">
</span><span class="c1">#=> "foo/my_path"</span><span class="w">
</span><span class="nc">Application</span><span class="o">.</span><span class="n">app_dir</span><span class="p" data-group-id="6230944988-4">(</span><span class="ss">:foo</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="6230944988-5">[</span><span class="s">"my"</span><span class="p">,</span><span class="w"> </span><span class="s">"nested"</span><span class="p">,</span><span class="w"> </span><span class="s">"path"</span><span class="p" data-group-id="6230944988-5">]</span><span class="p" data-group-id="6230944988-4">)</span><span class="w">
</span><span class="c1">#=> "foo/my/nested/path"</span></code></pre>
</section>
</div>
<div class="detail" id="delete_env/3">
<span id="delete_env/2"></span>
<div class="detail-header">
<a href="#delete_env/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">delete_env(app, key, opts \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L521" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>delete_env(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>(), timeout: <a href="typespecs.html#built-in-types">timeout</a>(), persistent: <a href="typespecs.html#built-in-types">boolean</a>()) :: :ok</pre>
</div>
</div>
<section class="docstring">
<p>Deletes the <code class="inline">key</code> from the given <code class="inline">app</code> environment.</p>
<p>See <a href="#put_env/4"><code class="inline">put_env/4</code></a> for a description of the options.</p>
</section>
</div>
<div class="detail" id="ensure_all_started/2">
<span id="ensure_all_started/1"></span>
<div class="detail-header">
<a href="#ensure_all_started/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">ensure_all_started(app, type \\ :temporary)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L548" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>ensure_all_started(<a href="#t:app/0">app</a>(), <a href="#t:restart_type/0">restart_type</a>()) ::
{:ok, [<a href="#t:app/0">app</a>()]} | {:error, {<a href="#t:app/0">app</a>(), <a href="typespecs.html#built-in-types">term</a>()}}</pre>
</div>
</div>
<section class="docstring">
<p>Ensures the given <code class="inline">app</code> and its applications are started.</p>
<p>Same as <a href="#start/2"><code class="inline">start/2</code></a> but also starts the applications listed under
<code class="inline">:applications</code> in the <code class="inline">.app</code> file in case they were not previously
started.</p>
</section>
</div>
<div class="detail" id="ensure_started/2">
<span id="ensure_started/1"></span>
<div class="detail-header">
<a href="#ensure_started/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">ensure_started(app, type \\ :temporary)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L536" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>ensure_started(<a href="#t:app/0">app</a>(), <a href="#t:restart_type/0">restart_type</a>()) :: :ok | {:error, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Ensures the given <code class="inline">app</code> is started.</p>
<p>Same as <a href="#start/2"><code class="inline">start/2</code></a> but returns <code class="inline">:ok</code> if the application was already
started. This is useful in scripts and in test setup, where test
applications need to be explicitly started:</p>
<pre><code class="nohighlight makeup elixir"><span class="ss">:ok</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">Application</span><span class="o">.</span><span class="n">ensure_started</span><span class="p" data-group-id="1658191076-1">(</span><span class="ss">:my_test_dep</span><span class="p" data-group-id="1658191076-1">)</span></code></pre>
</section>
</div>
<div class="detail" id="fetch_env!/2">
<div class="detail-header">
<a href="#fetch_env!/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">fetch_env!(app, key)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L467" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>fetch_env!(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>()) :: <a href="#t:value/0">value</a>() | <a href="typespecs.html#built-in-types">no_return</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment.</p>
<p>If the configuration parameter does not exist, raises <a href="ArgumentError.html"><code class="inline">ArgumentError</code></a>.</p>
</section>
</div>
<div class="detail" id="fetch_env/2">
<div class="detail-header">
<a href="#fetch_env/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">fetch_env(app, key)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L454" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>fetch_env(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>()) :: {:ok, <a href="#t:value/0">value</a>()} | :error</pre>
</div>
</div>
<section class="docstring">
<p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment in a tuple.</p>
<p>If the configuration parameter does not exist, the function returns <code class="inline">:error</code>.</p>
</section>
</div>
<div class="detail" id="format_error/1">
<div class="detail-header">
<a href="#format_error/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">format_error(reason)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L710" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>format_error(<a href="typespecs.html#basic-types">any</a>()) :: <a href="String.html#t:t/0">String.t</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Formats the error reason returned by <a href="#start/2"><code class="inline">start/2</code></a>,
<a href="#ensure_started/2"><code class="inline">ensure_started/2</code></a>, <a href="#stop/1"><code class="inline">stop/1</code></a>, <a href="#load/1"><code class="inline">load/1</code></a> and <a href="#unload/1"><code class="inline">unload/1</code></a>,
returns a string.</p>
</section>
</div>
<div class="detail" id="get_all_env/1">
<div class="detail-header">
<a href="#get_all_env/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get_all_env(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L398" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get_all_env(<a href="#t:app/0">app</a>()) :: [{<a href="#t:key/0">key</a>(), <a href="#t:value/0">value</a>()}]</pre>
</div>
</div>
<section class="docstring">
<p>Returns all key-value pairs for <code class="inline">app</code>.</p>
</section>
</div>
<div class="detail" id="get_application/1">
<div class="detail-header">
<a href="#get_application/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get_application(module)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L387" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get_application(<a href="typespecs.html#basic-types">atom</a>()) :: <a href="typespecs.html#basic-types">atom</a>() | nil</pre>
</div>
</div>
<section class="docstring">
<p>Gets the application for the given module.</p>
<p>The application is located by analyzing the spec
of all loaded applications. Returns <code class="inline">nil</code> if
the module is not listed in any application spec.</p>
</section>
</div>
<div class="detail" id="get_env/3">
<span id="get_env/2"></span>
<div class="detail-header">
<a href="#get_env/3" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">get_env(app, key, default \\ nil)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L444" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>get_env(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>(), <a href="#t:value/0">value</a>()) :: <a href="#t:value/0">value</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s environment.</p>
<p>If the configuration parameter does not exist, the function returns the
<code class="inline">default</code> value.</p>
<h2 id="get_env/3-examples" class="section-heading">
<a href="#get_env/3-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p><a href="#get_env/3"><code class="inline">get_env/3</code></a> is commonly used to read the configuration of your OTP applications.
Since Mix configurations are commonly used to configure applications, we will use
this as a point of illustration.</p>
<p>Consider a new application <code class="inline">:my_app</code>. <code class="inline">:my_app</code> contains a database engine which
supports a pool of databases. The database engine needs to know the configuration for
each of those databases, and that configuration is supplied by key-value pairs in
environment of <code class="inline">:my_app</code>.</p>
<pre><code class="nohighlight makeup elixir"><span class="n">config</span><span class="w"> </span><span class="ss">:my_app</span><span class="p">,</span><span class="w"> </span><span class="nc">Databases.RepoOne</span><span class="p">,</span><span class="w">
</span><span class="c1"># A database configuration</span><span class="w">
</span><span class="ss">ip</span><span class="p">:</span><span class="w"> </span><span class="s">"localhost"</span><span class="w">
</span><span class="ss">port</span><span class="p">:</span><span class="w"> </span><span class="mi">5433</span><span class="w">
</span><span class="n">config</span><span class="w"> </span><span class="ss">:my_app</span><span class="p">,</span><span class="w"> </span><span class="nc">Databases.RepoTwo</span><span class="p">,</span><span class="w">
</span><span class="c1"># Another database configuration (for the same OTP app)</span><span class="w">
</span><span class="ss">ip</span><span class="p">:</span><span class="w"> </span><span class="s">"localhost"</span><span class="w">
</span><span class="ss">port</span><span class="p">:</span><span class="w"> </span><span class="mi">20717</span><span class="w">
</span><span class="n">config</span><span class="w"> </span><span class="ss">:my_app</span><span class="p">,</span><span class="w"> </span><span class="ss">my_app_databases</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="6033332399-1">[</span><span class="nc">Databases.RepoOne</span><span class="p">,</span><span class="w"> </span><span class="nc">Databases.RepoTwo</span><span class="p" data-group-id="6033332399-1">]</span></code></pre>
<p>Our database engine used by <code class="inline">:my_app</code> needs to know what databases exist, and
what the database configurations are. The database engine can make a call to
<code class="inline">get_env(:my_app, :my_app_databases)</code> to retrieve the list of databases (specified
by module names). Our database engine can then traverse each repository in the
list and then call <code class="inline">get_env(:my_app, Databases.RepoOne)</code> and so forth to retrieve
the configuration of each one.</p>
<p><strong>Important:</strong> if you are writing a library to be used by other developers,
it is generally recommended to avoid the application environment, as the
application environment is effectively a global storage. For more information,
read our <a href="/library-guidelines.html">library guidelines</a>.</p>
</section>
</div>
<div class="detail" id="load/1">
<div class="detail-header">
<a href="#load/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">load(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L611" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>load(<a href="#t:app/0">app</a>()) :: :ok | {:error, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Loads the given <code class="inline">app</code>.</p>
<p>In order to be loaded, an <code class="inline">.app</code> file must be in the load paths.
All <code class="inline">:included_applications</code> will also be loaded.</p>
<p>Loading the application does not start it nor load its modules, but
it does load its environment.</p>
</section>
</div>
<div class="detail" id="loaded_applications/0">
<div class="detail-header">
<a href="#loaded_applications/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">loaded_applications()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L700" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>loaded_applications() :: [
{<a href="#t:app/0">app</a>(), description :: <a href="typespecs.html#built-in-types">charlist</a>(), vsn :: <a href="typespecs.html#built-in-types">charlist</a>()}
]</pre>
</div>
</div>
<section class="docstring">
<p>Returns a list with information about the applications which have been loaded.</p>
</section>
</div>
<div class="detail" id="put_env/4">
<span id="put_env/3"></span>
<div class="detail-header">
<a href="#put_env/4" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">put_env(app, key, value, opts \\ [])</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L511" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>put_env(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>(), <a href="#t:value/0">value</a>(), timeout: <a href="typespecs.html#built-in-types">timeout</a>(), persistent: <a href="typespecs.html#built-in-types">boolean</a>()) ::
:ok</pre>
</div>
</div>
<section class="docstring">
<p>Puts the <code class="inline">value</code> in <code class="inline">key</code> for the given <code class="inline">app</code>.</p>
<h2 id="put_env/4-options" class="section-heading">
<a href="#put_env/4-options" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Options
</h2>
<ul>
<li><code class="inline">:timeout</code> - the timeout for the change (defaults to <code class="inline">5_000</code> milliseconds)
</li>
<li><code class="inline">:persistent</code> - persists the given value on application load and reloads
</li>
</ul>
<p>If <a href="#put_env/4"><code class="inline">put_env/4</code></a> is called before the application is loaded, the application
environment values specified in the <code class="inline">.app</code> file will override the ones
previously set.</p>
<p>The persistent option can be set to <code class="inline">true</code> when there is a need to guarantee
parameters set with this function will not be overridden by the ones defined
in the application resource file on load. This means persistent values will
stick after the application is loaded and also on application reload.</p>
</section>
</div>
<div class="detail" id="spec/1">
<div class="detail-header">
<a href="#spec/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">spec(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L357" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>spec(<a href="#t:app/0">app</a>()) :: [{<a href="#t:key/0">key</a>(), <a href="#t:value/0">value</a>()}] | nil</pre>
</div>
</div>
<section class="docstring">
<p>Returns the spec for <code class="inline">app</code>.</p>
<p>The following keys are returned:</p>
<ul>
<li><code class="inline">:description</code>
</li>
<li><code class="inline">:id</code>
</li>
<li><code class="inline">:vsn</code>
</li>
<li><code class="inline">:modules</code>
</li>
<li><code class="inline">:maxP</code>
</li>
<li><code class="inline">:maxT</code>
</li>
<li><code class="inline">:registered</code>
</li>
<li><code class="inline">:included_applications</code>
</li>
<li><code class="inline">:applications</code>
</li>
<li><code class="inline">:mod</code>
</li>
<li><code class="inline">:start_phases</code>
</li>
</ul>
<p>Note the environment is not returned as it can be accessed via
<a href="#fetch_env/2"><code class="inline">fetch_env/2</code></a>. Returns <code class="inline">nil</code> if the application is not loaded.</p>
</section>
</div>
<div class="detail" id="spec/2">
<div class="detail-header">
<a href="#spec/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">spec(app, key)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L372" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>spec(<a href="#t:app/0">app</a>(), <a href="#t:key/0">key</a>()) :: <a href="#t:value/0">value</a>() | nil</pre>
</div>
</div>
<section class="docstring">
<p>Returns the value for <code class="inline">key</code> in <code class="inline">app</code>’s specification.</p>
<p>See <a href="#spec/1"><code class="inline">spec/1</code></a> for the supported keys. If the given
specification parameter does not exist, this function
will raise. Returns <code class="inline">nil</code> if the application is not loaded.</p>
</section>
</div>
<div class="detail" id="start/2">
<span id="start/1"></span>
<div class="detail-header">
<a href="#start/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">start(app, type \\ :temporary)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L587" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start(<a href="#t:app/0">app</a>(), <a href="#t:restart_type/0">restart_type</a>()) :: :ok | {:error, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Starts the given <code class="inline">app</code>.</p>
<p>If the <code class="inline">app</code> is not loaded, the application will first be loaded using <a href="#load/1"><code class="inline">load/1</code></a>.
Any included application, defined in the <code class="inline">:included_applications</code> key of the
<code class="inline">.app</code> file will also be loaded, but they won’t be started.</p>
<p>Furthermore, all applications listed in the <code class="inline">:applications</code> key must be explicitly
started before this application is. If not, <code class="inline">{:error, {:not_started, app}}</code> is
returned, where <code class="inline">app</code> is the name of the missing application.</p>
<p>In case you want to automatically load <strong>and start</strong> all of <code class="inline">app</code>’s dependencies,
see <a href="#ensure_all_started/2"><code class="inline">ensure_all_started/2</code></a>.</p>
<p>The <code class="inline">type</code> argument specifies the type of the application:</p>
<ul>
<li><p><code class="inline">:permanent</code> - if <code class="inline">app</code> terminates, all other applications and the entire
node are also terminated.</p>
</li>
<li><p><code class="inline">:transient</code> - if <code class="inline">app</code> terminates with <code class="inline">:normal</code> reason, it is reported
but no other applications are terminated. If a transient application
terminates abnormally, all other applications and the entire node are
also terminated.</p>
</li>
<li><p><code class="inline">:temporary</code> - if <code class="inline">app</code> terminates, it is reported but no other
applications are terminated (the default).</p>
</li>
</ul>
<p>Note that it is always possible to stop an application explicitly by calling
<a href="#stop/1"><code class="inline">stop/1</code></a>. Regardless of the type of the application, no other applications will
be affected.</p>
<p>Note also that the <code class="inline">:transient</code> type is of little practical use, since when a
supervision tree terminates, the reason is set to <code class="inline">:shutdown</code>, not <code class="inline">:normal</code>.</p>
</section>
</div>
<div class="detail" id="started_applications/1">
<span id="started_applications/0"></span>
<div class="detail-header">
<a href="#started_applications/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">started_applications(timeout \\ 5000)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L692" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>started_applications(<a href="typespecs.html#built-in-types">timeout</a>()) :: [
{<a href="#t:app/0">app</a>(), description :: <a href="typespecs.html#built-in-types">charlist</a>(), vsn :: <a href="typespecs.html#built-in-types">charlist</a>()}
]</pre>
</div>
</div>
<section class="docstring">
<p>Returns a list with information about the applications which are currently running.</p>
</section>
</div>
<div class="detail" id="stop/1">
<div class="detail-header">
<a href="#stop/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">stop(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L597" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>stop(<a href="#t:app/0">app</a>()) :: :ok | {:error, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Stops the given <code class="inline">app</code>.</p>
<p>When stopped, the application is still loaded.</p>
</section>
</div>
<div class="detail" id="unload/1">
<div class="detail-header">
<a href="#unload/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">unload(app)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L622" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>unload(<a href="#t:app/0">app</a>()) :: :ok | {:error, <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Unloads the given <code class="inline">app</code>.</p>
<p>It will also unload all <code class="inline">:included_applications</code>.
Note that the function does not purge the application modules.</p>
</section>
</div>
</section>
<section id="callbacks" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#callbacks">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Callbacks
</h1>
<div class="detail" id="c:prep_stop/1">
<div class="detail-header">
<a href="#c:prep_stop/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">prep_stop(state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L279" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(optional)</span>
<div class="specs">
<pre>prep_stop(<a href="#t:state/0">state</a>()) :: <a href="#t:state/0">state</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Called before stopping the application.</p>
<p>This function is called before the top-level supervisor is terminated. It
receives the state returned by <a href="#c:start/2"><code class="inline">start/2</code></a>, if it did, or <code class="inline">[]</code> otherwise.
The return value is later passed to <a href="#c:stop/1"><code class="inline">stop/1</code></a>.</p>
</section>
</div>
<div class="detail" id="c:start/2">
<div class="detail-header">
<a href="#c:start/2" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">start(start_type, start_args)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L267" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>start(<a href="#t:start_type/0">start_type</a>(), start_args :: <a href="typespecs.html#built-in-types">term</a>()) ::
{:ok, <a href="typespecs.html#basic-types">pid</a>()} | {:ok, <a href="typespecs.html#basic-types">pid</a>(), <a href="#t:state/0">state</a>()} | {:error, reason :: <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Called when an application is started.</p>
<p>This function is called when an application is started using
<a href="Application.html#start/2"><code class="inline">Application.start/2</code></a> (and functions on top of that, such as
<a href="Application.html#ensure_started/2"><code class="inline">Application.ensure_started/2</code></a>). This function should start the top-level
process of the application (which should be the top supervisor of the
application’s supervision tree if the application follows the OTP design
principles around supervision).</p>
<p><code class="inline">start_type</code> defines how the application is started:</p>
<ul>
<li><code class="inline">:normal</code> - used if the startup is a normal startup or if the application
is distributed and is started on the current node because of a failover
from another node and the application specification key <code class="inline">:start_phases</code>
is <code class="inline">:undefined</code>.
</li>
<li><code class="inline">{:takeover, node}</code> - used if the application is distributed and is
started on the current node because of a failover on the node <code class="inline">node</code>.
</li>
<li><code class="inline">{:failover, node}</code> - used if the application is distributed and is
started on the current node because of a failover on node <code class="inline">node</code>, and the
application specification key <code class="inline">:start_phases</code> is not <code class="inline">:undefined</code>.
</li>
</ul>
<p><code class="inline">start_args</code> are the arguments passed to the application in the <code class="inline">:mod</code>
specification key (e.g., <code class="inline">mod: {MyApp, [:my_args]}</code>).</p>
<p>This function should either return <code class="inline">{:ok, pid}</code> or <code class="inline">{:ok, pid, state}</code> if
startup is successful. <code class="inline">pid</code> should be the PID of the top supervisor. <code class="inline">state</code>
can be an arbitrary term, and if omitted will default to <code class="inline">[]</code>; if the
application is later stopped, <code class="inline">state</code> is passed to the <a href="#stop/1"><code class="inline">stop/1</code></a> callback (see
the documentation for the <a href="#c:stop/1"><code class="inline">stop/1</code></a> callback for more information).</p>
<p><code class="inline">use Application</code> provides no default implementation for the <a href="#start/2"><code class="inline">start/2</code></a>
callback.</p>
</section>
</div>
<div class="detail" id="c:start_phase/3">
<div class="detail-header">
<a href="#c:start_phase/3" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">start_phase(phase, start_type, phase_args)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L306" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(optional)</span>
<div class="specs">
<pre>start_phase(phase :: <a href="typespecs.html#built-in-types">term</a>(), <a href="#t:start_type/0">start_type</a>(), phase_args :: <a href="typespecs.html#built-in-types">term</a>()) ::
:ok | {:error, reason :: <a href="typespecs.html#built-in-types">term</a>()}</pre>
</div>
</div>
<section class="docstring">
<p>Start an application in synchronous phases.</p>
<p>This function is called after <a href="#start/2"><code class="inline">start/2</code></a> finishes but before
<a href="Application.html#start/2"><code class="inline">Application.start/2</code></a> returns. It will be called once for every start phase
defined in the application’s (and any included applications’) specification,
in the order they are listed in.</p>
</section>
</div>
<div class="detail" id="c:stop/1">
<div class="detail-header">
<a href="#c:stop/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">stop(state)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/elixir/lib/application.ex#L296" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>stop(<a href="#t:state/0">state</a>()) :: <a href="typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p>Called after an application has been stopped.</p>
<p>This function is called after an application has been stopped, i.e., after its
supervision tree has been stopped. It should do the opposite of what the
<a href="#c:start/2"><code class="inline">start/2</code></a> callback did, and should perform any necessary cleanup. The return
value of this callback is ignored.</p>
<p><code class="inline">state</code> is the state returned by <a href="#c:start/2"><code class="inline">start/2</code></a>, if it did, or <code class="inline">[]</code> otherwise.
If the optional callback <a href="#c:prep_stop/1"><code class="inline">prep_stop/1</code></a> is present, <code class="inline">state</code> is its return
value instead.</p>
<p><code class="inline">use Application</code> defines a default implementation of this function which does
nothing and just returns <code class="inline">:ok</code>.</p>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
016232f1d9a3f7bee85855d35a2bca58
>
files
>
26
