release_handler

模块

释放[医]处理程序

模块摘要

拆下和安装释放包

描述

大释放处理程序进程属于ssl应用程序，该应用程序负责释放处理，即解压、安装和拆卸释放包。

介绍以释放处理，并设置在一个例子OTP Design Principles中系统文档。

甲释放包是包含代码用于一个特定版本的释放的压缩tar文件，通过调用创建systools:make_tar/1,2。发行包位于$ROOT/releases发行版以前版本的目录中，其中$ROOT是安装根目录，code:root_dir()。releases可以使用SASL配置参数releases_dir或OS环境变量指定另一个目录RELDIR。释放处理程序必须具有对此目录的写入权限才能安装新版本。释放处理程序的持久状态存储在名为的文件中RELEASES。

发布包总是包含：

• 发布资源文件，Name.rel

• 启动脚本，Name.boot

大.rel文件包含有关发行版的信息：它的名称、版本以及它使用的ERTS和应用程序版本。

发布包还可以包含：

• 发布升级文件，relup

• 一个系统配置文件，sys.config

大relup文件包含有关如何升级到此版本或从此版本降级的说明。

发布包可以是未包装提取文件。未打包的版本可以是安装然后，通过对“指定版本”中的说明进行评估，将当前使用的版本升级或降级到指定版本。relup档案。可以制作已安装的版本。永久系统中只能存在一个永久版本，如果系统重新启动，则使用此版本。已安装的发行版(永久版本除外)可以是移除当一个版本被删除时，属于该版本的所有文件都会被删除。

每个发行版本都有一个状态，它可以是unpacked，current，permanent，或old。总是有一个最新版本，它具有状态permanent（正常情况）或current（安装，但尚未永久）。下表说明了状态值的含义：

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                -

发布处理程序进程是在每个节点上本地注册的进程。在分布式系统中安装发行版时，必须调用每个节点上的发布处理程序。发布安装可以在节点之间同步。从运算符的角度来看，指定每个节点可能不令人满意。其目的是在系统中安装一个发行包，不管有多少节点。建议编写解决此问题的软件管理功能。这样的函数可以具有系统架构的知识，因此它可以联系每个单独的发布处理程序来安装包。

为了使发布处理正常工作，运行时系统必须知道它正在运行哪个发行版。如果系统重新启动，它还必须能够更改（在运行系统中）使用哪个引导脚本和系统配置文件。如果Erlang作为嵌入式系统启动，这将自动处理。Embedded System在“ 系统文档”中阅读此内容。在这种情况下，系统配置文件sys.config是强制性的。

安装新版本可以重新启动系统。要使用的程序由SASL配置参数指定start_prg，默认为$ROOT/bin/start。

Windows NT上的仿真程序重新启动需要使用该erlsrv程序启动系统（作为服务）。此外，释放处理程序期望该服务被命名为NodeName_ Release，其中NodeName是Erlang节点名称的第一部分（最高但不包括“@”），并且Release是当前发行版本。此外，释放处理程序期望类似的程序start_erl.exe被指定为“机器” erlsrv。在重新启动升级期间，注册并启动一项新服务。新服务被设置为自动，并且在新版本永久化时旧服务被删除。

必须使用以下SASL配置参数相应配置在无盘计算机上运行的节点或具有只读文件系统的节点上的释放处理程序（有关详细信息，请参阅sasl(6)）：

masters

该节点使用一些主节点来存储和获取发布信息。每当发布信息由该节点编写时，所有主节点都必须是可操作的。

client_directory

大client_directory在主节点的目录结构中必须指定。

static_emulator

此参数指定Erlang模拟器是否静态地安装在客户端节点上。具有静态模拟器的节点不能动态切换到新的模拟器，因为可执行文件是静态写入内存的。

当不将Erlang作为嵌入式系统运行时，发布处理程序也可以用于解压缩和安装发布包。但是，在这种情况下，用户必须确保在必须重新启动系统时使用正确的引导脚本和配置文件。

函数用于使用比OTP中定义的结构更多的文件结构。这些函数可用于本地测试版本升级。

出口

check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}

类型

检查指定版本是否Vsn的版本可以安装。发布不得具有状态。current.在下列情况下发出警告relup档案或sys.config不存在。如果relup文件存在，检查其内容{error,Reason}如果发现错误，则返回。还检查是否存在所有必需的应用程序，以及是否可以加载所有新代码；{error,Reason}如果发现错误，则返回。

