diff options
Diffstat (limited to 'system/doc/design_principles/release_handling.xml')
| -rw-r--r-- | system/doc/design_principles/release_handling.xml | 44 |
1 files changed, 23 insertions, 21 deletions
diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml index 8ed36f3c56..4378b6599c 100644 --- a/system/doc/design_principles/release_handling.xml +++ b/system/doc/design_principles/release_handling.xml @@ -178,13 +178,13 @@ <marker id="instr"></marker> <title>Release Handling Instructions</title> <p>OTP supports a set of <em>release handling instructions</em> - that is used when creating <c>.appup</c> files. The release + that are used when creating <c>.appup</c> files. The release handler understands a subset of these, the <em>low-level</em> instructions. To make it easier for the user, there are also a number of <em>high-level</em> instructions, which are translated to low-level instructions by <c>systools:make_relup</c>.</p> <p>Here, some of the most frequently used instructions are - described. The complete list of instructions is found in + described. The complete list of instructions can be found in <c>appup(4)</c>.</p> <p>First, some definitions:</p> <taglist> @@ -239,9 +239,10 @@ <p><c>update</c> with argument <c>supervisor</c> is used when changing the start specification of a supervisor. See <seealso marker="appup_cookbook#sup">Appup Cookbook</seealso>.</p> - <p>The release handler finds the processes <em>using</em> a module - to update by traversing the supervision tree of each running - application and checking all the child specifications:</p> + <p>When a module is to be updated, the release handler finds + which processes that are <em>using</em> the module by + traversing the supervision tree of each running application + and checking all the child specifications:</p> <code type="none"> {Id, StartFunc, Restart, Shutdown, Type, Modules}</code> <p>A process is using a module if the name is listed in @@ -265,8 +266,8 @@ <p>The instruction loads the module and is absolutely necessary when running Erlang in embedded mode. It is not strictly required when running Erlang in interactive (default) mode, - since the code server automatically searches for and loads - unloaded modules.</p> + since the code server then automatically searches for and + loads unloaded modules.</p> <p>The opposite of <c>add_module</c> is <c>delete_module</c> which unloads a module:</p> <code type="none"> @@ -294,7 +295,7 @@ the modules are unloaded using a number of <c>delete_module</c> instructions and then the application specification is unloaded from the application controller.</p> - <p>Instruction for removing an application:</p> + <p>Instruction for restarting an application:</p> <code type="none"> {restart_application, Application}</code> <p>Restarting an application means that the application is stopped @@ -331,17 +332,17 @@ of the emulator and the core applications. Then it shuts down the current emulator by calling <c>init:reboot()</c>, see <c>init(3)</c>. All processes are terminated gracefully and - the system can then be rebooted by the heart program, using - the temporary boot file. After the reboot, the rest of the - relup instructions are executed. This is done as a part of the - boot script.</p> + the system is rebooted by the heart program, using the + temporary boot file. After the reboot, the rest of the relup + instructions are executed. This is done as a part of the + temporary boot script.</p> <p>An info report is written when the upgrade is completed. To programatically find out if the upgrade is complete, - call <c>release_handler:which_releases/0</c> and check if the - expected release has status <c>current</c>.</p> - <p>The new version must be made permanent when the new emulator - is up and running. Otherwise, the old version will be used in - case of a new system reboot.</p> + call <c>release_handler:which_releases(current)</c> and check + if it returns the expected (i.e. the new) release.</p> + <p>The new release version must be made permanent when the new + emulator is up and running. Otherwise, the old version will be + used in case of a new system reboot.</p> <p>On UNIX, the release handler tells the heart program which command to use to reboot the system. Note that the environment variable <c>HEART_COMMAND</c>, normally used by the heart @@ -362,8 +363,8 @@ a relup script, and it shall always be placed at the end. If the relup is generated by <c>systools:make_relup/3,4</c> this is automatically ensured.</p> - <p>When the release handler encounters the instruction, it shuts down - the emulator by calling <c>init:reboot()</c>, see + <p>When the release handler encounters the instruction, it shuts + down the emulator by calling <c>init:reboot()</c>, see <c>init(3)</c>. All processes are terminated gracefully and the system can then be rebooted by the heart program using the new release version. No more upgrade instruction will be @@ -581,8 +582,8 @@ release_handler:remove_release(Vsn) => ok</code> [].</code> <p>2) Start the system as a simple target system. Note that in reality, it should be started as an embedded system. However, - using <c>erl</c> with the correct boot script and <c>.config</c> - file is enough for illustration purposes:</p> + using <c>erl</c> with the correct boot script and config file is + enough for illustration purposes:</p> <pre> % <input>cd $ROOT</input> % <input>bin/erl -boot $ROOT/releases/A/start -config $ROOT/releases/A/sys</input> @@ -617,6 +618,7 @@ lib/ch_app-2/ebin/ch3.beam releases/B/start.boot releases/B/relup releases/B/sys.config +releases/B/ch_rel-2.rel releases/ch_rel-2.rel</code> <p>4) Copy the release package <c>ch_rel-2.tar.gz</c> to the <c>$ROOT/releases</c> directory.</p> |