This module contains functions to generate boot scripts
(.boot
, .script
), release upgrade scripts
(relup
), and release packages.
make_relup(Name, UpFromNames, DownToNames) -> Result
make_relup(Name, UpFromNames, DownToNames, Opts) -> Result
Types:
Name = string()
UpFromNames = DownToNames = [Name | {Name,Description}]
Description = term()
Opts = [Opt]
Opt = {path,Path} | restart_emulator | silent
| noexec
Path = [Dir]
Dir = string()
Result = ok | error
| {ok,Relup,Module,Warnings} | {error,Module,Error}
Relup - see relup(4)
Module = atom()
Warnings = Error = term()
Generates a release upgrade file relup
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
release_handler
when installing a new version of a
release in run-time.
The function compares the release resource file
Name.rel
with all release resource files
Name2.rel
specified in UpFromNames
and
DownToNames
. For each such pair, it is deducted:
Name.rel
but not in
Name2.rel
.
Name2.rel
but not in
Name.rel
.
Name.rel
and
Name2.rel
, but with different versions.
Instructions for this are added to the relup
script in
the above order. Instructions for upgrading/downgrading
between application versions are fetched from the relevant
application upgrade files Application.appup
, sorted in
the same order as when generating a boot script, see
make_script/1,2
. High-level instructions are translated
into low-level instructions and the result is printed to
relup
in the current working directory.
The optional Description
parameter is included as-is
in the relup
script, see relup(4)
. Defaults to
the empty list.
All the files are searched for in the code path. It is
assumed that the app
and appup
file for an
application is located in the same directory.
If the option {path,Path}
is provided, Path
is
appended to the code path. A directory in the path can be
given with a wildcard *
, this is expanded to all
matching directories.
If the restart_emulator
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.
By default, errors and warnings are printed to tty and
the function returns ok
or error
. If the option
silent
is provided, the function instead returns
{ok,Relup,Module,Warnings}
where Relup
is
the release upgrade script, or it returns
{error,Module,Error}
. Warnings and errors can be
converted to strings by calling
Module:format_warning(Warnings)
or
Module:format_error(Error)
.
If the option noexec
is provided, the function returns
the same values as for silent
but no relup
file
is created.
make_script(Name) -> Result
make_script(Name, Opts) -> Result
Types:
Name = string()
Opts = [Opt]
Opt = no_module_tests | {path,Path} |
| local | {variables,[Var]}
| exref | {exref,[Application]}]
| silent
Path = [Dir]
Dir = string()
Var = {VarName,PrefixDir}
VarName = PrefixDir = string()
Application = atom()
Result = ok | error
| {ok,Module,Warnings} | {error,Module,Error}
Module = atom()
Warnings = Error = term()
Generates a boot script Name.script
and a binary
version Name.boot
, specifying which code should be
loaded and which applications should be started when
the Erlang runtime system is started.
The function checks the contents of the release resource file
Name.rel
to find out which applications are included in
the release. It then checks the relevant application resource
files Application.app
for the values of
the modules
and mod
keys, see app(4)
,
to find out which modules should be loaded and if and how
the application should be started.
The correctness of each application is checked:
no_module_tests
option is specified, this
check is omitted.The applications are sorted according to the dependencies
between the applications. Where there are no dependencies,
the order in the release resource file is kept. The result is
printed to Name.script
and Name.boot
in
the current working directory (or to the directory where
Name.rel
is located, if Name
contains a path).
All the files are searched for in the code path. It is
assumed that the .app
and .beam
files for an
application is located in the same directory. The .erl
files are also assumed to be located in this directory, unless
it ends with ebin
in which case they are assumed to be
in the corresponding src
directory.
If the option {path,Path}
is provided, Path
is
appended to the code path. A directory in the path can be
given with a wildcard *
, this is expanded to all
matching directories.
In the generated boot script all applications are assumed to
be located in $ROOT/lib
, where $ROOT
is the root
directory of the installed release. If the local
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.
The variables
option can be used to specify an
installation directory other than $ROOT/lib
for some of
the applications. This is easiest illustrated using an
example:
If the option {variables,[{"TEST","/test/lib"}]}
is
supplied, all applications found underneath /test/lib
will get the path $TEST
in the generated boot script.
When starting the system with the generated boot script,
the TEST
variable is given a value using
the -boot_var Var Dir
command line flag (see
erl(1)
).
The checks performed before the boot script is generated can
be extended with some cross reference checks by specifying
the exref
option. These checks are performed with
the Xref tool. All applications, or the applications specified
with {exref,[Application]}
, are checked by Xref and
warnings are generated for calls to undefined functions.
By default, errors and warnings are printed to tty and
the function returns ok
or error
. If the option
silent
is provided, the function instead returns
{ok,Module,Warnings}
or {error,Module,Error}
.
Warnings and errors can be converted to strings by calling
Module:format_warning(Warnings)
or
Module:format_error(Error)
.
make_tar(Name) -> Result
make_tar(Name, Opts) -> Result
Types:
Name = string()
Opts = [Opt]
Opt = {path,Path} | silent | {dirs,Dirs}
| {erts,ErtsDir} | no_module_tests | {variables,Vars}
| {var_tar,VarTar} | {machine,Machine} | exref
| {exref,[AppName]}
Path = [Dir]
Dir = string()
Dirs = [atom()]
ErtsDir = string()
Vars = [Var]
Var = {VarName,PreFixDir}
VarName = atom() | string()
PreFixDir = string()
VarTar = include | ownfile | omit
Machine = atom()
AppName = atom()
Result = ok | error
| {ok,Module,Warnings} | {error,Module,Error}
Module = atom()
Warning = Error = term()
A release package file is generated from the Name.rel
file. The Name.tar.gz
file is generated. This file
must be uncompressed and unpacked on the target system before
the new release can be activated, using
the release_handler
.
By default, the generated release package contains a
directory under the lib
directory for each included
application. Each application directory is named
ApplicationName-ApplicationVsn
. For each application,
the ebin
and priv
directories are included.
These directories are copied from where the applications were
found. If more directories are needed, it is possible to
specify these with the {dirs,Dirs}
option. For example,
if the src and example directories should be included for
each application in the release package,
the {dirs,[src,examples]}
option should be supplied.
The variables
option can be used to specify an
installation directory other than the Erlang installation
directory for the user provided applications. If the option
{variables,[{"TEST","/home/xxx/applications"}]}
is
supplied, all applications found underneath this directory
will be packed into the TEST.tar.gz
file. Accordingly,
a separate package is created for each defined variable.
By default, all these files are included at the top level in
the ReleaseName.tar.gz
file and should be unpacked to
an appropriate installation directory.
The {var_tar,VarTar}
option can be used to specify if
and where a separate package should be stored. In this option,
VarTar
is:
include
. Each separate (variable) package
is included in the main ReleaseName.tar.gz
file. This is the default.ownfile
. Each separate (variable) package
is generated as separate files in the same directory as
the ReleaseName.tar.gz
file.omit
. No separate (variable) packages are
generated and applications which are found underneath a
variable directory are ignored.The normal code server path is searched for the release
file ReleaseName.rel
and the application files
(ApplicationName.app
). The code server path can be
appended with a path specified with the {path, Path}
option. Path
can contain wildcards (*) as described
for the make_script
function.
The machine
option can be used to generate a release
package file for an Erlang machine other than the running
machine. This ensures that object code files with the
expected file extension are included in the package, for
example .beam
files.
A directory called releases/RelVsn
is also included
in the release package. The release version RelVsn
is
found in the release package. This directory contains the
boot script (ReleaseName.boot
copied to
start.boot
), the relup
file (generated by
make_relup
), and the system configuration file
(sys.config
).
If the release package shall contain a new Erlang runtime
system, the bin
directory of the specified
({erts,ErtsDir}
) runtime system is copied to
erts-ErtsVsn/bin
.
Finally, the releases
directory contains the
ReleaseName.rel
file.
All checks performed with the make_script
function
are performed before the release package is created. The
no_module_tests
and exref
options are also
valid here.
The return value TarRet
and the handling of errors
and warnings are as described for the make_script
function above.
script2boot(File) -> ok | error
Types:
File = string()
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 File.script
boot script to a
binary term which is stored in the file File.boot
.
A boot script generated using the make_script
function is already transformed to the binary form.
app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), script(4)