对象之前发生的所有指令。point_of_no_return发布升级脚本中的指令。

返回与install_release/1。Descr默认为“”，如果没有relup找到文件。

如果purge指定了选项，则在所有其他检查都成功完成后，可清除所有可被软清除的旧代码。这可以减少所需的时间install_release/1。

create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}

类型

创建一个初始RELEASES将由发布处理程序使用的文件。此文件必须存在才能安装新版本。

Root是$ROOT前面所述的installation（）的根。RelDir是RELEASES要创建文件的目录（通常$ROOT/releases）。RelFile是.rel描述初始版本的文件的名称，包括扩展名.rel。

AppDirs可以用来指定从哪里加载指定应用程序的模块。App是应用程序的名称，Vsn是版本，并且Dir是所在目录的名称App-Vsn。相应的模块将位于下方Dir/App-Vsn/ebin。AppDirs假定未指定的应用程序目录位于中$ROOT/lib。

install_file(Vsn, File) -> ok | {error, Reason}

类型

在发行版结构中安装与版本相关的文件。发布相关文件必须在释放结构安装新版本时：start.boot，relup，和sys.config。

例如，当在目标处生成这些文件时，可以调用该函数。函数将在后面调用。set_unpacked/2已经被召唤了。

install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}

类型

安装指定版本Vsn的发行版。首先查找此relup文件中的文件Vsn和脚本{UpFromVsn,Descr1,Instructions1}以从当前版本升级。如果找不到，该函数将查找relup当前版本的文件以及{Vsn,Descr2,Instructions2}该文件中用于降级的脚本Vsn。

如果找到脚本，首先会发生的情况是应用程序规范根据.app文件进行更新并且sys.config属于发行版本Vsn。

应用程序规范更新后，将评估脚本中的指令，并在{ok,OtherVsn,Descr}成功时返回函数。OtherVsn并且Descr是脚本中指定的版本（UpFromVsn或Vsn）和描述（Descr1或Descr2）。

如果{continue_after_restart,OtherVsn,Descr}返回时，将在执行升级指令之前重新启动模拟器。如果仿真器或任何应用程序内核、STDLIB或SASL被更新，则会发生这种情况。新的模拟器版本和这些核心应用程序在重新启动后执行。对于所有其他应用程序，将启动旧版本，并通过执行升级指令以正常方式执行升级。

如果发生可恢复错误，则该函数将返回{error,Reason}并恢复了原来的应用规范。如果发生不可恢复的错误，系统将重新启动。

备选方案*

error_action

定义在安装过程中是否发生错误，节点是重新启动（init:restart()）还是重新启动（init:reboot()）。默认是restart。

code_change_timeout

定义所有调用的超时时间。sys:change_code如果未指定值，则为default中定义的默认值。sys被使用了。

suspend_timeout

定义所有调用的超时时间。sys:suspend如果未指定值，则由Timeout参数的upgrade或suspend使用指令。如果default中定义的默认值。sys被使用了。

{update_paths,Bool}

指示是要更新所有应用程序代码路径（Bool==true）还是仅更新已修改应用程序的代码路径（Bool==false默认）。此选项仅对默认的其他应用程序目录有效$ROOT/lib/App-Vsn，即AppDirs对调用create_RELEASES/4或中的参数中指定的应用程序目录set_unpacked/2。

例子：

在当前版本中CurVsn的应用程序目录。myapp是$ROOT/lib/myapp-1.0新版本NewVsn在发布处理程序之外解压缩，并通过调用通知发布处理程序，如下所示：

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

如果NewVsn用选项安装{update_paths,true}，则code:lib_dir(myapp)返回/home/user/myapp-1.0。

注

如果系统中有许多进程，安装新版本可能会很费时。原因是，在清除模块之前，必须检查每个进程对旧代码的引用。此检查可能导致垃圾收集和数据复制。

加快执行install_release，第一次呼叫check_install_release，使用选项purge这对旧代码也有同样的检查。然后清除所有可以被软清除的模块。清除模块就不再有任何旧代码，而且install_release不需要做检查。

这并不会减少升级的总时间，但它允许在真正的升级开始之前在后台执行检查和清除。

注

