[Erlang Systems]

1 System Principles

This chapter describes the strategies and options which are available to start an Erlang system. This section includes the following topics:

This chapter also provides a brief description of the applications which are included in an Erlang system.

1.1 Starting the System

An Erlang system is started with the command:

erl [-boot B] [-config F] [-mode M] [-heart]
    [-loader L] [-id Id] [-nodes N1 N2 ... Nn]
    [-pa Dir1 Dir2 ... Dirn] [-pz  Dir1 Dir2 ... Dirn] 
    [-path Dir1 Dir2 ... Dirn]
    [-AppName Key Value]
    [Other args]

The following comments apply to the arguments listed above:

1.2 Restarting and Stopping the System

The system is restarted and stopped with the following commands:

1.3 Command Line Arguments

When the system has started, application programs can access the values of the command line arguments by calling one of the functions init:get_argument(Key), or init:get_arguments().

Erlang was started by giving a command of the form:

erl -flag1 arg1 arg2 -flag2 arg3 ...

When the erl -flag1 ... command has been issued, Erlang starts by spawning a new process and the system behaves as if the function spawn(init, boot, [Args]) had been evaluated. Args is a list of all the command line arguments to erl. These are passed as strings. For example, the command erl -id 123 -loader efile -script "abc" ... causes the system to behave as if it had evaluated the following function:

spawn(init, boot, ["-id", "123", "-loader", "efile",
                   "-script", "\"abc\""]).

The first thing init does is to call init:parse_args(Args) to "normalize" the input arguments. After normalization, the arguments can be accessed as follows:

Both get_arguments/0 and get_argument/1 preserve the argument order of the arguments supplied with the command line.

Note!

Applications should not normally be configured with command line flags, but should use the application environment instead. Refer to Configuring an Application in the Design Principles chapter for details.

1.4 The Boot File

The boot script is stored in a file with the extension .script

A typical boot script file may look as follows:

{script, {Name, Vsn},
 [
  {progress, loading},
  {preLoaded, [Mod1, Mod2, ...]},
  {path, [Dir1,"$ROOT/Dir",...]}.
  {primLoad, [Mod1, Mod2, ...]},
  ...
  {kernel_load_completed},
  {progress, loaded},
  {kernelProcess, Name, {Mod, Func, Args}},
  ...
  {apply, {Mod, Func, Args}},
  ...
  {progress, started}]}.

The meanings of these terms are as follows:

Note!

In the interactive system the code loader provides demand driven code loading, but in the embedded system the code loader loads all the code immediately. The same version of code is used in both cases. The code server calls init:get_argument(mode) to find out if it should run in demand mode, or non-demand driven mode.

1.5 Making a Boot File

If a boot script is written manually, the systools:script2boot(File) function can be used to generate the compiled (binary) form File.boot from the File.script file. However, it is recommended that the systools:make_script function is used in order to create a boot script.

1.6 Starting the System with a Boot File

The command erl -boot File starts the system with a boot file called File.boot. An ASCII version of the boot file can be found in File.script.

The boot file is created by evaluating:

systools:script2boot(File)

Several standard boot files are available. For example, start.script starts the system as a plain Erlang system with the application_controller and the kernel applications.

1.6.1 start.script

The start.script is as follows:

{script,{"OTP  APN 181 01","R1A"},
        [{preLoaded,[init,erl_prim_loader]},
         {progress,preloaded},
         {path,["$ROOT/lib/kernel-1.1/ebin",
                "$ROOT/lib/stdlib-1.1/ebin"]},
         {primLoad,[error_handler,
                    ets,
                    lib,
                    lists,
                    slave,
                    heart,
                    application_controller,
                    application_master,
                    application,
                    auth,
                    c,
                    calendar,
                    code,
                    erlang,
                    erl_distribution,
                    erl_parse,
                    erl_scan,
                    io_lib,
                    io_lib_format,
                    io_lib_fread,
                    io_lib_pretty,
                    error_logger,
                    file,
                    gen,
                    gen_event,
                    gen_server,
                    global,
                    kernel,
                    net_kernel,
                    proc_lib,
                    rpc,
                    supervisor,
                    sys]},
         {kernel_load_completed},
         {progress,kernel_load_completed},
         {primLoad,[group,
                    user,
                    user_drv,
                    kernel_config,
                    net,
                    erl_boot_server,
                    net_adm]},
         {primLoad,[math,
                    random,
                    ordsets,
                    shell_default,
                    timer,
                    gen_fsm,
                    pg,
                    unix,
                    dict,
                    pool,
                    string,
                    digraph,
                    io,
                    epp,
                    log_mf_h,
                    queue,
                    erl_eval,
                    erl_id_trans,
                    shell,
                    erl_internal,
                    erl_lint,
                    error_logger_file_h,
                    error_logger_tty_h,
                    edlin,
                    erl_pp,
                    dets,
                    regexp,
                    supervisor_bridge]},
         {progress,modules_loaded},
         {kernelProcess,heart,{heart,start,[]}},
         {kernelProcess,error_logger,{error_logger,start_link,[]}},
         {kernelProcess,application_controller,
                        {application_controller,
                            start,
                            [{application,
                                 kernel,
                                 [{description,"ERTS  CXC 138 10"},
                                  {vsn,"1.1"},
                                  {modules,
                                      [{application,1},
                                       {erlang,1},
                                       {group,1},
                                       {rpc,1},
                                       {application_controller,1},
                                       {error_handler,1},
                                       {heart,1},
                                       {application_master,1},
                                       {error_logger,1},
                                       {init,1},
                                       {user,1},
                                       {auth,1},
                                       {kernel,1},
                                       {user_drv,1},
                                       {code,1},
                                       {kernel_config,1},
                                       {net,1},
                                       {erl_boot_server,1},
                                       {erl_prim_loader,1},
                                       {file,1},
                                       {net_adm,1},
                                       {erl_distribution,1},
                                       {global,1},
                                       {net_kernel,1}]},
                                  {registered,
                                      [init,
                                       erl_prim_loader,
                                       heart,
                                       error_logger,
                                       application_controller,
                                       kernel_sup,
                                       kernel_config,
                                       net_sup,
                                       net_kernel,
                                       auth,
                                       code_server,
                                       file_server,
                                       boot_server,
                                       global_name_server,
                                       rex,
                                       user]},
                                  {applications,[]},
                                  {env,
                                      [{error_logger,tty},
                                       {os, {unix, 'solaris'}}]},
                                  {maxT,infinity},
                                  {maxP,infinity},
                                  {mod,{kernel,[]}}]}]}},
         {progress,init_kernel_started},
         {apply,{application,load,
                             [{application,
                                  stdlib,
                                  [{description,"ERTS  CXC 138 10"},
                                   {vsn,"1.1"},
                                   {modules,
                                       [{c,1},
                                        {gen,1},
                                        {io_lib_format,1},
                                        {math,1},
                                        {random,1},
                                        {sys,1},
                                        {calendar,1},
                                        {gen_event,1},
                                        {io_lib_fread,1},
                                        {ordsets,1},
                                        {shell_default,1},
                                        {timer,1},
                                        {gen_fsm,1},
                                        {io_lib_pretty,1},
                                        {pg,1},
                                        {slave,1},
                                        {unix,1},
                                        {dict,1},
                                        {gen_server,1},
                                        {lib,1},
                                        {pool,1},
                                        {string,1},
                                        {digraph,1},
                                        {io,1},
                                        {lists,1},
                                        {proc_lib,1},
                                        {supervisor,1},
                                        {epp,1},
                                        {io_lib,1},
                                        {log_mf_h,1},
                                        {queue,1},
                                        {erl_eval,1},
                                        {erl_id_trans,1},
                                        {shell,1},
                                        {erl_internal,1},
                                        {erl_lint,1},
                                        {error_logger_file_h,1},
                                        {erl_parse,1},
                                        {error_logger_tty_h,1},
                                        {edlin,1},
                                        {erl_pp,1},
                                        {ets,1},
                                        {dets,1},
                                        {regexp,1},
                                        {erl_scan,1},
                                        {supervisor_bridge,1}]},
                                   {registered,
                                       [timer_server,
                                        rsh_starter,
                                        take_over_monitor,
                                        pool_master,
                                        dets]},
                                   {applications,[kernel]},
                                   {env,[]},
                                   {maxT,infinity},
                                   {maxP,infinity}]}]}},
         {progress,applications_loaded},
         {apply,{application,start_boot,[kernel,permanent]}},
         {apply,{application,start_boot,[stdlib,permanent]}},
         {apply,{c,erlangrc,[]}},
         {progress,started}]}.

1.7 Code Loading Strategy

The code is always loaded relative to the current path and this path is obtained from the value given in the script file, possibly modified by the path manipulation flags in the command line.

