.TH release_handler 3erl "sasl 3.0.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
release_handler \- Unpacking and Installation of Release Packages
.SH DESCRIPTION
.LP
The \fIrelease handler\fR\& process belongs to the SASL application, which is responsible for \fIrelease handling\fR\&, that is, unpacking, installation, and removal of release packages\&.
.LP
An introduction to release handling and an example is provided in \fBOTP Design Principles\fR\& in \fISystem Documentation\fR\&\&.
.LP
A \fIrelease package\fR\& is a compressed tar file containing code for a certain version of a release, created by calling \fB\fIsystools:make_tar/1,2\fR\&\fR\&\&. The release package is to be located in the \fI$ROOT/releases\fR\& directory of the previous version of the release, where \fI$ROOT\fR\& is the installation root directory, \fB\fIcode:root_dir()\fR\&\fR\&\&. Another \fIreleases\fR\& directory can be specified using the SASL configuration parameter \fIreleases_dir\fR\& or the OS environment variable \fIRELDIR\fR\&\&. The release handler must have write access to this directory to install the new release\&. The persistent state of the release handler is stored there in a file called \fIRELEASES\fR\&\&.
.LP
A release package is always to contain:
.RS 2
.TP 2
*
A release resource file, \fIName\&.rel\fR\&
.LP
.TP 2
*
A boot script, \fIName\&.boot\fR\&
.LP
.RE

.LP
The \fI\&.rel\fR\& file contains information about the release: its name, version, and which ERTS and application versions it uses\&.
.LP
A release package can also contain:
.RS 2
.TP 2
*
A release upgrade file, \fIrelup\fR\&
.LP
.TP 2
*
A system configuration file, \fIsys\&.config\fR\&
.LP
.RE

.LP
The \fIrelup\fR\& file contains instructions for how to upgrade to, or downgrade from, this version of the release\&.
.LP
The release package can be \fIunpacked\fR\&, which extracts the files\&. An unpacked release can be \fIinstalled\fR\&\&. The currently used version of the release is then upgraded or downgraded to the specified version by evaluating the instructions in the \fIrelup\fR\& file\&. An installed release can be made \fIpermanent\fR\&\&. Only one permanent release can exist in the system, and this release is used if the system is restarted\&. An installed release, except the permanent one, can be \fIremoved\fR\&\&. When a release is removed, all files belonging to that release only are deleted\&.
.LP
Each release version has a status, which can be \fIunpacked\fR\&, \fIcurrent\fR\&, \fIpermanent\fR\&, or \fIold\fR\&\&. There is always one latest release, which either has status \fIpermanent\fR\& (normal case) or \fIcurrent\fR\& (installed, but not yet made permanent)\&. The meaning of the status values are illustrated in the following table:
.LP
.nf

        Status     Action                NextStatus
        -------------------------------------------
        -          unpack                unpacked
        unpacked   install               current
                   remove                -
        current    make_permanent        permanent
                   install other         old
                   remove                -
        permanent  make other permanent  old
                   install               permanent
        old        reboot_old            permanent
                   install               current
                   remove                -
