<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2004</year><year>2012</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.
</legalnotice>
<title>SASL Release Notes</title>
<prepared>otp_appnotes</prepared>
<docno>nil</docno>
<date>nil</date>
<rev>nil</rev>
<file>notes.xml</file>
</header>
<p>This document describes the changes made to the SASL application.</p>
<section><title>SASL 2.3</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
release_handler_SUITE:otp_9864 deleted parts of the
release_handler_SUITE_data directory so the test suite
could not be executed twice without re-installation. This
has been corrected.</p>
<p>
Own Id: OTP-10394 Aux Id: kunagi-187 [98] </p>
</item>
<item>
<p>
It is no longer possible to have <c>{Mod,Vsn}</c> in the
'modules' list in a .app file.</p>
<p>
This was earlier possible, although never documented in
the .app file reference manual. It was however visible in
the documentation of <c>application:load/[1,2]</c>, where
the same term as in a .app file can be used as the first
argument.</p>
<p>
The possibility has been removed since the <c>Vsn</c>
part was never used.</p>
<p>
*** POTENTIAL INCOMPATIBILITY ***</p>
<p>
Own Id: OTP-10417</p>
</item>
<item>
<p>
release_handler:upgrade_script and
release_handler:downgrade_script could not read appup
files with regexps. This has been corrected. (Thanks to
Ulf Wiger)</p>
<p>
Own Id: OTP-10463</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>Where necessary a comment stating encoding has been
added to Erlang files. The comment is meant to be removed
in Erlang/OTP R17B when UTF-8 becomes the default
encoding. </p>
<p>
Own Id: OTP-10630</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.2.1</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
If sys.config existed, but was not readable or parseable,
this would not be detected until after the upgrade and at
the next node restart. The possibility for this to happen
is now reduced by adding a check to systools:make_tar
which fails the creation of the tar file if sys.config or
relup does not have reasonable contents. Note that there
are no detailed checks, only parsing and erlang term
format check.</p>
<p>
Own Id: OTP-9539</p>
</item>
<item>
<p>
systools:make_script would allow {kernel,Vsn,load} in the
.rel file, causing a .boot file which only loaded kernel
and did not start it. This has been corrected. Only start
type 'permanent', which is the default, is now allowed
for kernel and stdlib.</p>
<p>
Own Id: OTP-9652</p>
</item>
<item>
<p>
release_handler:remove_release/1 now handles symlinked
files properly</p>
<p>
Own Id: OTP-9864</p>
</item>
<item>
<p>
If stdlib was stated with a start type different from
<c>permanent</c> in a .rel file, systools would
incorrectly say that sasl had faulty start type. This has
been corrected.</p>
<p>
Own Id: OTP-9888</p>
</item>
<item>
<p>
Sasl documentation earlier said that the InclApps
parameters in a .rel file defaults to the empty list.
This is not correct. It defaults to the same value as
specified in the .app file. This has been corrected.</p>
<p>
Own Id: OTP-9980</p>
</item>
<item>
<p>
Applications that are listed in
<c>{applications,Apps}</c> in the .app file were not
sorted correctly by <c>systools:make_script/1,2</c>. They
got the reverse order of how they were listed in the .app
file. This is corrected so they are now sorted
(internally between each other) in the same order as they
are listed in the .rel file (i.e. the order they are
listed in the .app file does no longer matter).</p>
<p>
*** POTENTIAL INCOMPATIBILITY ***</p>
<p>
Own Id: OTP-9984</p>
</item>
<item>
<p>
Documentation of .appup files now also states that
<c>UpFromVsn</c> and <c>DownToVsn</c> can be specified as
regular expressions in order to avoid duplicated upgrade
instructions.</p>
<p>
Own Id: OTP-10001</p>
</item>
<item>
<p>
Reltool would sometimes generate a .app file containing
<c>{start_phases,undefined}</c>, which would cause an
exception in systools at parse time. This has been
corrected so reltool now omits the <c>start_phases</c>
entry if the value is <c>undefined</c>. (Thanks to Juan
Jose Comellas)</p>
<p>
In order to align with reltool, sasl will also omit
<c>start_phases</c> entries with value <c>undefined</c>
in .script files.</p>
<p>
Own Id: OTP-10003</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.2</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Fix the mechanism for upgrading emulator.</p>
<p>
The appup files for kernel, stdlib and sasl do now
recognize two major releases back and include a
'restart_new_emulator' instruction. </p>
<p>
Appup files can include regular expressions for matching
earlier releases.</p>
<p>
The mechanism for upgrading the emulator is changed so
'restart_new_emulator' will be the first instruction
executed. The rest of the upgrade instruction will be
executed after the emulator restart.</p>
<p>
A new upgrade instruction 'restart_emulator' is added for
the case where the emulator shall be restarted after all
other upgrade instructions.</p>
<p>
*** POTENTIAL INCOMPATIBILITY ***</p>
<p>
Own Id: OTP-9438</p>
</item>
<item>
<p>
Add release_handler:which_releases/1</p>
<p>
This is an extension to which_releases that allows a user
to specify the status of the releases they wish to be
returned. For instance it allows for quickly determining
which release is 'permanent' without the need of parsing
the entire release list. (Thanks to Joe Williams)</p>
<p>
Own Id: OTP-9717</p>
</item>
<item>
<p>
Add copy of rel file in releases/Vsn in release tar file</p>
<p>
systool:make_tar stores the rel file in the releases
directory. When unpacking with
release_handler:unpack_release, the file is automatically
moved to releases/Vsn/. If, however, the tar file is
unpacked manually, the rel file might not be moved, and
the next release unpacked might overwrite the rel file.
To overcome this, systools:make_tar now stores a copy of
the rel file in releases/Vsn/ directly and it is not
longer necessary to move the file after unpacking.</p>
<p>
The reason for keeping the file in the releases directory
also is that is needs to be extracted separately before
the release version (Vsn) is known.</p>
<p>
Own Id: OTP-9746</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.10</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
The release_handler functionality on windows services was
broken. This has been corrected.</p>
<p>
Own Id: OTP-9306</p>
</item>
<item>
<p>
If a new version of an application did not include any
erlang module changes, the code path of the application
was not updated by the release_handler unless a
'load_object_code' instruction was added for the
application. This would be a problem if e.g. only some
files in the priv dir were changed since calls to
code:lib_dir or code:priv_dir would then point to the old
location of the application. This has been corrected -
now code:replace_path/2 will be called for all
applications that are changed (i.e. when the
application's vsn is changed in the .rel file).</p>
<p>
Own Id: OTP-9402</p>
</item>
<item>
<p>
The appup instruction 'delete_module' would cause a crash
during upgrade if the module to be deleted was not
loaded. This has been corrected.</p>
<p>
Own Id: OTP-9417</p>
</item>
<item>
<p>
If a path was given as ONLY 'ebin' and not for example
'./ebin', then systools:make_tar would fail with a
<c>function_clause</c> exception in filename:join/1. This
has been corrected. (Thanks to Nikola Skoric for
reporting).</p>
<p>
Own Id: OTP-9507</p>
</item>
<item>
<p>
Implement or fix -Werror option</p>
<p>
If -Werror is enabled and there are warnings no output
file is written. Also make sure that error/warning
reporting is consistent. (Thanks to Tuncer Ayaz)</p>
<p>
Own Id: OTP-9536</p>
</item>
<item>
<p>
Improved error information for timeouts during
release_handler:install_release.</p>
<p>
This patch addresses two cases where a timeout will occur
during upgrade. 1) if a supervisor is suspended (call to
get children from supervisor will hang) 2) if the child
spec for a supervisor incorrectly states that it is a
worker with a dynamic set of modules (call to get modules
from gen_event will hang)</p>
<p>
An error report will now be printed, and the return value
of release_handler:install_release will indicate what
happened. (Thanks to joe williams)</p>
<p>
Own Id: OTP-9546</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
<c>release_handler:install_release</c> could be very slow
when there are many processes in the system. Some
optimization work has been done both in erts and in the
release handler in order to improve this. </p>
<p>
A new option, <c>purge</c>, is added to
<c>release_handler:check_install_release</c> which can be
called first in order to speed up the execution of
<c>release_handler:install_release</c>.</p>
<p>
Own Id: OTP-9395</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.9.4</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>
Remove traces of release_handler reading from filesystem
when it has Masters list</p>
<p>
There are a couple of places in release_handler and
release_handler_1 that assumed it has a disk to read
from, which in the case of an erl_prim_loader Loader
other than efile is not necessarily true</p>
<p>
Add check_paths/2 to do the equivalent of check_path/1
for when there is a Masters list</p>
<p>
Change get_vsn to no longer get sent File paths but
instead use the Bin since beam_lib:version being sent a
file path causes it to read the local file system</p>
<p>
Add get_current_vsn/1 as an equivalent to
beam_lib:version(code:which(Mod)), but using
erl_prim_loader:get_file instead of reading from local
file system</p>
<p>
(Thanks to Steven Gravell)</p>
<p>
Own Id: OTP-9142</p>
</item>
<item>
<p>
rb:stop did sometimes return {error,running}. This came
from supervisor:delete_child and happened when the
rb_server has not yet terminated when this function was
called. Instead of having a separate gen_server call to
rb_server for stopping the process,
supervisor:terminate_child is now called. This is a
synchronous function - i.e. it waits for the process to
actually terminate before it returns.</p>
<p>
A file descriptor leak in rb:scan_files is corrected. The
index file was never closed after reading.</p>
<p>
A mismatch in the behavior of rb:filter, when filter
included 'no', is corrected. Such filters will now return
*all* non-matching reports, not only the 'proplist'
reports.</p>
<p>
Own Id: OTP-9149</p>
</item>
<item>
<p>
Start and end date for rb:filter/2 was specified as
{{Y-M-D},...} in the help text instead of {{Y,M,D},...}.
This has been corrected.</p>
<p>
Own Id: OTP-9166</p>
</item>
<item>
<p>
If some, but not all, of the sasl environment variables
related to the log_mf_h error handler were missing sasl
would successfully start but silently skip starting
log_mf_h. This is corrected so sasl startup will now fail
if one or two of the three variables are given. If none
of the variables are given, sasl will start as before
without starting log_mf_h.</p>
<p>
Own Id: OTP-9185</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Change default behaviour to not check src code when
creating release</p>
<p>
Add new option <c>src_tests</c> to systools:make_script
and systools:make_tar. The old option
<c>no_module_tests</c> is now ignored as this is the
default behaviour.</p>
<p>
*** POTENTIAL INCOMPATIBILITY ***</p>
<p>
Own Id: OTP-9146 Aux Id: seq11803 </p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.9.3</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Honor start type in .rel files when building relup files</p>
<p>
Previously, relup file always included an
application:start(Application, permanent) apply
instruction for every application that appear in the
UpTo/DowFrom release file, whatever their start type in
the release file.</p>
<p>
The new implementation fixes this bug by honoring the
start type according to the rel(5) format. If the start
type is none, no apply line is included in the relup. If
the start type is load, the relup includes instruction to
only load the application. Otherwise, the relup includes
an instruction to start the application to the according
type.</p>
<p>
The fix is implemented by adding a new parameter to the
add_application high level appup instruction. This new
parameter is documented in appup(5).</p>
<p>
Own Id: OTP-9097</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.9.2</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>In R13B04 sys:get_status was modified to invoke
format_status/2 in the callback module if the module
exports that function. This resulted in a change to the
term returned from calling sys:get_status on the
supervisor module, since supervisor is a gen_server and
gen_server exports format_status. The sasl
release_handler_1 module had a dependency on the
pre-R13B04 term returned by sys:get_status when invoked
on a supervisor, so the R13B04 change broke that
dependency.</p>
<p>This problem has been fixed by change
release_handler_1 to handle both the pre-R13B04 and
R13B04 terms that sys:get_status can return from a
supervisor.</p>
<p>
Own Id: OTP-8619 Aux Id: seq11570 </p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.9.1</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>Use an infinity timeout in all calls to
<c>gen_server:call()</c> in the <c>sasl</c>
application.</p>
<p>
Own Id: OTP-8506 Aux Id: seq11509 </p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.9</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
The <c>re:grep/1</c> function now uses the '<c>re</c>'
module instead of the deprecated '<c>regexp</c>' module.
There are new functions <c>rb:filter/1</c> and
<c>rb:filter/2</c> for easier filtering of reports.
(Thanks to Alvaro Videla.)</p>
<p>
Own Id: OTP-8443</p>
</item>
<item>
<p>
There is new function <c>sasl_report:format_report/3</c>
that works like the existing
<c>sasl_report:write_report/3</c> function except that it
returns a formatted string. Note that there is currently
no documentation for the <c>sasl_report</c> module.
(Thanks to Jay Nelson.)</p>
<p>
Own Id: OTP-8445</p>
</item>
<item>
<p>
Cleanups suggested by tidier and modernization of types
and specs.</p>
<p>
Own Id: OTP-8455</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.8</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
The documentation is now built with open source tools
(xsltproc and fop) that exists on most platforms. One
visible change is that the frames are removed.</p>
<p>
Own Id: OTP-8201</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.7</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
The Windows utility Erlsrv, run in interactive mode now
accepts options for registering internal service name and
description field of Windows registry database.</p>
<p>
Own Id: OTP-8132</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.6</title>
<section><title>Fixed Bugs and Malfunctions</title>
<list>
<item>
<p>When using the SASL application configuration
parameter <c>masters</c> the error tuple
<c>{error,{no_such_file,{Master,FileName}}}</c> was
sometimes returned even though the file <c>FileName</c>
existed.</p>
<p>
Own Id: OTP-7667</p>
</item>
</list>
</section>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Missing preloaded modules added</p>
<p>
Own Id: OTP-7820</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.5.4</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
A Dialyzer warning was eliminated</p>
<p>
Own Id: OTP-7635</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.5.3</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Minor changes.</p>
<p>
Own Id: OTP-7388</p>
</item>
</list>
</section>
</section>
<section><title>SASL 2.1.5.2</title>
<section><title>Improvements and New Features</title>
<list>
<item>
<p>
Minor updates.</p>
<p>
Own Id: OTP-6998</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.5.1</title>
<section>
<title>Improvements and New Features</title>
<list type="bulleted">
<item>
<p>Minor Makefile changes.</p>
<p>Own Id: OTP-6689</p>
</item>
<item>
<p>Obsolete guard tests (such as list()) have been replaced
with the modern guard tests (such as is_list()).</p>
<p>Own Id: OTP-6725</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.5</title>
<section>
<title>Fixed Bugs and Malfunctions</title>
<list type="bulleted">
<item>
<p>Removed some dead code from <c>erlsrv:get_service/2</c>,
<c>release_handler:do_write_file/2</c>,
<c>systools_relup:foreach_baserel_up/7</c> and
<c>systools_relup:foreach_baserel_dn/7</c>.</p>
<p>Own Id: OTP-6499</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.4</title>
<section>
<title>Improvements and New Features</title>
<list type="bulleted">
<item>
<p>Added an option <c>{outdir,Dir}</c> to the functions in
<c>systools</c>, making it possible to specify in which
directory a boot script, relup file or release package
file should be placed.</p>
<p>Also, when using <c>systools:make_tar/2</c> to create a
release package file, the boot script, relup file and
<c>sys.config</c> are now searched for also in the current
working directory and any directory specified by
the <c>path</c> option, not only in the directory of
the <c>.rel</c> file.</p>
<p>As part of the work some minor bugs have been corrected:</p>
<list type="bulleted">
<item>
<p><c>systools:make_script/1,2</c> now returns
<c>error</c> if the <c>.script</c> and/or <c>.boot</c>
file could not be opened for writing, not <c>ok</c>.</p>
</item>
<item>
<p><c>systools:make_tar/1,2</c> can now handle a
<c>RelName</c> argument which includes a path.
Previously this would cause the <c>.rel</c> file to end
up in the wrong directory in the resulting tar file.</p>
</item>
<item>
<p>A documentation error for <c>systools:make_tar/1,2</c>:
The <c>.rel</c> file is placed in the <c>releases</c>
directory in the tar file, not <c>releases/RelVsn</c>.</p>
</item>
</list>
<p>Own Id: OTP-6226</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.3</title>
<section>
<title>Fixed Bugs and Malfunctions</title>
<list type="bulleted">
<item>
<p><c>release_handler:upgrade_app/2</c> and
<c>release_handler:downgrade_app/2,3</c> -- used for
testing application upgrade and downgrade according to
the <c>.appup</c> file -- now update application
configuration parameters correctly. (Thanks to Serge
Aleynikov)</p>
<p>Own Id: OTP-6162</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.2</title>
<section>
<title>Fixed Bugs and Malfunctions</title>
<list type="bulleted">
<item>
<p>Fixed some minor bugs in <c>release_handler</c> found by
Dialyzer.</p>
<p>Own Id: OTP-6039</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1.1</title>
<section>
<title>Improvements and New Features</title>
<list type="bulleted">
<item>
<p>Added a number of functions to <c>release_handler</c> which
makes it possible to test upgrade and downgrade of
applications according to an <c>.appup</c> file "on the
fly": <br></br>
- <c>upgrade_app/2</c> <br></br>
- <c>upgrade_script/2</c> <br></br>
- <c>downgrade_app/2,3</c> <br></br>
- <c>downgrade_script/3</c> <br></br>
- <c>eval_appup_script/4</c></p>
<p>Own Id: OTP-5858</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.1</title>
<section>
<title>Improvements and New Features</title>
<list type="bulleted">
<item>
<p>A new option <c>{update_paths,Bool}</c> has been added
for <c>release_handler:install_release/2</c>. It
indicates if all application code paths should be updated
(<c>Bool==true</c>), or if only code paths for modified
applications should be updated (<c>Bool==false</c>,
default).</p>
<p><c>release_handler:set_unpacked/2</c> now returns an
error tuple if a specified application directory does not
exist.</p>
<p>*** POTENTIAL INCOMPATIBILITY ***</p>
<p>Own Id: OTP-5761</p>
</item>
</list>
</section>
</section>
<section>
<title>SASL 2.0.1</title>
<section>
<title>Improvements and New Features</title>
<list type="bulleted">
<item>
<p>A bug that made it impossible to call <c>rb:show(N)</c>
(<c>N</c> being an integer) twice without getting an error
has been fixed.</p>
<p>Own Id: OTP-5287</p>
</item>
</list>
</section>
</section>
</chapter>
