app(5)

📦
version 25.3.2.8 · 3 versions
, in ubuntu noble

💖 app(5) — bestie, it's the manual for app, the Application resource file 💖

okay so welcome to the Files manual section, and today we're talking about app — your application resource file. she's the blueprint, the vibe check, the whole origin story of an OTP app. let's get into it 🫶

✨ NAME ✨

app — Application resource file. yeah. that's her. 💅

🌸 DESCRIPTION 🌸

so the application resource file is the lil document that says what resources an application uses and how the application is started. and listen — for each application Application in the system, there must always be one application resource file, and it's called Application.app. no exceptions bestie, it's giving mandatory.

who reads this file? the application controller, when an application is loaded/started. also the functions in systools read it, like when they're generating start scripts. so she's popular. 👑

🎀 FILE SYNTAX 🎀

the naming + location rules (important!!)

  • the application resource file must be called Application.app, where Application is the application name
  • it has to live in the directory ebin for the application

the one term to rule them all

the file must contain a single Erlang term, and that term 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}]}.

the values and their defaults 📋

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

and the type deets:

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

💜 Application

Application name. short and sweet, that's her.

so who requires what?? 🕵️

for the application controller, all keys are optional. any key you skip just gets its respective default value. lowkey generous of her.

but the functions in systools need more info. if you're using them, these keys are mandatory:

  • description
  • vsn
  • modules
  • registered
  • applications

the other keys? systools straight up ignores them. not her business. 💀

🌟 description:

a one-line description of the application. literally one line. keep it cute.

🌟 id:

Product identification, or similar.

🌟 vsn:

Version of the application.

🌟 modules:

All modules introduced by this application. systools uses this list when generating start scripts and tar files. and heads up: a module can only be defined in one application. no double-dipping, bestie. 🙈

🌟 maxP:

Deprecated - is ignored

Maximum number of processes allowed in the application. she's retired, we don't talk about her anymore 💅

🌟 maxT:

Maximum time, in milliseconds, that the application is allowed to run. after the specified time, the application terminates automatically. clock's ticking ⏰

🌟 registered:

All names of registered processes started in this application. systools uses this list to detect name clashes between different applications. she's the peacekeeper fr fr 🕊️

🌟 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's assumed that the top-most supervisor of the included application is started by a supervisor of this application. so like, loaded but not launched. she's on standby 🧚

🌟 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 does exist, it's 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. yes even the tiny ones. everyone needs Kernel and STDLIB, it's giving "you can't sit with us unless—" 😌

🌟 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's available, it must be listed on both applications and optional_applications. both. say it with me. both. 💅

🌟 env:

Configuration parameters used by the application. the value of a configuration parameter is retrieved by calling application:get_env/1,2. and plot twist — the values in the application resource file can be overridden by values in a configuration file (see config(5)) or by command-line flags (see erts:erl(1)). so if your env isn't what you expected, check who's been messing with it 👀

🌟 mod:

Specifies the application callback module and a start argument, see application(3erl).

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. no processes, no problem, no mod. ✨

🌟 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 she's not coming back until she's done, okay? she's thorough. 💅

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. no extra phases that the primary doesn't know about, bestie, that's not how this works. for more information, see OTP Design Principles.

🌟 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.

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.

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.

⚠️ Warning: The runtime_dependencies key was introduced in OTP 17.0. The type of its value might be subject to changes during the OTP 17 release.
⚠️ Warning: All runtime dependencies specified in OTP applications during the OTP 17 release may not be completely correct. This is actively being worked on. Declared runtime dependencies in OTP applications are expected to be correct in OTP 18.

🦋 SEE ALSO 🦋

and that's the whole page, bestie!! you ate this. 💅✨ go forth and write a flawless Application.app, you've got this, i believe in you fr fr 🫶🌸

signed, sealed, delivered with love from Ericsson AB — kernel 8.5.4.2 — and the app(5) manual page herself. mwah 💖👑🌈

📦 where this page comes from