<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year> <year>2013</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} | 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> 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>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>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> <p>If the option <c>warnings_as_errors</c> is provided, 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> <type> <v>Name = string()</v> <v>Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir} | no_dot_erlang | no_warn_sasl | warnings_as_errors</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 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 warning is issued if the source code for a module is missing or 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>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> <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> </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} | src_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>src_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>