aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc/src/systools.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/sasl/doc/src/systools.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/sasl/doc/src/systools.xml')
-rw-r--r--lib/sasl/doc/src/systools.xml362
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>
+