The R13B03 release.OTP_R13B03

1 files changed, 362 insertions, 0 deletions

diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml
new file mode 100644
index 0000000000..296553bb12
--- /dev/null
+++ b/lib/sasl/doc/src/systools.xml
@@ -0,0 +1,362 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>systools</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>systools</module>
+  <modulesummary>A Set of Release Handling Tools.</modulesummary>
+  <description>
+    <p>This module contains functions to generate boot scripts
+      (<c>.boot</c>, <c>.script</c>), release upgrade scripts
+      (<c>relup</c>), and release packages.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>make_relup(Name, UpFrom, DownTo) -> Result</name>
+      <name>make_relup(Name, UpFrom, DownTo, [Opt]) -> Result</name>
+      <fsummary>Generate a release upgrade file <c>relup</c>.</fsummary>
+      <type>
+        <v>Name = string()</v>
+        <v>UpFrom = DownTo = [Name | {Name,Descr}]</v>
+        <v>&nbsp;Descr = term()</v>
+        <v>Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}</v>
+        <v>&nbsp;Dir = string()</v>
+        <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v>
+        <v>&nbsp;Relup - see relup(4)</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>&nbsp;Warnings = Error = term()</v>
+      </type>
+      <desc>
+        <p>Generates a release upgrade file <c>relup</c> containing a
+          script which describes how to upgrade the system from a number
+          of previous releases, and how to downgrade to a number of
+          previous releases. The script is used by
+          <c>release_handler</c> when installing a new version of a
+          release in run-time.</p>
+        <p>By default, <c>relup</c> is placed in the current working
+          directory. If the option <c>{outdir,Dir}</c> is provided,
+          <c>relup</c> is placed in <c>Dir</c> instead.</p>
+        <p>The release resource file <c>Name.rel</c> is compared with
+          all release resource files <c>Name2.rel</c> specified in
+          <c>UpFrom</c> and <c>DownTo</c>. For each such pair, it is
+          deducted:</p>
+        <list type="bulleted">
+          <item>
+            <p>Which applications should be deleted, that is
+              applications which are listed in <c>Name.rel</c> but not
+              in <c>Name2.rel</c>.</p>
+          </item>
+          <item>
+            <p>Which applications should be added, that is applications
+              which are listed in <c>Name2.rel</c> but not in
+              <c>Name.rel</c>.</p>
+          </item>
+          <item>
+            <p>Which applications should be upgraded/downgraded, that
+              is applications listed in both <c>Name.rel</c> and
+              <c>Name2.rel</c>, but with different versions.</p>
+          </item>
+          <item>
+            <p>If the emulator needs to be restarted after upgrading or
+              downgrading, that is if the ERTS version differs between
+              <c>Name.rel</c> and <c>Name2.rel</c>.</p>
+          </item>
+        </list>
+        <p>Instructions for this are added to the <c>relup</c> script in
+          the above order. Instructions for upgrading or downgrading
+          between application versions are fetched from the relevant
+          application upgrade files <c>App.appup</c>, sorted in
+          the same order as when generating a boot script, see
+          <c>make_script/1,2</c>. High-level instructions are translated
+          into low-level instructions and the result is printed to
+          <c>relup</c>.</p>
+        <p>The optional <c>Descr</c> parameter is included as-is in
+          the <c>relup</c> script, see <c>relup(4)</c>. Defaults to
+          the empty list.</p>
+        <p>All the files are searched for in the code path. It is
+          assumed that the <c>.app</c> and <c>.appup</c> file for an
+          application is located in the same directory.</p>
+        <p>If the option <c>{path,[Dir]}</c> is provided, this path is
+          appended to the current path. The wildcard <c>*</c> is
+          expanded to all matching directories.
+          Example: <c>lib/*/ebin</c>.</p>
+        <p>If the <c>restart_emulator</c> option is supplied, a
+          low-level instruction to restart the emulator is appended to
+          the relup scripts. This ensures that a complete reboot of
+          the system is done when the system is upgraded or downgraded.</p>
+        <p>By default, errors and warnings are printed to tty and
+          the function returns <c>ok</c> or <c>error</c>. If the option
+          <c>silent</c> is provided, the function instead returns
+          <c>{ok,Relup,Module,Warnings}</c> where <c>Relup</c> is
+          the release upgrade script, or it returns
+          <c>{error,Module,Error}</c>. Warnings and errors can be
+          converted to strings by calling
+          <c>Module:format_warning(Warnings)</c> or
+          <c>Module:format_error(Error)</c>.</p>
+        <p>If the option <c>noexec</c> is provided, the function returns
+          the same values as for <c>silent</c> but no <c>relup</c> file
+          is created.</p>
+      </desc>
+    </func>
+    <func>
+      <name>make_script(Name) -> Result</name>
+      <name>make_script(Name, [Opt]) -> Result</name>
+      <fsummary>Generate a boot script <c>.script/.boot</c>.</fsummary>
+      <type>
+        <v>Name = string()</v>
+        <v>Opt = no_module_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir}</v>
+        <v>&nbsp;Dir = string()</v>
+        <v>&nbsp;Var = {VarName,Prefix}</v>
+        <v>&nbsp;&nbsp;VarName = Prefix = string()</v>
+        <v>&nbsp;App = atom()</v>
+        <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>&nbsp;Warnings = Error = term()</v>
+      </type>
+      <desc>
+        <p>Generates a boot script <c>Name.script</c> and its binary
+          version, the boot file <c>Name.boot</c>. The boot file
+          specifies which code should be loaded and which applications
+          should be started when the Erlang runtime system is started.
+          See <c>script(4)</c>.</p>
+        <p>The release resource file <c>Name.rel</c> is read to find
+          out which applications are included in the release. Then
+          the relevant application resource files <c>App.app</c> are
+          read to find out which modules should be loaded and if and
+          how the application should be started. (Keys <c>modules</c>
+          and <c>mod</c>, see <c>app(4)</c>).</p>
+        <p>By default, the boot script and boot file are placed in
+          the same directory as <c>Name.rel</c>. That is, in the current
+          working directory unless <c>Name</c> contains a path. If
+          the option <c>{outdir,Dir}</c> is provided, they are placed
+          in <c>Dir</c> instead.</p>
+        <p>The correctness of each application is checked:</p>
+        <list type="bulleted">
+          <item>
+            <p>The version of an application specified in
+              the <c>.rel</c> file should be the same as the version
+              specified in the <c>.app</c> file.</p>
+          </item>
+          <item>
+            <p>There should be no undefined applications, that is,
+              dependencies to applications which are not included in
+              the release. (Key <c>applications</c> in <c>.app</c>
+              file).</p>
+          </item>
+          <item>
+            <p>There should be no circular dependencies among
+              the applications.</p>
+          </item>
+          <item>
+            <p>There should no duplicated modules, that is, modules with
+              the same name but belonging to different applications.</p>
+          </item>
+          <item>
+            <p>A warning is issued if the source code for a module is
+              missing or newer than the object code.              <br></br>
+
+              If the <c>no_module_tests</c> option is specified, this
+              check is omitted.</p>
+          </item>
+        </list>
+        <p>The applications are sorted according to the dependencies
+          between the applications. Where there are no dependencies,
+          the order in the <c>.rel</c> file is kept.</p>
+        <p>All files are searched for in the current path. It is
+          assumed that the <c>.app</c> and <c>.beam</c> files for an
+          application is located in the same directory. The <c>.erl</c>
+          files are also assumed to be located in this directory, unless
+          it is an <c>ebin</c> directory in which case they may be
+          located in the corresponding <c>src</c> directory.</p>
+        <p>If the option <c>{path,[Dir]}</c> is provided, this path is
+          appended to the current path. A directory in the path can be
+          given with a wildcard <c>*</c>, this is expanded to all
+          matching directories. Example: <c>"lib/*/ebin"</c>.</p>
+        <p>In the generated boot script all application directories are
+          structured as <c>App-Vsn/ebin</c> and assumed to be located
+          in <c>$ROOT/lib</c>, where <c>$ROOT</c> is the root directory
+          of the installed release. If the <c>local</c> option is
+          supplied, the actual directories where the applications were
+          found are used instead. This is a useful way to test a
+          generated boot script locally.</p>
+        <p>The <c>variables</c> option can be used to specify an
+          installation directory other than <c>$ROOT/lib</c> for some of
+          the applications. If a variable <c>{VarName,Prefix}</c> is
+          specified and an application is found in a directory
+          <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application will get
+          the path <c>VarName/Rest/App-Vsn/ebin</c> in the boot script.
+          If an application is found in a directory <c>Prefix/Rest</c>,
+          the path will be <c>VarName/Rest/App-Vsn/ebin</c>. When
+          starting Erlang, all variables <c>VarName</c> are given
+          values using the <c>boot_var</c> command line flag.</p>
+        <p>Example: If the option <c>{variables,[{"TEST","lib"}]}</c> is
+          supplied, and <c>myapp.app</c> is found in
+          <c>lib/myapp/ebin</c>, then the path to this application in
+          the boot script will be <c>$TEST/myapp-1/ebin"</c>. If
+          <c>myapp.app</c> is found in <c>lib/test</c>, then the path
+          will be <c>$TEST/test/myapp-1/ebin</c>.</p>
+        <p>The checks performed before the boot script is generated can
+          be extended with some cross reference checks by specifying
+          the <c>exref</c> option. These checks are performed with
+          the Xref tool. All applications, or the applications specified
+          with <c>{exref,[App]}</c>, are checked by Xref and
+          warnings are generated for calls to undefined functions.</p>
+        <p>By default, errors and warnings are printed to tty and
+          the function returns <c>ok</c> or <c>error</c>. If the option
+          <c>silent</c> is provided, the function instead returns
+          <c>{ok,Module,Warnings}</c> or <c>{error,Module,Error}</c>.
+          Warnings and errors can be converted to strings by calling
+          <c>Module:format_warning(Warnings)</c> or
+          <c>Module:format_error(Error)</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>make_tar(Name) -> Result</name>
+      <name>make_tar(Name, [Opt]) -> Result</name>
+      <fsummary>Create a release package.</fsummary>
+      <type>
+        <v>Name = string()</v>
+        <v>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | no_module_tests | exref | {exref,[App]} | silent | {outdir,Dir}</v>
+        <v>&nbsp;Dir = string()</v>
+        <v>&nbsp;IncDir = src | include | atom()</v>
+        <v>&nbsp;Var = {VarName,PreFix}</v>
+        <v>&nbsp;&nbsp;VarName = Prefix = string()</v>
+        <v>&nbsp;VarTar = include | ownfile | omit</v>
+        <v>&nbsp;Machine = atom()</v>
+        <v>&nbsp;App = atom()</v>
+        <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>&nbsp;Warning = Error = term()</v>
+      </type>
+      <desc>
+        <p>Creates a release package file <c>Name.tar.gz</c>. file.
+          This file must be uncompressed and unpacked on the target
+          system using the <c>release_handler</c>, before the new
+          release can be installed.</p>
+        <p>The release resource file <c>Name.rel</c> is read to find out
+          which applications are included in the release. Then
+          the relevant application resource files <c>App.app</c> are
+          read to find out the version and modules of each application.
+          (Keys <c>vsn</c> and <c>modules</c>, see <c>app(4)</c>).</p>
+        <p>By default, the release package file is placed in the same
+          directory as <c>Name.rel</c>. That is, in the current working
+          directory unless <c>Name</c> contains a path. If the option
+          <c>{outdir,Dir}</c> is provided, it is placed in <c>Dir</c>
+          instead.</p>
+        <p>By default, the release package contains the directories
+          <c>lib/App-Vsn/ebin</c> and <c>lib/App-Vsn/priv</c> for each
+          included application. If more directories, the option
+          <c>dirs</c> is supplied. Example:
+          <c>{dirs,[src,examples]}</c>.</p>
+        <p>All these files are searched for in the current path. If
+          the option <c>{path,[Dir]}</c> is provided, this path is
+          appended to the current path. The wildcard <c>*</c> is
+          expanded to all matching directories.
+          Example: <c>"lib/*/ebin"</c>.</p>
+        <p>The <c>variables</c> option can be used to specify an
+          installation directory other than <c>lib</c> for some of
+          the applications. If a variable <c>{VarName,Prefix}</c> is
+          specified and an application is found in a directory
+          <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application will be
+          packed into a separate <c>VarName.tar.gz</c> file as
+          <c>Rest/App-Vsn/ebin</c>.</p>
+        <p>Example: If the option <c>{variables,[{"TEST","lib"}]}</c> is
+          supplied, and <c>myapp.app</c> is found in
+          <c>lib/myapp-1/ebin</c>, the the application <c>myapp</c> is
+          included in <c>TEST.tar.gz</c>:</p>
+        <pre>
+% <input>tar tf TEST.tar</input>
+myapp-1/ebin/myapp.app
+...
+        </pre>
+        <p>The <c>{var_tar,VarTar}</c> option can be used to specify if
+          and where a separate package should be stored. In this option,
+          <c>VarTar</c> is:</p>
+        <list type="bulleted">
+          <item>
+            <p><c>include</c>. Each separate (variable) package is
+              included in the main <c>ReleaseName.tar.gz</c> file. This
+              is the default.</p>
+          </item>
+          <item>
+            <p><c>ownfile</c>. Each separate (variable) package is
+              generated as separate files in the same directory as
+              the <c>ReleaseName.tar.gz</c> file.</p>
+          </item>
+          <item>
+            <p><c>omit</c>. No separate (variable) packages are
+              generated and applications which are found underneath a
+              variable directory are ignored.</p>
+          </item>
+        </list>
+        <p>A directory called <c>releases</c> is also included in
+          the release package, containing <c>Name.rel</c> and a
+          subdirectory called <c>RelVsn</c>. <c>RelVsn</c> is
+          the release version as specified in <c>Name.rel</c>.</p>
+        <p><c>releases/RelVsn</c> contains the boot script
+          <c>Name.boot</c> renamed to <c>start.boot</c> and, if found,
+          the files <c>relup</c> and <c>sys.config</c>. These files
+          are searched for in the same directory as <c>Name.rel</c>,
+          in the current working directory, and in any directories
+          specified using the <c>path</c> option.</p>
+        <p>If the release package should contain a new Erlang runtime
+          system, the <c>bin</c> directory of the specified runtime
+          system <c>{erts,Dir}</c> is copied to <c>erts-ErtsVsn/bin</c>.</p>
+        <p>All checks performed with the <c>make_script</c> function
+          are performed before the release package is created. The
+          <c>no_module_tests</c> and <c>exref</c> options are also
+          valid here.</p>
+        <p>The return value and the handling of errors and warnings
+          are the same as described for <c>make_script</c> above.</p>
+      </desc>
+    </func>
+    <func>
+      <name>script2boot(File) -> ok | error</name>
+      <fsummary>Generate a binary version of a boot script.</fsummary>
+      <type>
+        <v>File = string()</v>
+      </type>
+      <desc>
+        <p>The Erlang runtime system requires that the contents of
+          the script used to boot the system is a binary Erlang term.
+          This function transforms the <c>File.script</c> boot script
+          to a binary term which is stored in the file <c>File.boot</c>.</p>
+        <p>A boot script generated using the <c>make_script</c>
+          function is already transformed to the binary form.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
+      script(4)</p>
+  </section>
+</erlref>
+