-spec check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
                         when
                             Vsn :: string(),
                             OtherVsn :: string(),
                             Descr :: term(),
                             Reason :: term().

Equivalent to check_install_release(Vsn, []).

-spec check_install_release(Vsn, Opts) -> {ok, OtherVsn, Descr} | {error, Reason}
                         when
                             Vsn :: string(),
                             OtherVsn :: string(),
                             Opts :: [Opt],
                             Opt :: purge,
                             Descr :: term(),
                             Reason :: term().

Checks if the specified version Vsn of the release can be installed.

The release must not have status current. Issues warnings if relup file or sys.config is not present. If relup file is present, its contents are checked and {error,Reason} is returned if an error is found. Also checks that all required applications are present and that all new code can be loaded; {error,Reason} is returned if an error is found.

Evaluates all instructions that occur before the point_of_no_return instruction in the release upgrade script.

Returns the same as install_release/1. Descr defaults to "" if no relup file is found.

If option purge is specified, all old code that can be soft-purged is purged after all other checks are successfully completed. This can be useful to reduce the time needed by install_release/1.

-spec create_RELEASES(RelDir, RelFile, AppDirs) -> ok | {error, Reason}
                   when
                       RelDir :: string(),
                       RelFile :: string(),
                       AppDirs :: [{App, Vsn, Dir}],
                       App :: atom(),
                       Vsn :: string(),
                       Dir :: string(),
                       Reason :: term().

Equivalent to create_RELEASES("", RelDir, RelFile, Appdirs).

-spec create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
                   when
                       Root :: string(),
                       RelDir :: string(),
                       RelFile :: string(),
                       AppDirs :: [{App, Vsn, Dir}],
                       App :: atom(),
                       Vsn :: string(),
                       Dir :: string(),
                       Reason :: term().

Creates an initial RELEASES file to be used by the release handler.

This file must exist to install new releases.

Root is the root of the installation ($ROOT) as described earlier. RelDir is the directory where the RELEASES file is to be created (normally $ROOT/releases). RelFile is the name of the .rel file that describes the initial release, including the extension .rel. If Root is not given, the RELEASES file will be location independent (i.e, it will not contain absolute paths unless there are absolute paths in AppDirs). A RELEASES file should be made location independent if the installation's $ROOT is unknown. The release_handler module will interpret relative paths in a running system's RELEASES file as being relative to $ROOT.

AppDirs can be used to specify from where the modules for the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

-spec install_file(Vsn, File) -> ok | {error, Reason}
                when Vsn :: string(), File :: string(), Reason :: term().

Installs a release-dependent file in the release structure.

The release-dependent file must be in the release structure when a new release is installed: start.boot, relup, and sys.config.

The function can be called, for example, when these files are generated at the target. The function is to be called after set_unpacked/2 has been called.

-spec install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
                   when
                       Vsn :: string(),
                       OtherVsn :: string(),
                       Descr :: term(),
                       Reason ::
                           {already_installed, Vsn} |
                           {change_appl_data, term()} |
                           {missing_base_app, OtherVsn, App} |
                           {could_not_create_hybrid_boot, term()} |
                           term(),
                       App :: atom().

Equivalent to install_release(Vsn, []).

-spec install_release(Vsn, [Opt]) ->
                   {ok, OtherVsn, Descr} |
                   {continue_after_restart, OtherVsn, Descr} |
                   {error, Reason}
                   when
                       Vsn :: string(),
                       OtherVsn :: string(),
                       Opt ::
                           {error_action, Action} |
                           {code_change_timeout, Timeout} |
                           {suspend_timeout, Timeout} |
                           {update_paths, Bool},
                       Action :: restart | reboot,
                       Timeout :: default | infinity | pos_integer(),
                       Bool :: boolean(),
                       Descr :: term(),
                       Reason ::
                           {illegal_option, Opt} |
                           {already_installed, Vsn} |
                           {change_appl_data, term()} |
                           {missing_base_app, OtherVsn, App} |
                           {could_not_create_hybrid_boot, term()} |
                           term(),
                       App :: atom().

Installs the specified version Vsn of the release.

Looks first for a relup file for Vsn and a script {UpFromVsn,Descr1,Instructions1} in this file for upgrading from the current version. If not found, the function looks for a relup file for the current version and a script {Vsn,Descr2,Instructions2} in this file for downgrading to Vsn.

If a script is found, the first thing that happens is that the application specifications are updated according to the .app files and sys.config belonging to the release version Vsn.

After the application specifications have been updated, the instructions in the script are evaluated and the function returns {ok,OtherVsn,Descr} if successful. OtherVsn and Descr are the version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as specified in the script.