.fi
.LP
The release handler process is a locally registered process on each node\&. When a release is installed in a distributed system, the release handler on each node must be called\&. The release installation can be synchronized between nodes\&. From an operator view, it can be unsatisfactory to specify each node\&. The aim is to install one release package in the system, no matter how many nodes there are\&. It is recommended that software management functions are written that take care of this problem\&. Such a function can have knowledge of the system architecture, so it can contact each individual release handler to install the package\&.
.LP
For release handling to work properly, the runtime system must know which release it is running\&. It must also be able to change (in runtime) which boot script and system configuration file are to be used if the system is restarted\&. This is taken care of automatically if Erlang is started as an embedded system\&. Read about this in \fBEmbedded System\fR\& in \fISystem Documentation\fR\&\&. In this case, the system configuration file \fIsys\&.config\fR\& is mandatory\&.
.LP
The installation of a new release can restart the system\&. Which program to use is specified by the SASL configuration parameter \fIstart_prg\fR\&, which defaults to \fI$ROOT/bin/start\fR\&\&.
.LP
The emulator restart on Windows NT expects that the system is started using the \fIerlsrv\fR\& program (as a service)\&. Furthermore, the release handler expects that the service is named \fINodeName\fR\&_\fIRelease\fR\&, where \fINodeName\fR\& is the first part of the Erlang node name (up to, but not including the "@") and \fIRelease\fR\& is the current release version\&. The release handler furthermore expects that a program like \fIstart_erl\&.exe\fR\& is specified as "machine" to \fIerlsrv\fR\&\&. During upgrading with restart, a new service is registered and started\&. The new service is set to automatic and the old service is removed when the new release is made permanent\&.
.LP
The release handler at a node running on a diskless machine, or with a read-only file system, must be configured accordingly using the following SASL configuration parameters (for details, see \fBsasl(7)\fR\&):
.RS 2
.TP 2
.B
\fImasters\fR\&:
This node uses some master nodes to store and fetch release information\&. All master nodes must be operational whenever release information is written by this node\&.
.TP 2
.B
\fIclient_directory\fR\&:
The \fIclient_directory\fR\& in the directory structure of the master nodes must be specified\&.
.TP 2
.B
\fIstatic_emulator\fR\&:
This parameter specifies if the Erlang emulator is statically installed at the client node\&. A node with a static emulator cannot dynamically switch to a new emulator, as the executable files are statically written into memory\&.
.RE
.LP
The release handler can also be used to unpack and install release packages when not running Erlang as an embedded system\&. However, in this case the user must somehow ensure that correct boot scripts and configuration files are used if the system must be restarted\&.
.LP
Functions are provided for using another file structure than the structure defined in OTP\&. These functions can be used to test a release upgrade locally\&.
.SH EXPORTS
.LP
.B
check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
.br
.B
check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = OtherVsn = string()
.br
Opts = [Opt]
.br
Opt = purge
.br
Descr = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Checks if the specified version \fIVsn\fR\& of the release can be installed\&. The release must not have status \fIcurrent\fR\&\&. Issues warnings if \fIrelup\fR\& file or \fIsys\&.config\fR\& is not present\&. If \fIrelup\fR\& file is present, its contents are checked and \fI{error,Reason}\fR\& is returned if an error is found\&. Also checks that all required applications are present and that all new code can be loaded; \fI{error,Reason}\fR\& is returned if an error is found\&.
.LP
Evaluates all instructions that occur before the \fIpoint_of_no_return\fR\& instruction in the release upgrade script\&.
.LP
Returns the same as \fB\fIinstall_release/1\fR\&\fR\&\&. \fIDescr\fR\& defaults to "" if no \fIrelup\fR\& file is found\&.
.LP
If option \fIpurge\fR\& 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 \fB\fIinstall_release/1\fR\&\fR\&\&.
.RE

.LP
.B
create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Root = RelDir = RelFile = string()
.br
AppDirs = [{App, Vsn, Dir}]
.br
 App = atom()
.br
 Vsn = Dir = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Creates an initial \fIRELEASES\fR\& file to be used by the release handler\&. This file must exist to install new releases\&.
.LP
\fIRoot\fR\& is the root of the installation (\fI$ROOT\fR\&) as described earlier\&. \fIRelDir\fR\& is the directory where the \fIRELEASES\fR\& file is to be created (normally \fI$ROOT/releases\fR\&)\&. \fIRelFile\fR\& is the name of the \fI\&.rel\fR\& file that describes the initial release, including the extension \fI\&.rel\fR\&\&.
.LP
\fIAppDirs\fR\& can be used to specify from where the modules for the specified applications are to be loaded\&. \fIApp\fR\& is the name of an application, \fIVsn\fR\& is the version, and \fIDir\fR\& is the name of the directory where \fIApp-Vsn\fR\& is located\&. The corresponding modules are to be located under \fIDir/App-Vsn/ebin\fR\&\&. The directories for applications not specified in \fIAppDirs\fR\& are assumed to be located in \fI$ROOT/lib\fR\&\&.
.RE

.LP
.B
install_file(Vsn, File) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = File = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
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: \fIstart\&.boot\fR\&, \fIrelup\fR\&, and \fIsys\&.config\fR\&\&.
.LP
The function can be called, for example, when these files are generated at the target\&. The function is to be called after \fB\fIset_unpacked/2\fR\&\fR\& has been called\&.
.RE

