When you have written code implementing some specific functionality you might want to make the code into an application, that is, a component that can be started and stopped as a unit, and which can also be reused in other systems.

To do this, create an application callback module, and describe how the application is to be started and stopped.

Then, an application specification is needed, which is put in an application resource file. Among other things, this file specifies which modules the application consists of and the name of the callback module.

If you use systools, the Erlang/OTP tools for packaging code (see Releases), the code for each application is placed in a separate directory following a pre-defined directory structure.

How to start and stop the code for the application, that is, the supervision tree, is described by two callback functions:

Example of an application callback module for packaging the supervision tree from Supervisor Behaviour:

A library application that cannot be started or stopped, does not need any application callback module.

To define an application, an application specification is created, which is put in an application resource file, or in short an .app file:

The contents of a minimal .app file for a library application libapp looks as follows:

The contents of a minimal .app file ch_app.app for a supervision tree application like ch_app looks as follows:

The key mod defines the callback module and start argument of the application, in this case ch_app and [], respectively. This means that the following is called when the application is to be started:

The following is called when the application is stopped.

When using systools, the Erlang/OTP tools for packaging code (see Section Releases), the keys description, vsn, modules, registered, and applications are also to be specified:

When packaging code using systools, the code for each application is placed in a separate directory, lib/Application-Vsn, where Vsn is the version number.

This can be useful to know, even if systools is not used, since Erlang/OTP is packaged according to the OTP principles and thus comes with this directory structure. The code server (see the code(3) manual page in Kernel) automatically uses code from the directory with the highest version number, if more than one version of an application is present.

The application directory structure can also be used in the development environment. The version number can then be omitted from the name.

The application directory has the following sub-directories:

When an Erlang runtime system is started, a number of processes are started as part of the Kernel application. One of these processes is the application controller process, registered as application_controller.

All operations on applications are coordinated by the application controller. It is interacted through the functions in the module application, see the application(3) manual page in Kernel. In particular, applications can be loaded, unloaded, started, and stopped.

Before an application can be started, it must be loaded. The application controller reads and stores the information from the .app file:

1> application:load(ch_app).
ok
2> application:loaded_applications().
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"},
 {ch_app,"Channel allocator","1"}]

An application that has been stopped, or has never been started, can be unloaded. The information about the application is erased from the internal database of the application controller.

3> application:unload(ch_app).
ok
4> application:loaded_applications().
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"}]

An application is started by calling:

5> application:start(ch_app).
ok
6> application:which_applications().
[{kernel,"ERTS  CXC 138 10","2.8.1.3"},
 {stdlib,"ERTS  CXC 138 10","1.11.4.3"},
 {ch_app,"Channel allocator","1"}]

If the application is not already loaded, the application controller first loads it using application:load/1. It checks the value of the applications key, to ensure that all applications that are to be started before this application are running.

The application controller then creates an application master for the application. The application master is the group leader of all the processes in the application. The application master starts the application by calling the application callback function start/2 in the module, and with the start argument, defined by the mod key in the .app file.

An application is stopped, but not unloaded, by calling:

7> application:stop(ch_app).
ok

The application master stops the application by telling the top supervisor to shut down. The top supervisor tells all its child processes to shut down, and so on; the entire tree is terminated in reversed start order. The application master then calls the application callback function stop/1 in the module defined by the mod key.

An application can be configured using configuration parameters. These are a list of {Par,Val} tuples specified by a key env in the .app file:

Par is to be an atom. Val is any term. The application can retrieve the value of a configuration parameter by calling application:get_env(App, Par) or a number of similar functions, see the application(3) manual page in Kernel.

Example:

% erl
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1> application:start(ch_app).
ok
2> application:get_env(ch_app, file).
{ok,"/usr/local/log"}

The values in the .app file can be overridden by values in a system configuration file. This is a file that contains configuration parameters for relevant applications:

The system configuration is to be called Name.config and Erlang is to be started with the command-line argument -config Name. For details, see the config(4) manual page in Kernel.

Example:

A file test.config is created with the following contents:

The value of file overrides the value of file as defined in the .app file:

% erl -config test
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1> application:start(ch_app).
ok
2> application:get_env(ch_app, file).
{ok,"testlog"}

If release handling is used, exactly one system configuration file is to be used and that file is to be called sys.config.

The values in the .app file and the values in a system configuration file can be overridden directly from the command line:

% erl -ApplName Par1 Val1 ... ParN ValN

Example:

% erl -ch_app file '"testlog"'
Erlang (BEAM) emulator version 5.2.3.6 [hipe] [threads:0]

Eshell V5.2.3.6  (abort with ^G)
1> application:start(ch_app).
ok
2> application:get_env(ch_app, file).
{ok,"testlog"}

A start type is defined when starting the application:

application:start(Application) is the same as calling application:start(Application, temporary). The type can also be permanent or transient:

An application can always be stopped explicitly by calling application:stop/1. Regardless of the mode, no other applications are affected.

The transient mode is of little practical use, since when a supervision tree terminates, the reason is set to shutdown, not normal.