From 3d70cee4034e4da37d125679345aa2a10c58cb34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update Kernel documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by technical writers from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/kernel/doc/src/app.xml | 168 ++++++++++++++++++++++++--------------------- 1 file changed, 90 insertions(+), 78 deletions(-) (limited to 'lib/kernel/doc/src/app.xml') diff --git a/lib/kernel/doc/src/app.xml b/lib/kernel/doc/src/app.xml index 35feec144e..3740f1cff9 100644 --- a/lib/kernel/doc/src/app.xml +++ b/lib/kernel/doc/src/app.xml @@ -42,12 +42,12 @@
- FILE SYNTAX -

The application resource file should be called - Application.app where Application is the name of - the application. The file should be located in the ebin - directory for the application.

-

It must contain one single Erlang term, which is called an + File Syntax +

The application resource file is to be called + Application.app, where Application is the + application name. The file 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, @@ -80,19 +80,26 @@ Env [{Par,Val}] [] Start {Module,StartArgs} [] Phases [{Phase,PhaseArgs}] undefined RTDeps [ApplicationVersion] [] - Module = Name = App = Par = Phase = atom() - Val = StartArgs = PhaseArgs = term() - ApplicationVersion = string() -

Application is the name of the application.

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

The functions in systools require more information. If - they are used, the following keys are mandatory: - description, vsn, modules, registered - and applications. The other keys are ignored by - systools.

-

The RTDeps type was introduced in OTP 17.0 and - might be subject to changes during the OTP 17 release.

 + they are used, the following keys are mandatory:

+ + description + vsn + modules + registered + applications + +

The other keys are ignored by systools.

description @@ -104,7 +111,7 @@ RTDeps [ApplicationVersion] [] vsn -

The version of the application.

+

Version of the application.

 modules @@ -114,15 +121,14 @@ RTDeps [ApplicationVersion] [] maxP -

Deprecated - will be ignored

- - The maximum number of processes allowed in the application.

+

Deprecated - is ignored

+

Maximum number of processes allowed in the application.

 maxT -

The maximum time in milliseconds that the application is - allowed to run. After the specified time the application will - automatically terminate.

+

Maximum time, in milliseconds, that the application is + allowed to run. After the specified time, the application + terminates automatically.

 registered @@ -132,20 +138,20 @@ RTDeps [ApplicationVersion] [] included_applications -

All applications which are included by this application. - When this application is started, all included application - will automatically be loaded, but not started, by - the application controller. It is assumed that the topmost +

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.

 applications -

All applications which must be started before this +

All applications that must be started before this application is allowed to be started. systools uses this list to generate correct start scripts. Defaults to - the empty list, but note that all applications have - dependencies to (at least) kernel and stdlib.

+ the empty list, but notice that all applications have + dependencies to (at least) Kernel and STDLIB.

 env @@ -153,78 +159,84 @@ RTDeps [ApplicationVersion] [] 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 - erl(1)).

+ file (see config(4)) + or by command-line flags (see + erts:erl(1)).

 mod -

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

-

The mod key is necessary for an application - implemented as a supervision tree, or the application - controller will not know how to start it. The mod key +

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

+

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 such as the application STDLIB.

+ code libraries, for example, STDLIB.

 start_phases

A list of start phases and corresponding start arguments for the application. If this key is present, the application - master will - in addition to the usual call to - Module:start/2 - also call + 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 the start_phases key, and only - after this extended start procedure will - application:start(Application) return.

-

Start phases may be used to synchronize startup of an + start phase defined by key start_phases. Only + after this extended start procedure, + application:start(Application) returns.

+

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

+ key mod must be specified as follows:

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

The application master will then call Module:start/2 +

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 application, for which the start + 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. Refer to OTP Design Principles for more information.

+ for the primary application. 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 on - how to compare application versions see - the - documentation of versions in the system principles - guide. Note that the application version - specifies a source code version. An additional indirect - requirement is that installed binary application of - the specified version has been built so that it is - compatible with the rest of the system.

-

Some dependencies might only be required in specific runtime - scenarios. In the case such optional dependencies exist, these are - specified and documented in the corresponding "App" documentation - of the specific application.

-

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.

 -

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.

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

+

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.

 +

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 -

application(3), - systools(3)

+ See Also +

application(3), + sasl:systools(3)

-- cgit v1.2.3