diff options
Diffstat (limited to 'lib/sasl/doc/src/systools.xml')
| -rw-r--r-- | lib/sasl/doc/src/systools.xml | 347 |
1 files changed, 180 insertions, 167 deletions
diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml index 11d99fa595..1a5119a5cf 100644 --- a/lib/sasl/doc/src/systools.xml +++ b/lib/sasl/doc/src/systools.xml @@ -31,17 +31,18 @@ <rev></rev> </header> <module>systools</module> - <modulesummary>A Set of Release Handling Tools.</modulesummary> + <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>.boot</c>, <c>.script</c>), a release upgrade file (<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> + <fsummary>Generates a release upgrade file <c>relup</c>.</fsummary> <type> <v>Name = string()</v> <v>UpFrom = DownTo = [Name | {Name,Descr}]</v> @@ -50,93 +51,94 @@ | warnings_as_errors</v> <v> Dir = string()</v> <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v> - <v> Relup - see relup(4)</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>Generates a release upgrade file <c>relup</c> containing instructions + for upgrading from or downgrading to one or more previous releases. + The instructions are used by + <seealso marker="release_handler"><c>release_handler</c></seealso> + when installing a new version of a release in runtime.</p> + <p>By default, <c>relup</c> file is located in the current working + directory. If option <c>{outdir,Dir}</c> is specified, + the <c>relup</c> file is located 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> + all release resource files <c>Name2.rel</c>, specified in + <c>UpFrom</c> and <c>DownTo</c>. For each such pair, the + following 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> + <p>Which applications to be deleted, that is, + applications 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> + <p>Which applications to be added, that is, applications + 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> + <p>Which applications to 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> + downgrading, that is, if the <c>ERTS</c> 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 + <p>Instructions for this are added to the <c>relup</c> file 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 + <seealso marker="#make_script/1"><c>make_script/1,2</c></seealso>. + High-level instructions are translated + into low-level instructions and the result is printed to the + <c>relup</c> file.</p> + <p>The optional <c>Descr</c> parameter is included "as is" in + the <c>relup</c> file, see + <seealso marker="relup"><c>relup(4)</c></seealso>. 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 + assumed that the <c>.app</c> and <c>.appup</c> files for an + application are located in the same directory.</p> + <p>If option <c>{path,[Dir]}</c> is specified, this path is + appended to the current path. Wildcard <c>*</c> is + expanded to all matching directories, for example, + <c>lib/*/ebin</c>.</p> + <p>If option <c>restart_emulator</c> is specified, a low-level instruction to restart the emulator is appended to - the relup scripts. This ensures that a complete reboot of + the <c>relup</c> file. This ensures that a complete reboot of the system is done when the system is upgraded or downgraded.</p> - <p>If an upgrade includes a change from an emulator earlier - than OTP R15 to OTP R15 or later, the warning - <c>pre_R15_emulator_upgrade</c> is issued. See <seealso - marker="doc/design_principles:appup_cookbook">Design - Principles</seealso> for more information about this.</p> + <p>If an upgrade includes a change from an emulator earlier + than OTP R15 to OTP R15 or later, the warning + <c>pre_R15_emulator_upgrade</c> is issued. For more information + about this, see + <seealso marker="doc/design_principles:appup_cookbook">Design + Principles</seealso> in <em>System Documentation</em>.</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 + the function returns <c>ok</c> or <c>error</c>. If option + <c>silent</c> is specified, the function instead either returns + <c>{ok,Relup,Module,Warnings}</c>, where <c>Relup</c> is + the release upgrade file, 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> - <p>If the option <c>noexec</c> is provided, the function returns + <p>If option <c>noexec</c> is specified, the function returns the same values as for <c>silent</c> but no <c>relup</c> file is created.</p> - <p>If the option <c>warnings_as_errors</c> is provided, warnings - are treated as errors.</p> + <p>If option <c>warnings_as_errors</c> is specified, warnings + are treated as errors.</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> + <fsummary>Generates a boot script <c>.script/.boot</c>.</fsummary> <type> <v>Name = string()</v> <v>Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | @@ -153,114 +155,117 @@ <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 + specifies which code to be loaded and which applications + to be started when the Erlang runtime system is started. + See <seealso marker="script"><c>script(4)</c></seealso>.</p> + <p>The release resource file <c>Name.rel</c> is read to determine + which applications are included in the release. Then + the relevant application resource files <c>App.app</c> are read + to determine which modules to be loaded, and if and + how the applications are to be started. (Keys <c>modules</c> + and <c>mod</c>, see + <seealso marker="kernel:app"><c>app(4)</c></seealso>.</p> + <p>By default, the boot script and boot file are located 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 + option <c>{outdir,Dir}</c> is specified, they are located in <c>Dir</c> instead.</p> - <p>The correctness of each application is checked:</p> + <p>The correctness of each application is checked as follows:</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 + the <c>.rel</c> file is to 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> + <p>There are to be no undefined applications, that is, + dependencies to applications that are not included in + the release. (Key <c>applications</c> in the <c>.app</c> file).</p> </item> <item> - <p>There should be no circular dependencies among + <p>There are to be no circular dependencies among the applications.</p> </item> <item> - <p>There should be no duplicated modules, that is, modules with + <p>There are to be no duplicated modules, that is, modules with the same name but belonging to different applications.</p> </item> <item> - <p>If the <c>src_tests</c> option is specified, a + <p>If option <c>src_tests</c> is specified, a warning is issued if the source code for a module is - missing or newer than the object code.</p> + missing or is newer than the object code.</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>The function will fail if the mandatory - applications <c>kernel</c> and <c>stdlib</c> are not - included in the <c>.rel</c> file and have start - type <c>permanent</c> (default).</p> - <p>If <c>sasl</c> is not included as an application in - the <c>.rel</c> file, a warning is emitted because such a - release can not be used in an upgrade. To turn off this - warning, add the option <c>no_warn_sasl</c>.</p> + <p>The function fails if the mandatory + applications <c>Kernel</c> and <c>STDLIB</c> are not + included in the <c>.rel</c> file and have start + type <c>permanent</c> (which is default).</p> + <p>If <c>SASL</c> is not included as an application in + the <c>.rel</c> file, a warning is issued because such a + release cannot be used in an upgrade. To turn off this + warning, add option <c>no_warn_sasl</c>.</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> + application are 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 + it is an <c>ebin</c> directory in which case they can be located in the corresponding <c>src</c> directory.</p> - <p>If the option <c>{path,[Dir]}</c> is provided, this path is + <p>If option <c>{path,[Dir]}</c> is specified, 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 + specified 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 + structured as <c>App-Vsn/ebin</c>. They are 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 + of the installed release. If option <c>local</c> is + specified, 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 + <p>Option <c>variables</c> 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 + <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application gets 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 + the path is <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> + values using command-line flag <c>boot_var</c>.</p> + <p><em>Example:</em> If option <c>{variables,[{"TEST","lib"}]}</c> + is specified and <c>myapp.app</c> is found in + <c>lib/myapp/ebin</c>, the path to this application in + the boot script is <c>"$TEST/myapp-1/ebin"</c>. If + <c>myapp.app</c> is found in <c>lib/test</c>, the path + is <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 + option <c>exref</c>. 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> + warnings are issued 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 + the function returns <c>ok</c> or <c>error</c>. If option + <c>silent</c> is specified, 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> - <p>If the option <c>warnings_as_errors</c> is provided, warnings - are treated as errors.</p> - <p>If the option <c>no_dot_erlang</c> is provided, the instruction to - load the <c>.erlang</c> file during boot is <em>NOT</em> included.</p> + <p>If option <c>warnings_as_errors</c> is specified, warnings + are treated as errors.</p> + <p>If option <c>no_dot_erlang</c> is specified, the instruction to + load the <c>.erlang</c> file during boot is <em>not</em> + included.</p> </desc> </func> + <func> <name>make_tar(Name) -> Result</name> <name>make_tar(Name, [Opt]) -> Result</name> - <fsummary>Create a release package.</fsummary> + <fsummary>Creates a release package.</fsummary> <type> <v>Name = string()</v> <v>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir}</v> @@ -276,90 +281,91 @@ <v> Warning = Error = term()</v> </type> <desc> - <p>Creates a release package file <c>Name.tar.gz</c>. file. + <p>Creates a release package file <c>Name.tar.gz</c>. 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 + system using + <seealso marker="release_handler"><c>release_handler</c></seealso> + before the new release can be installed.</p> + <p>The release resource file <c>Name.rel</c> is read to determine 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 + read to determine the version and modules of each application + (keys <c>vsn</c> and <c>modules</c>, see + <seealso marker="kernel:app"><c>app(4)</c></seealso>).</p> + <p>By default, the release package file is located 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> + directory unless <c>Name</c> contains a path. If option + <c>{outdir,Dir}</c> is specified, it is located 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: + included application. If more directories are to be included, + option <c>dirs</c> is specified, for 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 + option <c>{path,[Dir]}</c> is specified, this path is + appended to the current path. 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 + <p>Option <c>variables</c> 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 + the applications. If variable <c>{VarName,Prefix}</c> is + specified and an application is found in directory + <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application is 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 + <p><em>Example:</em> If option <c>{variables,[{"TEST","lib"}]}</c> + is specified and <c>myapp.app</c> is located in + <c>lib/myapp-1/ebin</c>, 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 +...</pre> + <p>Option <c>{var_tar,VarTar}</c> can be used to specify if + and where a separate package is to be stored. In this option + <c>VarTar</c> is one of the following:</p> + <taglist> + <tag><c>include</c></tag> + <item><p>Each separate (variable) package is included in the + main <c>ReleaseName.tar.gz</c> file. This is the + default.</p></item> + <tag><c>ownfile</c></tag> + <item><p>Each separate (variable) package is + generated as a separate file in the same directory as + the <c>ReleaseName.tar.gz</c> file.</p></item> + <tag><c>omit</c></tag> + <item><p>No separate (variable) packages are + generated. Applications that are found underneath a + variable directory are ignored.</p></item> + </taglist> + <p>A directory <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 + subdirectory <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 + specified using option <c>path</c>.</p> + <p>If the release package is to 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>src_tests</c> and <c>exref</c> options are also + <p>All checks with function + <seealso marker="#make_script/1"><c>make_script</c></seealso> + are performed before the release package is created. + Options <c>src_tests</c> and <c>exref</c> 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> + are the same as described for + <seealso marker="#make_script/1"><c>make_script</c></seealso>.</p> </desc> </func> + <func> <name>script2boot(File) -> ok | error</name> - <fsummary>Generate a binary version of a boot script.</fsummary> + <fsummary>Generates a binary version of a boot script.</fsummary> <type> <v>File = string()</v> </type> @@ -367,17 +373,24 @@ myapp-1/ebin/myapp.app <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> + to a binary term, which is stored in the <c>File.boot</c> + file.</p> + <p>A boot script generated using + <seealso marker="#make_script/1"><c>make_script</c></seealso> + 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> + <title>See Also</title> + <p><seealso marker="kernel:app"><c>app(4)</c></seealso>, + <seealso marker="appup"><c>appup(4)</c></seealso>, + <seealso marker="erts:erl"><c>erl(1)</c></seealso>, + <seealso marker="rel"><c>rel(4)</c></seealso>, + <seealso marker="release_handler"><c>release_handler(3)</c></seealso>, + <seealso marker="relup"><c>relup(4)</c></seealso>, + <seealso marker="script"><c>script(4)</c></seealso></p> </section> </erlref> |