从OTP R15之前的版本升级仿真器时，会尝试将新的应用程序束代码加载到旧仿真器中。有时新的波束格式不能被旧的仿真器读取，因此代码加载失败，并且完全升级被终止。为了克服这个问题，新的应用程序代码将与旧的模拟器一起编译。有关从预OTP R15版本的模拟器升级的详细信息，请参阅Design Principles在系统文档。

make_permanent(Vsn) -> ok | {error, Reason}

类型

生成指定的发行版本。Vsn永久的。

remove_release(Vsn) -> ok | {error, Reason}

类型

从系统中移除发行版及其文件。释放不能是永久释放。仅移除其他版本未使用的文件和目录。

reboot_old_release(Vsn) -> ok | {error, Reason}

类型

通过使旧版本永久重启系统，并init:reboot()直接调用。发布版必须具有状态old。

set_removed(Vsn) -> ok | {error, Reason}

类型

使得可以处理发布处理程序之外的版本删除。通知发布处理程序，发布已从系统中删除。此函数不删除任何文件。

set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}

类型

使得可以在释放处理程序之外处理解压缩版本。告诉释放处理程序该版本已解包。Vsn是从释放资源文件中提取的RelFile。

AppDirs可以用来指定从哪里加载指定应用程序的模块。App是应用程序的名称，Vsn是版本，并且Dir是所在目录的名称App-Vsn。相应的模块将位于下方Dir/App-Vsn/ebin。AppDirs假定未指定的应用程序目录位于中$ROOT/lib。

unpack_release(Name) -> {ok, Vsn} | {error, Reason}

类型

解包Name.tar.gz位于releases目录。

对包执行一些检查，例如，检查是否存在所有强制文件，并提取其内容。

which_releases() -> [{Name, Vsn, Apps, Status}]

类型

返回发行处理程序已知的所有版本。

which_releases(Status) -> [{Name, Vsn, Apps, Status}]

类型

返回特定状态的所有版本(发布处理程序已知)。

应用程序升级/降级

以下功能可用于测试单个应用程序%28的升级和降级，而不是升级/降级整个版本%29。中的指令对应的脚本。relup文件是根据.appup文件，并以与release_handler是的。

警告

这些功能主要用于简化.appup档案。类的上下文中没有运行它们。release_handler过程。因此，他们必须不与调用一起使用install_release/1,2，因为这会导致release_handler以不一致的状态结束。

不更新持久信息，因此这些函数可以在任何Erlang节点上使用，无论嵌入与否。此外，如果有重新启动，使用这些函数不会影响加载哪些代码。

如果升级或降级失败，应用程序可能会处于不一致的状态。

出口

upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}

类型

升级应用程序App从当前版本到新版本的Dir根据.appup档案。

App是应用程序的名称，必须启动。Dir是新的图书馆目录App。相应的模块以及.app和.appup文件将位于下方Dir/ebin。

函数在.appup文件并尝试使用以下方法从应用程序的当前版本找到升级脚本。upgrade_script/2.此脚本将使用eval_appup_script/4，就像install_release/1,2是的。

返回下列内容之一：

• {ok, Unpurged}如果评估脚本成功，则在Unpurged是未清除模块的列表。

• restart_emulator如果在脚本中遇到此指令

• {error, Reason}如果在查找或计算脚本时发生错误

如果restart_new_emulator在脚本中找到该指令，则upgrade_app/2返回{error,restart_new_emulator}。这是因为restart_new_emulator需要在执行其余升级指令之前启动新版本的仿真器，并且这只能通过install_release/1,2。

downgrade_app(App, Dir) ->downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}

类型

降级应用程序App从当前版本到以前版本OldVsn位于Dir根据.appup档案。

App是应用程序的名称，必须启动。OldVsn是以前的应用程序版本，如果Dir是格式，则可以省略"App-OldVsn"。Dir是以前版本的库目录App。相应的模块和旧.app文件将位于下方Dir/ebin。该.appup文件将位于应用程序（）ebin的当前库目录的目录中code:lib_dir(App)。

函数在.appup文件，并尝试使用以下方法找到将脚本降级为应用程序的前一个版本的脚本。downgrade_script/3.此脚本将使用eval_appup_script/4，就像install_release/1,2是的。

返回下列内容之一：

• {ok, Unpurged}如果评估脚本成功，则在Unpurged是未清除模块的列表。