If {continue_after_restart,OtherVsn,Descr} is returned, the emulator is restarted before the upgrade instructions are executed. This occurs if the emulator or any of the applications Kernel, STDLIB, or SASL are updated. The new emulator version and these core applications execute after the restart. For all other applications the old versions are started and the upgrade is performed as normal by executing the upgrade instructions.

If a recoverable error occurs, the function returns {error,Reason} and the original application specifications are restored. If a non-recoverable error occurs, the system is restarted.

Options:

• error_action - Defines if the node is to be restarted (init:restart()) or rebooted (init:reboot()) if there is an error during the installation. Default is restart.

• code_change_timeout - Defines the time-out for all calls to sys:change_code. If no value is specified or default is specified, the default value defined in sys is used.

• suspend_timeout - Defines the time-out for all calls to sys:suspend. If no value is specified, the values defined by the Timeout parameter of the upgrade or suspend instructions are used. If default is specified, the default value defined in sys is used.

• {update_paths,Bool} - Indicates if all application code paths are to be updated (Bool==true) or if only code paths for modified applications are to be updated (Bool==false, default). This option has only effect for other application directories than the default $ROOT/lib/App-Vsn, that is, application directories specified in argument AppDirs in a call to create_RELEASES/4 or set_unpacked/2.

  Example:

  In the current version CurVsn of a release, the application directory of myapp is $ROOT/lib/myapp-1.0. A new version NewVsn is unpacked outside the release handler and the release handler is informed about this with a call as follows:

  release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
  => {ok,NewVsn}

  If NewVsn is installed with option {update_paths,true}, then code:lib_dir(myapp) returns /home/user/myapp-1.0.

Note

Installing a new release can be time consuming if there are many processes in the system. The reason is that each process must be checked for references to old code before a module can be purged. This check can lead to garbage collections and copying of data.

To speed up the execution of install_release, first call check_install_release, using option purge. This does the same check for old code. Then purges all modules that can be soft-purged. The purged modules do then no longer have any old code, and install_release does not need to do the checks.

This does not reduce the overall time for the upgrade, but it allows checks and purge to be executed in the background before the real upgrade is started.

Note

When upgrading the emulator from a version older than OTP R15, an attempt is made to load new application beam code into the old emulator. Sometimes the new beam format cannot be read by the old emulator, so the code loading fails and the complete upgrade is terminated. To overcome this problem, the new application code is to be compiled with the old emulator. For more information about emulator upgrade from pre OTP R15 versions, see Design Principles in System Documentation.

-spec make_permanent(Vsn) -> ok | {error, Reason}
                  when Vsn :: string(), Reason :: {bad_status, Status :: term()} | term().

Makes the specified release version Vsn permanent.

-spec reboot_old_release(Vsn) -> ok | {error, Reason}
                      when Vsn :: string(), Reason :: {bad_status, Status :: term()} | term().

Reboots the system by making the old release permanent, and calls init:reboot() directly.

The release must have status old.

-spec remove_release(Vsn) -> ok | {error, Reason}
                  when Vsn :: string(), Reason :: {permanent, Vsn} | client_node | term().

Removes a release and its files from the system.

The release must not be the permanent release. Removes only the files and directories not in use by another release.

-spec set_removed(Vsn) -> ok | {error, Reason} when Vsn :: string(), Reason :: {permanent, Vsn} | term().

Makes it possible to handle removal of releases outside the release handler.

Tells the release handler that the release is removed from the system. This function does not delete any files.

-spec set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
                when
                    RelFile :: string(),
                    AppDirs :: [{App, Vsn, Dir}],
                    App :: atom(),
                    Vsn :: string(),
                    Dir :: string(),
                    Reason :: term().

Makes it possible to handle unpacking of releases outside the release handler.

Tells the release handler that the release is unpacked. Vsn is extracted from the release resource file RelFile.

AppDirs can be used to specify from where the modules for the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

-spec unpack_release(Name) -> {ok, Vsn} | {error, Reason}
                  when Name :: string(), Vsn :: string(), Reason :: client_node | term().

Unpacks a release package Name.tar.gz located in the releases directory.

Performs some checks on the package, for example, checks that all mandatory files are present, and extracts its contents.

-spec which_releases() -> [{Name, Vsn, Apps, Status}]
                  when
                      Name :: string(),
                      Vsn :: string(),
                      Apps :: [AppVsn :: string()],
                      Status :: unpacked | current | permanent | old.

Returns all releases known to the release handler.

-spec which_releases(Status) -> [{Name, Vsn, Apps, Status}]
                  when
                      Name :: string(),
                      Vsn :: string(),
                      Apps :: [AppVsn :: string()],
                      Status :: unpacked | current | permanent | old.

Returns all releases, known to the release handler, of a specific status.