diff options
Diffstat (limited to 'lib/sasl/doc/src/systools.xml')
| -rw-r--r-- | lib/sasl/doc/src/systools.xml | 362 |
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> Descr = term()</v> + <v>Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}</v> + <v> Dir = string()</v> + <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v> + <v> Relup - see relup(4)</v> + <v> Module = atom()</v> + <v> 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> Dir = string()</v> + <v> Var = {VarName,Prefix}</v> + <v> VarName = Prefix = string()</v> + <v> App = atom()</v> + <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v> + <v> Module = atom()</v> + <v> 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> Dir = string()</v> + <v> IncDir = src | include | atom()</v> + <v> Var = {VarName,PreFix}</v> + <v> VarName = Prefix = string()</v> + <v> VarTar = include | ownfile | omit</v> + <v> Machine = atom()</v> + <v> App = atom()</v> + <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v> + <v> Module = atom()</v> + <v> 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> + |