> ## 8 Included Applications

> ### 8.1 Definition

> An application can include other applications. An included application has its own application directory and `.app` file, but it is started as part of the supervisor tree of another application.

> An application can only be included by one other application.

> An included application can include other applications.

> An application which is not included by any other application is called a primary application.

> Primary Application and Included Applications.

> The application controller will automatically load any included applications when loading a primary application, but not start them. Instead, the top supervisor of the included application must be started by a supervisor in the including application.

> This means that when running, an included application is in fact part of the primary application and a process in an included application will consider itself belonging to the primary application.

> ### 8.2 Specifying Included Applications

> Which applications to include is defined by the `included_applications` key in the `.app` file.

>     {application, treeapp,
>      [{description, "Tree application"},
>       {vsn, "1"},
>       {modules, [treeapp_cb, treeapp_sup, treeapp_server]},
>       {registered, [treeapp_server]},
>       {included_applications, [subtreeapp]},
>       {applications, [kernel, stdlib, sasl]},
>       {mod, {treeapp_cb,[]}},
>       {env, [{file, "/usr/local/log"}]}
>      ]}.

> ### 8.3 Synchronizing Processes During Startup

> The supervisor tree of an included application is started as part of the supervisor tree of the including application. If there is a need for synchronization between processes in the including and included applications, this can be achieved by using start phases.

> Start phases are defined by the `start_phases` key in the `.app` file.

>     {application, treeapp,
>      [{description, "Tree application"},
>       {vsn, "1"},
>       {modules, [treeapp_cb, treeapp_sup, treeapp_server]},
>       {registered, [treeapp_server]},
>       {included_applications, [subtreeapp]},
>       {start_phases, [{init,[]}, {go,[]}]},
>       {applications, [kernel, stdlib, sasl]},
>       {mod, {treeapp_cb,[]}},
>       {env, [{file, "/usr/local/log"}]}
>      ]}.

>     {application, subtreeapp,
>      [{description, "Included application"},
>       {vsn, "1"},
>       {modules, [subtreeapp_sup, subtreeapp_server]},
>       {registered, []},
>       {start_phases, [{go,[]}]},
>       {applications, [kernel, stdlib, sasl]},
>       {mod, {subtreeapp_cb,[]}}
>      ]}.

> A start phase is defined as a tuple `{Phase,PhaseArgs}`, where `Phase` is an atom and `PhaseArgs` is a term.

> When starting a primary application with included applications, the primary application is started the normal way: The application controller creates an application master for the application, and the application master calls `Module:start(normal, StartArgs)` to start the top supervisor.

> Then, for the primary application and each included application in top-down, left-to-right order, the application master calls `Module:start_phase(Phase, Type, PhaseArgs)` for each phase defined for for the primary application, in that order. Note that if a phase is not defined for an included application, the function is not called for this phase and application.

> The following requirements apply to the `.app` file for an included application:

> - The `{mod, {Module,StartArgs}}` option must be included. This option is used to find the callback module `Module` of the application. `StartArgs` is ignored, as `Module:start/2` is called only for the primary application.
> - The `{start_phases, [{Phase,PhaseArgs}]}` option must be included, and the set of specified phases must be a subset of the set of phases specified for the including application.

Copyright © 1991-2003 Ericsson Utvecklings AB