systools(3erl)
NAME
systools - A Set of Release Handling Tools
DESCRIPTION
This module contains functions to generate boot scripts (.boot, .script), a release upgrade file (relup), and release packages.
EXPORTS
make_relup(Name, UpFrom, DownTo) -> Result
make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
Types:
Name = string()
UpFrom = DownTo = [Name | {Name,Descr}]
Descr = term()
Opt = {path,[Dir]} | restart_emulator | silent | noexec |
{outdir,Dir} | warnings_as_errors
Dir = string()
Result = ok | error | {ok,Relup,Module,Warnings} |
{error,Module,Error}
Relup, see relup(5)
Module = atom()
Warnings = Error = term()
Generates a release upgrade file relup containing instructions
for upgrading from or downgrading to one or more previous
releases. The instructions are used by release_handler when
installing a new version of a release in runtime.
By default, relup file is located in the current working
directory. If option {outdir,Dir} is specified, the relup file
is located in Dir instead.
The release resource file Name.rel is compared with all release
resource files Name2.rel, specified in UpFrom and DownTo. For
each such pair, the following is deducted:
* Which applications to be deleted, that is, applications
listed in Name.rel but not in Name2.rel
* Which applications to be added, that is, applications listed
in Name2.rel but not in Name.rel
* Which applications to be upgraded/downgraded, that is,
applications listed in both Name.rel and Name2.rel but with
different versions
* If the emulator needs to be restarted after upgrading or
downgrading, that is, if the ERTS version differs between
Name.rel and Name2.rel
Instructions for this are added to the relup file in the above
order. Instructions for upgrading or downgrading between
application versions are fetched from the relevant application
upgrade files App.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 the relup file.
The optional Descr parameter is included "as is" in the relup
file, see relup(5). Defaults to the empty list.
All the files are searched for in the code path. It is assumed
that the .app and .appup files for an application are located in
the same directory.
If option {path,[Dir]} is specified, this path is appended to
the current path. Wildcard * is expanded to all matching
directories, for example, lib/*/ebin.
If option restart_emulator is specified, a low-level instruction
to restart the emulator is appended to the relup file. This
ensures that a complete reboot of the system is done when the
system is upgraded or downgraded.
If an upgrade includes a change from an emulator earlier than
OTP R15 to OTP R15 or later, the warning
pre_R15_emulator_upgrade is issued. For more information about
this, see Design Principles in System Documentation.
By default, errors and warnings are printed to tty and the
function returns ok or error. If option silent is specified, the
function instead either returns {ok,Relup,Module,Warnings},
where Relup is the release upgrade file, or
{error,Module,Error}. Warnings and errors can be converted to
strings by calling Module:format_warning(Warnings) or
Module:format_error(Error).
If option noexec is specified, the function returns the same
values as for silent but no relup file is created.
If option warnings_as_errors is specified, warnings are treated
as errors.
make_script(Name) -> Result
make_script(Name, [Opt]) -> Result
Types:
Name = string()
Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} |
exref | {exref,[App]}] | silent | {outdir,Dir} |
no_dot_erlang | no_warn_sasl | warnings_as_errors
Dir = string()
Var = {VarName,Prefix}
VarName = Prefix = string()
App = atom()
Result = ok | error | {ok,Module,Warnings} |
{error,Module,Error}
Module = atom()
Warnings = Error = term()
Generates a boot script Name.script and its binary version, the
boot file Name.boot. The boot file specifies which code to be
loaded and which applications to be started when the Erlang
runtime system is started. See script(5).
The release resource file Name.rel is read to determine which
applications are included in the release. Then the relevant
application resource files App.app are read to determine which
modules to be loaded, and if and how the applications are to be
started. (Keys modules and mod, see app(5).
By default, the boot script and boot file are located in the
same directory as Name.rel. That is, in the current working
directory unless Name contains a path. If option {outdir,Dir} is
specified, they are located in Dir instead.
The correctness of each application is checked as follows:
* The version of an application specified in the .rel file is
to be the same as the version specified in the .app file.
* There are to be no undefined applications, that is,
dependencies to applications that are not included in the
release. (Key applications in the .app file).
* There are to be no circular dependencies among the
applications.
* There are to be no duplicated modules, that is, modules with
the same name but belonging to different applications.
* If option src_tests is specified, a warning is issued if the
source code for a module is missing or is newer than the
object code.
The applications are sorted according to the dependencies
between the applications. Where there are no dependencies, the
order in the .rel file is kept.
The function fails if the mandatory applications Kernel and
STDLIB are not included in the .rel file and have start type
permanent (which is default).
If SASL is not included as an application in the .rel file, a
warning is issued because such a release cannot be used in an
upgrade. To turn off this warning, add option no_warn_sasl.
All files are searched for in the current path. It is assumed
that the .app and .beam files for an application are located in
the same directory. The .erl files are also assumed to be
located in this directory, unless it is an ebin directory in
which case they can be located in the corresponding src
directory.
If option {path,[Dir]} is specified, this path is appended to
the current path. A directory in the path can be specified with
a wildcard *, this is expanded to all matching directories.
Example: "lib/*/ebin".
In the generated boot script all application directories are
structured as App-Vsn/ebin. They are assumed to be located in
$ROOT/lib, where $ROOT is the root directory of the installed
release. If option local 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.
Option variables can be used to specify an installation
directory other than $ROOT/lib for some of the applications. If
a variable {VarName,Prefix} is specified and an application is
found in a directory Prefix/Rest/App[-Vsn]/ebin, this
application gets the path VarName/Rest/App-Vsn/ebin in the boot
script. If an application is found in a directory Prefix/Rest,
the path is VarName/Rest/App-Vsn/ebin. When starting Erlang, all
variables VarName are given values using command-line flag
boot_var.
Example: If option {variables,[{"TEST","lib"}]} is specified and
myapp.app is found in lib/myapp/ebin, the path to this
application in the boot script is "$TEST/myapp-1/ebin". If
myapp.app is found in lib/test, the path is
$TEST/test/myapp-1/ebin.
The checks performed before the boot script is generated can be
extended with some cross reference checks by specifying option
exref. These checks are performed with the Xref tool. All
applications, or the applications specified with {exref,[App]},
are checked by Xref and warnings are issued for calls to
undefined functions.
By default, errors and warnings are printed to tty and the
function returns ok or error. If option silent is specified, 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).
If option warnings_as_errors is specified, warnings are treated
as errors.
If option no_dot_erlang is specified, the instruction to load
the .erlang file during boot is not included.
make_tar(Name) -> Result
make_tar(Name, [Opt]) -> Result
Types:
Name = string()
Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} |
{var_tar,VarTar} | {erts,Dir} | src_tests | exref |
{exref,[App]} | silent | {outdir,Dir}
Dir = string()
IncDir = src | include | atom()
Var = {VarName,PreFix}
VarName = Prefix = string()
VarTar = include | ownfile | omit
Machine = atom()
App = atom()
Result = ok | error | {ok,Module,Warnings} |
{error,Module,Error}
Module = atom()
Warning = Error = term()
Creates a release package file Name.tar.gz. This file must be
uncompressed and unpacked on the target system using
release_handler before the new release can be installed.
The release resource file Name.rel is read to determine which
applications are included in the release. Then the relevant
application resource files App.app are read to determine the
version and modules of each application (keys vsn and modules,
see app(5)).
By default, the release package file is located in the same
directory as Name.rel. That is, in the current working directory
unless Name contains a path. If option {outdir,Dir} is
specified, it is located in Dir instead.
By default, the release package contains the directories
lib/App-Vsn/ebin and lib/App-Vsn/priv for each included
application. If more directories are to be included, option dirs
is specified, for example, {dirs,[src,examples]}.
All these files are searched for in the current path. If option
{path,[Dir]} is specified, this path is appended to the current
path. Wildcard * is expanded to all matching directories.
Example: "lib/*/ebin".
Option variables can be used to specify an installation
directory other than lib for some of the applications. If
variable {VarName,Prefix} is specified and an application is
found in directory Prefix/Rest/App[-Vsn]/ebin, this application
is packed into a separate VarName.tar.gz file as Rest/App-
Vsn/ebin.
Example: If option {variables,[{"TEST","lib"}]} is specified and
myapp.app is located in lib/myapp-1/ebin, application myapp is
included in TEST.tar.gz:
% tar tf TEST.tar
myapp-1/ebin/myapp.app
...
Option {var_tar,VarTar} can be used to specify if and where a
separate package is to be stored. In this option VarTar is one
of the following:
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 a separate
file in the same directory as the ReleaseName.tar.gz file.
omit:
No separate (variable) packages are generated. Applications
that are found underneath a variable directory are ignored.
A directory releases is also included in the release package,
containing Name.rel and a subdirectory RelVsn. RelVsn is the
release version as specified in Name.rel.
releases/RelVsn contains the boot script Name.boot renamed to
start.boot and, if found, the files relup and sys.config. These
files are searched for in the same directory as Name.rel, in the
current working directory, and in any directories specified
using option path.
If the release package is to contain a new Erlang runtime
system, the bin directory of the specified runtime system
{erts,Dir} is copied to erts-ErtsVsn/bin.
All checks with function make_script are performed before the
release package is created. Options src_tests and exref are also
valid here.
The return value and the handling of errors and warnings are the
same as described for make_script.
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.boot file.
A boot script generated using make_script is already transformed
to the binary form.
SEE ALSO
app(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