.LP
.B
install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}
.br
.B
install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = OtherVsn = string()
.br
Opt = {error_action, Action} | {code_change_timeout, Timeout}
.br
 | {suspend_timeout, Timeout} | {update_paths, Bool}
.br
 Action = restart | reboot
.br
 Timeout = default | infinity | pos_integer()
.br
 Bool = boolean()
.br
Descr = term()
.br
Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()
.br
App = atom()
.br
.RE
.RE
.RS
.LP
Installs the specified version \fIVsn\fR\& of the release\&. Looks first for a \fIrelup\fR\& file for \fIVsn\fR\& and a script \fI{UpFromVsn,Descr1,Instructions1}\fR\& in this file for upgrading from the current version\&. If not found, the function looks for a \fIrelup\fR\& file for the current version and a script \fI{Vsn,Descr2,Instructions2}\fR\& in this file for downgrading to \fIVsn\fR\&\&.
.LP
If a script is found, the first thing that happens is that the application specifications are updated according to the \fI\&.app\fR\& files and \fIsys\&.config\fR\& belonging to the release version \fIVsn\fR\&\&.
.LP
After the application specifications have been updated, the instructions in the script are evaluated and the function returns \fI{ok,OtherVsn,Descr}\fR\& if successful\&. \fIOtherVsn\fR\& and \fIDescr\fR\& are the version (\fIUpFromVsn\fR\& or \fIVsn\fR\&) and description (\fIDescr1\fR\& or \fIDescr2\fR\&) as specified in the script\&.
.LP
If \fI{continue_after_restart,OtherVsn,Descr}\fR\& 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\&.
.LP
If a recoverable error occurs, the function returns \fI{error,Reason}\fR\& and the original application specifications are restored\&. If a non-recoverable error occurs, the system is restarted\&.
.LP
\fIOptions\fR\&:
.RS 2
.TP 2
.B
\fIerror_action\fR\&:
Defines if the node is to be restarted (\fB\fIinit:restart()\fR\&\fR\&) or rebooted (\fB\fIinit:reboot()\fR\&\fR\&) if there is an error during the installation\&. Default is \fIrestart\fR\&\&.
.TP 2
.B
\fIcode_change_timeout\fR\&:
Defines the time-out for all calls to \fB\fIsys:change_code\fR\&\fR\&\&. If no value is specified or \fIdefault\fR\& is specified, the default value defined in \fIsys\fR\& is used\&.
.TP 2
.B
\fIsuspend_timeout\fR\&:
Defines the time-out for all calls to \fB\fIsys:suspend\fR\&\fR\&\&. If no value is specified, the values defined by the \fITimeout\fR\& parameter of the \fIupgrade\fR\& or \fIsuspend\fR\& instructions are used\&. If \fIdefault\fR\& is specified, the default value defined in \fIsys\fR\& is used\&.
.TP 2
.B
\fI{update_paths,Bool}\fR\&:
Indicates if all application code paths are to be updated (\fIBool==true\fR\&) or if only code paths for modified applications are to be updated (\fIBool==false\fR\&, default)\&. This option has only effect for other application directories than the default \fI$ROOT/lib/App-Vsn\fR\&, that is, application directories specified in argument \fIAppDirs\fR\& in a call to \fB\fIcreate_RELEASES/4\fR\&\fR\& or \fB\fIset_unpacked/2\fR\&\fR\&\&.
.RS 2
.LP
\fIExample:\fR\&
.RE

.RS 2
.LP
In the current version \fICurVsn\fR\& of a release, the application directory of \fImyapp\fR\& is \fI$ROOT/lib/myapp-1\&.0\fR\&\&. A new version \fINewVsn\fR\& is unpacked outside the release handler and the release handler is informed about this with a call as follows:
.RE

.LP
.nf

release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}
.fi
.RS 2
.LP
If \fINewVsn\fR\& is installed with option \fI{update_paths,true}\fR\&, then \fB\fIcode:lib_dir(myapp)\fR\&\fR\& returns \fI/home/user/myapp-1\&.0\fR\&\&.
.RE