This approach allows us to run the system in a number of different ways:

1.8 Making an Embedded System

When using the the interactive Erlang development environment, it often does not matter if things go wrong at runtime. The main difference with an embedded system is that it is extremely important that things do not go wrong at runtime.

Before building a release which is targeted for an embedded system, we must perform a large number of compile-time checks on the code.

A boot script file can be created with the systools:make_script function. This function reads a .rel release file and generates the boot script in accordance with the specified applications in the release file. A boot script which is generated this way ensures that all code specified in the application resource files are loaded and that all specified applications are started.

A complete release can be packaged with the systools:make_tar function . All application directories and files are packaged according to the release file. The release file and the release upgrade script are also included in the release package.

1.9 The Primitive Loader

Unlike the Erlang node, the primitive file loader "knows" how to fetch modules and scripts from its environment.

The interface to the primitive loader is as follows:

Note!

We assume the primitive loader to be running as long as the Erlang node is up and running. In the interactive mode, the code server fetches all code through the loader and the application_controller fetches configuration and application files this way.

If an other loader than the one distributed with the system is required, this loader must be implemented by the user as an external port program. The Loader provided by the user must fulfill a protocol defined for the erl_prim_loader, and it will be started by the erl_prim_loader using the open_port({spawn,Loader},[binary]) function call. Refer to the Reference Manual for more information.

1.10 Erlang Applications

The Erlang system is structured as a set of applications, two mandatory (kernel and stdlib), and the others optional. This means that the user can pick the applications which are suitable for a specific project, and disregard the others.

The following applications are included in the Erlang distribution system:

The development tools included with Erlang are listed in Chapter 1 of this User's Guide.

1.10.1 Kernel

The kernel is always the first application to be started. It provides low-level services which are necessary for an Erlang system to start, to participate in a distributed system, to handle errors, and to perform IO operations. Also included in the kernel application are standard error_logger event handlers.

In a minimal Erlang system, kernel and stdlib are the only two applications running.

Refer to the Reference Manual, section kernel, for information about the modules which are included with the kernel application. The Design Principles chapter in this User Guide also has information about these services.

1.10.2 The Standard Library (stdlib)

The standard library contains a large number of re-usable software modules. Many of these modules are specially adapted to programming concurrent, distributed systems and there are modules which solve common programming tasks such as gen_server, gen_event, and gen_fsm.

The Reference Manual describes these modules in detail. The Design Principles chapter of this User's Guide also describe some of these modules in detail.

1.10.3 Sockets

This application contains the following services:

Refer to the Reference Manual, the module sockets for detailed information.

1.10.4 The C/C++ Interface Generator (IG)

The Interface Generator (IG) is a tool which is used to interface interface C with Erlang. With IG, it is possible to transparently access the "other" language directly. C functions look like Erlang functions on the Erlang side, and Erlang functions look like C functions on the C side.

Refer to the chapter C Interface Generator and to the Reference Manual, module ig, for detailed information.

1.10.5 erl_interface Library

The erl_interface library contains functions which are used to interface other software system with the Erlang system. In particular, it contain functions which support the encoding of structures which correspond to an Erlang data structure into a sequence of bytes, and the decoding of a sequence of bytes which correspond to an Erlang structure into a C struct.

Refer to the chapter Interface Libraries, the section The erl Interface Library for detailed information.

1.10.6 The Java Interface (Jive)

Jive makes it possible for a Java Applet/Application to communicate with an Erlang server. Java is ideal for client-side interaction, whereas Erlang is ideal for server-side programming. The idea behind Jive is to integrate these two languages. Jive allows a Java Applet/Application to interact with an Erlang server.

Refer to the chapter Interface Libraries, the section The Java Interface for detailed information.

1.10.7 The Graphics System (gs)

The gs graphics system enables the user to create graphical objects. This system works on all platforms on which Erlang has been implemented.

Refer to the chapter Interface Libraries;The Graphics System, section for detailed information.

1.11 File Types

The following file types are defined in an Erlang system:

Type File name/Extension Description Manual page which describes the file syntax
module .erl Erlang code -
application .app Application resource file app(4)
release .rel Release resource file rel(4)
script .script Start script script(4)
boot .boot Binary boot file -
config .config Configuration file - used to override values in the .app files config(4)
application upgrade .appup Application upgrade appup(4)
release upgrade script relup Release upgrade script relup(4)
File Types

Copyright © 1991-1999 Ericsson Utvecklings AB