System Principles — Erlang System Documentation v28.4.1

Search documentation of Erlang System Documentation

# System Principles

View Source

## Starting the System

An Erlang runtime system is started with command `erl`:

    % erl
    Erlang/OTP 27 [erts-15.0] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit]

    Eshell V15.0 (press Ctrl+G to abort, type help(). for help)
    1>

`erl` understands a number of command-line arguments; see erl in the ERTS application. Some arguments are also described in this chapter.

Application programs can access the values of the command-line arguments by calling one of the following functions:

- `init:get_argument(Key)`
- `init:get_arguments()`
- `init:get_plain_arguments()`

## Restarting and Stopping the System

The runtime system is halted by calling `halt/0,1,2`.

Module `init` contains functions for restarting, rebooting, and stopping the runtime system:

- `init:restart()`
- `init:reboot()`
- `init:stop()`

The runtime system terminates if the Erlang shell is terminated.

## Boot Scripts

The runtime system is started using a boot script. The boot script contains instructions on which code to load and which processes and applications to start.

A boot script file has the extension `.script`. The runtime system uses a binary version of the script. This binary boot script file has the extension `.boot`.

Which boot script to use is specified by the command-line flag `-boot`. The extension `.boot` is to be omitted. For example, using the boot script `start_all.boot`:

    % erl -boot start_all

If no boot script is specified, it defaults to `ROOT/bin/start`, where `ROOT` is the installation directory of Erlang/OTP. See Default Boot Scripts.

When the command-line flag `-init_debug` is used, the `init` process will output debug information while interpreting the boot script.

    % erl -init_debug
    {progress,preloaded}
    {progress,kernel_load_completed}
    {progress,modules_loaded}
    {start,heart}
    {start,logger}
      .
      .
      .

For a detailed description of the syntax and contents of the boot script, see `script` in the SASL application.

### Default Boot Scripts

Erlang/OTP comes with these boot scripts:

- `start_clean.boot` - Loads the code for and starts the applications Kernel and STDLIB.
- `start_sasl.boot` - Loads the code for and starts the applications Kernel, STDLIB, and SASL.
- `no_dot_erlang.boot` - Loads the code for and starts the applications Kernel and STDLIB. Skips loading the file `.erlang`. Useful for scripts and other tools that are to behave the same irrespective of user preferences.

Which of `start_clean` and `start_sasl` to use as default is decided by the user when installing Erlang/OTP using `Install`. The user is asked:

    Do you want to use a minimal system startup instead of the SASL startup?

If the answer is yes, `start_clean` is used, otherwise `start_sasl` is used. The chosen boot script is copied and renamed as `start.boot`, then placed into directory `ROOT/bin`.

### User-Defined Boot Scripts

It is sometimes useful or necessary to create a user-defined boot script. This is true especially when running Erlang in embedded mode; see Code Loading Strategy.

While it is possible to manually create a boot script, it is preferable to generate it from a release resource file called `Name.rel` using the function `systools:make_script/1,2`. This requires that the source code is structured as applications according to the OTP design principles.

For more information about `.rel` files, see Release Handling and the rel page in SASL.

To generate the binary boot script file `Name.boot` the boot script file `Name.script`, use the `systools:script2boot(File)` function.

## Code Loading Strategy

The runtime system can be started in either embedded or interactive mode. Which one is decided by the command-line flag `-mode`:

    % erl -mode embedded

The default mode is `interactive`. If more than one `-mode` flag is given, the first one will be used.

The mode properties are as follows:

- In embedded mode, all code is loaded during system startup according to the boot script. (Code can be loaded later by explicitly ordering the code server to load it.)

- In interactive mode, code is dynamically loaded when first required, which means that when an attempt is made to call a function in a module that is not loaded, the code server searches the code path and loads the module into the system.

Initially, the code path consists of the current working directory and all object code directories under `ROOT/lib`, where `ROOT` is the installation directory of Erlang/OTP. Directories can be named `Name[-Vsn]`, where the `-Vsn` suffix is optional. By default, the code server chooses the directory with the highest version number among those which have the same `Name`. If an `ebin` directory exists under the `Name[-Vsn]` directory, this directory is added to the code path.

The code path can be extended by using the command-line flags `-pa Directories` and `-pz Directories`. These add `Directories` to the head or the end of the code path, respectively. Example:

    % erl -pa /home/arne/mycode

The `code` module contains a number of functions for modifying and querying the search path.

## File Types

The following file types are defined in Erlang/OTP:

File Type | File Name/Extension | Documented in
--- | --- | ---
Module | `.erl` | Erlang Reference Manual
Include file | `.hrl` | Erlang Reference Manual
Release resource file | `.rel` | rel in SASL
Application resource file | `.app` | app in Kernel
Boot script | `.script` | script in SASL
Binary boot script | `.boot` | -
Configuration file | `.config` | config in Kernel
Application upgrade file | `.appup` | appup in SASL
Release upgrade file | `relup` | relup in SASL

Table: File Types

← Previous Page Debugging
Next Page → Error Logging