.RE
.LP

.RS -4
.B
Note:
.RE
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\&.
.LP
To speed up the execution of \fB\fIinstall_release\fR\&\fR\&, first call \fB\fIcheck_install_release\fR\&\fR\&, using option \fIpurge\fR\&\&. 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 \fB\fIinstall_release\fR\&\fR\& does not need to do the checks\&.
.LP
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\&.

.LP

.RS -4
.B
Note:
.RE
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 \fBDesign Principles\fR\& in \fISystem Documentation\fR\&\&.

.RE

.LP
.B
make_permanent(Vsn) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = string()
.br
Reason = {bad_status, Status} | term()
.br
.RE
.RE
.RS
.LP
Makes the specified release version \fIVsn\fR\& permanent\&.
.RE

.LP
.B
remove_release(Vsn) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = string()
.br
Reason = {permanent, Vsn} | client_node | term()
.br
.RE
.RE
.RS
.LP
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\&.
.RE

.LP
.B
reboot_old_release(Vsn) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = string()
.br
Reason = {bad_status, Status} | term()
.br
.RE
.RE
.RS
.LP
Reboots the system by making the old release permanent, and calls \fB\fIinit:reboot()\fR\&\fR\& directly\&. The release must have status \fIold\fR\&\&.
.RE

.LP
.B
set_removed(Vsn) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Vsn = string()
.br
Reason = {permanent, Vsn} | term()
.br
.RE
.RE
.RS
.LP
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\&.
.RE

.LP
.B
set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
RelFile = string()
.br
AppDirs = [{App, Vsn, Dir}]
.br
 App = atom()
.br
 Vsn = Dir = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Makes it possible to handle unpacking of releases outside the release handler\&. Tells the release handler that the release is unpacked\&. \fIVsn\fR\& is extracted from the release resource file \fIRelFile\fR\&\&.
.LP
\fIAppDirs\fR\& can be used to specify from where the modules for the specified applications are to be loaded\&. \fIApp\fR\& is the name of an application, \fIVsn\fR\& is the version, and \fIDir\fR\& is the name of the directory where \fIApp-Vsn\fR\& is located\&. The corresponding modules are to be located under \fIDir/App-Vsn/ebin\fR\&\&. The directories for applications not specified in \fIAppDirs\fR\& are assumed to be located in \fI$ROOT/lib\fR\&\&.
.RE

.LP
.B
unpack_release(Name) -> {ok, Vsn} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Name = Vsn = string()
.br
Reason = client_node | term()
.br
.RE
.RE
.RS
.LP
Unpacks a release package \fIName\&.tar\&.gz\fR\& located in the \fIreleases\fR\& directory\&.
.LP
Performs some checks on the package, for example, checks that all mandatory files are present, and extracts its contents\&.
.RE

.LP
.B
which_releases() -> [{Name, Vsn, Apps, Status}]
.br
.RS
.LP
Types:

.RS 3
Name = Vsn = string()
.br
Apps = ["App-Vsn"]
.br
Status = unpacked | current | permanent | old
.br
.RE
.RE
.RS
.LP
Returns all releases known to the release handler\&.
.RE

.LP
.B
which_releases(Status) -> [{Name, Vsn, Apps, Status}]
.br
.RS
.LP
Types:

.RS 3
Name = Vsn = string()
.br
Apps = ["App-Vsn"]
.br
Status = unpacked | current | permanent | old
.br
.RE
.RE
.RS
.LP
Returns all releases, known to the release handler, of a specific status\&.
.RE

.SH "APPLICATION UPGRADE/DOWNGRADE"

.LP
The following functions can be used to test upgrade and downgrade of single applications (instead of upgrading/downgrading an entire release)\&. A script corresponding to the instructions in the \fIrelup\fR\& file is created on-the-fly, based on the \fI\&.appup\fR\& file for the application, and evaluated exactly in the same way as \fIrelease_handler\fR\& does\&.
.LP