• restart_emulator如果在脚本中遇到此指令

• {error, Reason}如果在查找或计算脚本时发生错误

upgrade_script(App, Dir) -> {ok, NewVsn, Script}

类型

尝试找到应用程序升级脚本App从当前版本到新版本的Dir...

然后，可以使用eval_appup_script/4.建议使用upgrade_app/2但是这个函数%28upgrade_script%29用于检查脚本的内容。

App必须启动的应用程序的名称。Dir的新库目录。App相应的模块以及.app和.appup文件位于Dir/ebin...

函数在.appup文件并尝试从当前应用程序版本找到升级脚本。高级指令被翻译成低级指令.。指令的排序方式与生成relup档案。

回报{ok, NewVsn, Script}如果成功，哪里NewVsn是新的应用程序版本。有关Script，见appup(4)...

失败：如果找不到脚本，函数就会失败，并有适当的错误原因。

downgrade_script(App, OldVsn, Dir) -> {ok, Script}

类型

试图找到一个应用程序降级脚本App从当前版本到以前的版本OldVsn位于Dir。

然后可以使用降级脚本进行评估eval_appup_script/4。建议使用它downgrade_app/2,3，但是此函数（downgrade_script）对检查脚本的内容很有用。

App是应用程序的名称，必须启动。Dir是以前的图书馆目录App。相应的模块和旧.app文件将位于下方Dir/ebin。该.appup文件将位于应用程序ebin的当前库目录的目录中（code:lib_dir(App))。

函数在.appup文件并尝试从当前应用程序版本中找到降级脚本。高级指令被翻译成低级指令.。指令的排序方式与生成relup档案。

{ok, Script}如果成功则返回。有关详细信息Script，请参阅appup(4)。

失败：如果找不到脚本，函数就会失败，并有适当的错误原因。

eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}

类型

See [`upgrade_script/2`](about:blank#upgrade_script-2), [`downgrade_script/3`](about:blank#downgrade_script-3) 

评估应用程序升级或降级脚本Script，调用的结果upgrade_script/2或downgrade_script/3，就像install_release/1,2是的。

App是应用程序的名称，必须启动。ToVsn是要升级/降级到的版本，并且ToDir是此版本的库目录。相应的模块以及.app和.appup文件将位于下方Dir/ebin。

返回下列内容之一：

• {ok, Unpurged}如果评估脚本成功，则在Unpurged是未清除模块的列表。

• restart_emulator如果在脚本中遇到此指令

• {error, Reason}如果在查找或计算脚本时发生错误

如果restart_new_emulator在脚本中找到该指令，则eval_appup_script/4返回{error,restart_new_emulator}。这是因为restart_new_emulator需要在执行其余升级指令之前启动新版本的仿真器，并且这只能通过install_release/1,2。

典型错误原因

{bad_masters, Masters}

主节点Masters都不活着了。

{bad_rel_file, File}

规定.rel档案File不能阅读或不包含单个术语。

{bad_rel_data, Data}

规定.rel文件不包含公认的发布规范，而是另一个术语。Data...

{bad_relup_file, File}

规定relup档案Relup包含坏数据。

{cannot_extract_file, Name, Reason}

从tar文件中提取问题时，erl_tar:extract/2退回来{error, {Name, Reason}}...

{existing_release, Vsn}

指定发行版本Vsn已经在使用了。

{Master, Reason, When}

一些操作，用术语表示When，在主节点上失败。Master具有指定错误原因的Reason...

{no_matching_relup, Vsn, CurrentVsn}

无法找到用于升级/降级的脚本CurrentVsn和Vsn...

{no_such_directory, Path}

目录Path不存在。

{no_such_file, Path}

路径Path（文件或目录）不存在。

{no_such_file, {Master, Path}}

Path主节点上不存在路径（文件或目录）Master。

{no_such_release, Vsn}

指定的发行版本Vsn不存在。

{not_a_directory, Path}

Path存在但不是目录。

{Posix, File}

某些文件操作失败File。Posix是从Posix的错误代码命名的原子，如enoent，eacces，或eisdir。file(3)在Kernel中查看。

Posix

某些文件操作失败，如列表中的前一项。

另见

OTP Design Principles, config(4), rel(4), relup(4), script(4), sys(3), systools(3)