<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year>
<year>2011</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_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>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>
</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>