.RS -4
.B
Warning:
.RE
These functions are primarily intended for simplified testing of \fI\&.appup\fR\& files\&. They are not run within the context of the \fIrelease_handler\fR\& process\&. They must therefore \fInot\fR\& be used together with calls to \fB\fIinstall_release/1,2\fR\&\fR\&, as this causes the \fIrelease_handler\fR\& to end up in an inconsistent state\&.
.LP
No persistent information is updated, so these functions can be used on any Erlang node, embedded or not\&. Also, using these functions does not affect which code is loaded if there is a reboot\&.
.LP
If the upgrade or downgrade fails, the application can end up in an inconsistent state\&.

.SH EXPORTS
.LP
.B
upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
App = atom()
.br
Dir = string()
.br
Unpurged = [Module]
.br
 Module = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Upgrades an application \fIApp\fR\& from the current version to a new version located in \fIDir\fR\& according to the \fI\&.appup\fR\& file\&.
.LP
\fIApp\fR\& is the name of the application, which must be started\&. \fIDir\fR\& is the new library directory of \fIApp\fR\&\&. The corresponding modules as well as the \fI\&.app\fR\& and \fI\&.appup\fR\& files are to be located under \fIDir/ebin\fR\&\&.
.LP
The function looks in the \fI\&.appup\fR\& file and tries to find an upgrade script from the current version of the application using \fB\fIupgrade_script/2\fR\&\fR\&\&. This script is evaluated using \fB\fIeval_appup_script/4\fR\&\fR\&, exactly in the same way as \fB\fIinstall_release/1,2\fR\&\fR\& does\&.
.LP
Returns one of the following:
.RS 2
.TP 2
*
\fI{ok, Unpurged}\fR\& if evaluating the script is successful, where \fIUnpurged\fR\& is a list of unpurged modules
.LP
.TP 2
*
\fIrestart_emulator\fR\& if this instruction is encountered in the script
.LP
.TP 2
*
\fI{error, Reason}\fR\& if an error occurred when finding or evaluating the script
.LP
.RE

.LP
If the \fIrestart_new_emulator\fR\& instruction is found in the script, \fB\fIupgrade_app/2\fR\&\fR\& returns \fI{error,restart_new_emulator}\fR\&\&. This because \fIrestart_new_emulator\fR\& requires a new version of the emulator to be started before the rest of the upgrade instructions can be executed, and this can only be done by \fB\fIinstall_release/1,2\fR\&\fR\&\&.
.RE

.LP
.B
downgrade_app(App, Dir) ->
.br
.B
downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
App = atom()
.br
Dir = OldVsn = string()
.br
Unpurged = [Module]
.br
 Module = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Downgrades an application \fIApp\fR\& from the current version to a previous version \fIOldVsn\fR\& located in \fIDir\fR\& according to the \fI\&.appup\fR\& file\&.
.LP
\fIApp\fR\& is the name of the application, which must be started\&. \fIOldVsn\fR\& is the previous application version and can be omitted if \fIDir\fR\& is of the format \fI"App-OldVsn"\fR\&\&. \fIDir\fR\& is the library directory of the previous version of \fIApp\fR\&\&. The corresponding modules and the old \fI\&.app\fR\& file are to be located under \fIDir/ebin\fR\&\&. The \fI\&.appup\fR\& file is to be located in the \fIebin\fR\& directory of the \fIcurrent\fR\& library directory of the application (\fB\fIcode:lib_dir(App)\fR\&\fR\&)\&.
.LP
The function looks in the \fI\&.appup\fR\& file and tries to find a downgrade script to the previous version of the application using \fB\fIdowngrade_script/3\fR\&\fR\&\&. This script is evaluated using \fB\fIeval_appup_script/4\fR\&\fR\&, exactly in the same way as \fB\fIinstall_release/1,2\fR\&\fR\& does\&.
.LP
Returns one of the following:
.RS 2
.TP 2
*
\fI{ok, Unpurged}\fR\& if evaluating the script is successful, where \fIUnpurged\fR\& is a list of unpurged modules
.LP
.TP 2
*
\fIrestart_emulator\fR\& if this instruction is encountered in the script
.LP
.TP 2
*
\fI{error, Reason}\fR\& if an error occurred when finding or evaluating the script
.LP
.RE

.RE

