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}
, wherePhase
is an atom andPhaseArgs
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 moduleModule
of the application.StartArgs
is ignored, asModule: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.