app(4)

app(4) 💅 — Erlang Module Definition

okay so bestie, welcome to app(4), the Erlang Module Definition for the application resource file. It's literally the blueprint for which resources an application uses and how it gets started. Main-character energy only. ✨

🌸 NAME 🌸

app — Application resource file. Short, iconic, done. 💖

🦋 DESCRIPTION 🦋

The application resource file is the receipts for the resources an application uses and how the application is started. There must always be one application resource file called Application.app for each application Application in the system. That's non-negotiable, bestie.

The application controller reads this file when an application is loaded/started. The functions in systools also use it, for example when generating start scripts. Obsessed with a file that does both. 💅

🎀 File Syntax 🎀

The file is to be called Application.app, where Application is the application name. It is to be located in directory ebin for the application.

The file must contain a single Erlang term, which is called an application specification:

{application, Application,
  [{description,  Description},
   {id,           Id},
   {vsn,          Vsn},
   {modules,      Modules},
   {maxP,         MaxP},
   {maxT,         MaxT},
   {registered,   Names},
   {included_applications, Apps},
   {optional_applications, Apps},
   {applications, Apps},
   {env,          Env},
   {mod,          Start},
   {start_phases, Phases},
   {runtime_dependencies, RTDeps}]}.

Here's the value/default menu — every row is important, no skipping:

Value                Default
-----                -------
Application  atom()               -
Description  string()             ""
Id           string()             ""
Vsn          string()             ""
Modules      [Module]             []
MaxP         int()                infinity
MaxT         int()                infinity
Names        [Name]               []
Apps         [App]                []
Env          [{Par,Val}]          []
Start        {Module,StartArgs}   []
Phases       [{Phase,PhaseArgs}]  undefined
RTDeps       [ApplicationVersion] []

And the type definitions, because we keep it precise:

Module = Name = App = Par = Phase = atom()
Val = StartArgs = PhaseArgs = term()
ApplicationVersion = string()

• Application — Application name. 👑

For the application controller, all keys are optional. The respective default values are used for any omitted keys. Chill.

The functions in systools require more information. If they are used, the following keys are mandatory:

• description
• vsn
• modules
• registered
• applications

The other keys are ignored by systools. That's the rule, bestie. 💀

• description — A one-line description of the application. One line. Don't write a novel. 🎀
• id — Product identification, or similar. You know, the ID vibe. 🪪
• vsn — Version of the application. The version. The vsn. Slay. ⭐
• modules — Every module this application introduces. systools uses this list when generating start scripts and tar files. A module can only be defined in one application. No module double-booking, periodt. 🚫
• maxP — 🚨 Deprecated - is ignored. Maximum number of processes allowed in the application. It's still in the manual, but it's ignored, so don't build your whole personality around it. 💀
• maxT — Maximum time, in milliseconds, that the application is allowed to run. After the specified time, the application terminates automatically. So yes, it will shut itself down. ⏰
• registered — All names of registered processes started in this application. systools uses this list to detect name clashes between different applications. Name-clash detection is lowkey iconic. 💅
• included_applications — All applications included by this application. When this application is started, all included applications are loaded automatically, but not started, by the application controller. It is assumed that the top-most supervisor of the included application is started by a supervisor of this application. Loaded, not started — say it with me. 👀
• applications — All applications that must be started before this application. If an application is also listed in optional_applications, then the application is not required to exist (but if it exists, it is also guaranteed to be started before this one). systools uses this list to generate correct start scripts. Defaults to the empty list, but notice that all applications have dependencies to (at least) Kernel and STDLIB. Kernel and STDLIB are always in the group chat. 🫶
• optional_applications — A list of applications that are optional. Note: if you want an optional dependency to be automatically started before the current application whenever it is available, it must be listed on both applications and optional_applications. Both. Lists. Bestie. ✨
• env — Configuration parameters used by the application. The value of a configuration parameter is retrieved by calling application:get_env/1,2. The values in the application resource file can be overridden by values in a configuration file (see config(4)) or by command-line flags (see erts:erl(1)). Overridable, documented, and cute. 💅
• mod — Specifies the application callback module and a start argument, see application. Key mod is necessary for an application implemented as a supervision tree, otherwise the application controller does not know how to start it. mod can be omitted for applications without processes, typically code libraries, for example, STDLIB. Supervision tree? You need mod. Code library with no processes? You can leave it out. 🧚
• start_phases — A list of start phases and corresponding start arguments for the application. If this key is present, the application master, in addition to the usual call to Module:start/2, also calls Module:start_phase(Phase,Type,PhaseArgs) for each start phase defined by key start_phases. Only after this extended start procedure, application:start(Application) returns. So the start call is not done until the phases are done. 🌈

Start phases can be used to synchronize startup of an application and its included applications. In this case, key mod must be specified as follows:

{mod, {application_starter,[Module,StartArgs]}}

The application master then calls Module:start/2 for the primary application, followed by calls to Module:start_phase/3 for each start phase (as defined for the primary application), both for the primary application and for each of its included applications, for which the start phase is defined.

This implies that for an included application, the set of start phases must be a subset of the set of phases defined for the primary application. For more information, see Applications in OTP Design Principles. Subset, not superset — write that down. 🫡

• runtime_dependencies — A list of application versions that the application depends on. An example of such an application version is "kernel-3.0". Application versions specified as runtime dependencies are minimum requirements. That is, a larger application version than the one specified in the dependency satisfies the requirement. For information about how to compare application versions, see section Versions in the System Principles User's Guide. Minimum requirement means a bigger version can still satisfy it. ✅

Notice that the application version specifies a source code version. One more, indirect, requirement is that the installed binary application of the specified version is built so that it is compatible with the rest of the system. So it's not just the source version — the installed binary has to be compatible with the rest of the system too. 🧠

Some dependencies can only be required in specific runtime scenarios. When such optional dependencies exist, these are specified and documented in the corresponding "App" documentation of the specific application. Optional dependency lore lives in that app's own docs. 📚

🌟 See Also 🌟

• application
• systools

---

Cute sign-off, bestie: source is Ericsson AB, version is kernel 11.0.4, and the manual page is app(4). The footer doesn't print a date, so I'm not inventing one — that's the whole footer tea. 💅✨