.LP
.B
upgrade_script(App, Dir) -> {ok, NewVsn, Script}
.br
.RS
.LP
Types:

.RS 3
App = atom()
.br
Dir = string()
.br
NewVsn = string()
.br
Script = Instructions
.br
.RE
.RE
.RS
.LP
Tries to find an application upgrade script for \fIApp\fR\& from the current version to a new version located in \fIDir\fR\&\&.
.LP
The upgrade script can then be evaluated using \fB\fIeval_appup_script/4\fR\&\fR\&\&. It is recommended to use \fB\fIupgrade_app/2\fR\&\fR\& instead, but this function (\fIupgrade_script\fR\&) is useful to inspect the contents of the script\&.
.LP
\fIApp\fR\& is the name of the application, which must be started\&. \fIDir\fR\& is the new library directory of \fIApp\fR\&\&. The corresponding modules as well as the \fI\&.app\fR\& and \fI\&.appup\fR\& files are to be located under \fIDir/ebin\fR\&\&.
.LP
The function looks in the \fI\&.appup\fR\& file and tries to find an upgrade script from the current application version\&. High-level instructions are translated to low-level instructions\&. The instructions are sorted in the same manner as when generating a \fIrelup\fR\& file\&.
.LP
Returns \fI{ok, NewVsn, Script}\fR\& if successful, where \fINewVsn\fR\& is the new application version\&. For details about \fIScript\fR\&, see \fB\fIappup(5)\fR\&\fR\&\&.
.LP
Failure: If a script cannot be found, the function fails with an appropriate error reason\&.
.RE

.LP
.B
downgrade_script(App, OldVsn, Dir) -> {ok, Script}
.br
.RS
.LP
Types:

.RS 3
App = atom()
.br
OldVsn = Dir = string()
.br
Script = Instructions
.br
.RE
.RE
.RS
.LP
Tries to find an application downgrade script for \fIApp\fR\& from the current version to a previous version \fIOldVsn\fR\& located in \fIDir\fR\&\&.
.LP
The downgrade script can then be evaluated using \fB\fIeval_appup_script/4\fR\&\fR\&\&. It is recommended to use \fB\fIdowngrade_app/2,3\fR\&\fR\& instead, but this function (\fIdowngrade_script\fR\&) is useful to inspect the contents of the script\&.
.LP
\fIApp\fR\& is the name of the application, which must be started\&. \fIDir\fR\& is the previous library directory of \fIApp\fR\&\&. The corresponding modules and the old \fI\&.app\fR\& file are to be located under \fIDir/ebin\fR\&\&. The \fI\&.appup\fR\& file is to be located in the \fIebin\fR\& directory of the \fIcurrent\fR\& library directory of the application (\fB\fIcode:lib_dir(App)\fR\&)\fR\&\&.
.LP
The function looks in the \fI\&.appup\fR\& file and tries to find a downgrade script from the current application version\&. High-level instructions are translated to low-level instructions\&. The instructions are sorted in the same manner as when generating a \fIrelup\fR\& file\&.
.LP
Returns \fI{ok, Script}\fR\& if successful\&. For details about \fIScript\fR\&, see \fB\fIappup(5)\fR\&\fR\&\&.
.LP
Failure: If a script cannot be found, the function fails with an appropriate error reason\&.
.RE

.LP
.B
eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
App = atom()
.br
ToVsn = ToDir = string()
.br
Script
.br
.RS 2
See \fB\fIupgrade_script/2\fR\&\fR\&, \fB\fIdowngrade_script/3\fR\&\fR\&
.RE
Unpurged = [Module]
.br
 Module = atom()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Evaluates an application upgrade or downgrade script \fIScript\fR\&, the result from calling \fB\fIupgrade_script/2\fR\&\fR\& or \fB\fIdowngrade_script/3\fR\&\fR\&, exactly in the same way as \fB\fIinstall_release/1,2\fR\&\fR\& does\&.
.LP
\fIApp\fR\& is the name of the application, which must be started\&. \fIToVsn\fR\& is the version to be upgraded/downgraded to, and \fIToDir\fR\& is the library directory of this version\&. The corresponding modules as well as the \fI\&.app\fR\& and \fI\&.appup\fR\& files are to be located under \fIDir/ebin\fR\&\&.
.LP
Returns one of the following:
.RS 2
.TP 2
*
\fI{ok, Unpurged}\fR\& if evaluating the script is successful, where \fIUnpurged\fR\& is a list of unpurged modules
.LP
.TP 2
*
\fIrestart_emulator\fR\& if this instruction is encountered in the script
.LP
.TP 2
*
\fI{error, Reason}\fR\& if an error occurred when finding or evaluating the script
.LP
.RE

.LP
If the \fIrestart_new_emulator\fR\& instruction is found in the script, \fB\fIeval_appup_script/4\fR\&\fR\& returns \fI{error,restart_new_emulator}\fR\&\&. This because \fIrestart_new_emulator\fR\& requires a new version of the emulator to be started before the rest of the upgrade instructions can be executed, and this can only be done by \fB\fIinstall_release/1,2\fR\&\fR\&\&.
.RE

.SH "TYPICAL ERROR REASONS"

.RS 2
.TP 2
.B
\fI{bad_masters, Masters}\fR\&:
The master nodes \fIMasters\fR\& are not alive\&.
.TP 2
.B
\fI{bad_rel_file, File}\fR\&:
Specified \fI\&.rel\fR\& file \fIFile\fR\& cannot be read or does not contain a single term\&.
.TP 2
.B
\fI{bad_rel_data, Data}\fR\&:
Specified \fI\&.rel\fR\& file does not contain a recognized release specification, but another term \fIData\fR\&\&.
.TP 2
.B
\fI{bad_relup_file, File}\fR\&:
Specified \fIrelup\fR\& file \fIRelup\fR\& contains bad data\&.
.TP 2
.B
\fI{cannot_extract_file, Name, Reason}\fR\&:
Problems when extracting from a tar file, \fB\fIerl_tar:extract/2\fR\&\fR\& returned \fI{error, {Name, Reason}}\fR\&\&.
.TP 2
.B
\fI{existing_release, Vsn}\fR\&:
Specified release version \fIVsn\fR\& is already in use\&.
.TP 2
.B
\fI{Master, Reason, When}\fR\&:
Some operation, indicated by the term \fIWhen\fR\&, failed on the master node \fIMaster\fR\& with the specified error reason \fIReason\fR\&\&.
.TP 2
.B
\fI{no_matching_relup, Vsn, CurrentVsn}\fR\&:
Cannot find a script for upgrading/downgrading between \fICurrentVsn\fR\& and \fIVsn\fR\&\&.
.TP 2
.B
\fI{no_such_directory, Path}\fR\&:
The directory \fIPath\fR\&does not exist\&.
.TP 2
.B
\fI{no_such_file, Path}\fR\&:
The path \fIPath\fR\& (file or directory) does not exist\&.
.TP 2
.B
\fI{no_such_file, {Master, Path}}\fR\&:
The path \fIPath\fR\& (file or directory) does not exist at the master node \fIMaster\fR\&\&.
.TP 2
.B
\fI{no_such_release, Vsn}\fR\&:
The specified release version \fIVsn\fR\& does not exist\&.
.TP 2
.B
\fI{not_a_directory, Path}\fR\&:
\fIPath\fR\& exists but is not a directory\&.
.TP 2
.B
\fI{Posix, File}\fR\&:
Some file operation failed for \fIFile\fR\&\&. \fIPosix\fR\& is an atom named from the Posix error codes, such as \fIenoent\fR\&, \fIeacces\fR\&, or \fIeisdir\fR\&\&. See \fB\fIfile(3erl)\fR\&\fR\& in Kernel\&.
.TP 2
.B
\fIPosix\fR\&:
Some file operation failed, as for the previous item in the list\&.
.RE
.SH "SEE ALSO"

.LP
\fBOTP Design Principles\fR\&, \fB\fIconfig(5)\fR\&\fR\&, \fB\fIrel(5)\fR\&\fR\&, \fB\fIrelup(5)\fR\&\fR\&, \fB\fIscript(5)\fR\&\fR\&, \fB\fIsys(3erl)\fR\&\fR\&, \fB\fIsystools(3erl)\fR\&\fR\&