reltool

v1.0.2-rc0

Reltool Release Notes

This document describes the changes made to the Reltool system from version to version. The intention of this document is to list all incompatibilities as well as all enhancements and bugfixes for every release of Reltool. Each release of Reltool thus constitutes one section in this document. The title of each section is the version number of Reltool.

Reltool 1.0.2

Improvements and New Features

The license and copyright header has changed format to include an SPDX-License-Identifier. At the same time, most files have been updated to follow a uniform standard for license headers.

Own Id: OTP-19575 Aux Id: PR-9670

Reltool 1.0.1

Fixed Bugs and Malfunctions

The dependencies for this application are now listed in the app file.

Own Id: OTP-18831 Aux Id: PR-7441

Improvements and New Features

The documentation has been migrated to use Markdown and ExDoc.

Own Id: OTP-18955 Aux Id: PR-8026

Reltool 1.0

Improvements and New Features

Add possibility to strip specific chunks from beam files included in a release. Before this change it was only possible to strip all chunks from the beam files.

Own Id: OTP-18230 Aux Id: PR-5936

Runtime dependencies have been updated.

Own Id: OTP-18350

Support for the experimental code archives feature has been removed from reltool.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-18488 Aux Id: PR-6836

The implementation has been fixed to use proc_lib:init_fail/2,3 where appropriate, instead of proc_lib:init_ack/1,2.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-18490 Aux Id: OTP-18471, GH-6339, PR-6843

Reltool 0.9.1.1

Fixed Bugs and Malfunctions

Fixed runtime dependencies.

Own Id: OTP-19064

Reltool 0.9.1

Fixed Bugs and Malfunctions

Fixed a bug that would cause analysis to crash.

Own Id: OTP-18372 Aux Id: GH-6580

Reltool 0.9

Improvements and New Features

Recognize new key 'optional_applications' in application resource files.

Own Id: OTP-17189 Aux Id: PR-2675

Removed timestamps from files generated by sasl and reltool to enable deterministic builds.

Own Id: OTP-17292 Aux Id: PR-4685, PR-4684

Reltool 0.8

Improvements and New Features

A new element, Opts, can now be included in a rel tuple in the reltool release specific configuration format: {rel, Name, Vsn, RelApps, Opts}.

This supports the use of {rel, Name, Vsn, RelApps, [{load_dot_erlang, false}]} to prevent the boot script from running the .erlang file.

The incompatibilities are as follows:

* The return from reltool:get_config/1 and reltool:get_config/3 includes the new rel tuple for all releases where the load_dot_erlang option is set to false.
* The return from reltool:get_config/3 includes the new rel tuple for ALL releases if the InclDefs parameter is set to true.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-15571

Reltool 0.7.8

Fixed Bugs and Malfunctions

Reltool would earlier erroneously split paths like "c:\foo" into ["c","\foo"] when reading the $ERL_LIBS variable on windows. This is now corrected.

Own Id: OTP-15454

Reltool 0.7.7

Fixed Bugs and Malfunctions

Improved documentation.

Own Id: OTP-15190

Reltool 0.7.6

Improvements and New Features

Calls to erlang:get_stacktrace() are removed.

Own Id: OTP-14861

Reltool 0.7.5

Improvements and New Features

Files generated by release_handler and reltool, which might contain Unicode characters, are now encoded as UTF-8 and written with format "~tp" or "~ts". If the file is to be read by file:consult/1, an encoding comment is added.

Own Id: OTP-14463

Reltool 0.7.4

Improvements and New Features

The User's Guide examples are updated after removal of support for Dets files created with Erlang/OTP R7 and earlier.

Own Id: OTP-14422 Aux Id: OTP-13830

Reltool 0.7.3

Fixed Bugs and Malfunctions

Fixed xml issues in old release notes

Own Id: OTP-14269

Reltool 0.7.2

Fixed Bugs and Malfunctions

Dependencies specified in .app files would earlier only be followed for applications that are included in a 'rel' spec in the reltool config. For other applications, only xref would decide the dependencies.

Some dependency chains would even be missed for applications that are included in a 'rel' spec in the reltool config. E.g.

Application x has y as included application, and y in turn has z as included application. Then z is not included.

Application x has y in its 'applications' tag in the .app file, and y in turn has z as included application. Then z is not included.

These bugs are now corrected.

Own Id: OTP-11993

Reltool 0.7.1

Improvements and New Features

Modify the code as motivated by a change of the Erlang Parser (undefined is no longer automatically inserted to the type of record fields without an initializer).

Own Id: OTP-13033 Aux Id: OTP-12719

Reltool 0.7

Improvements and New Features

Change license text from Erlang Public License to Apache Public License v2

Own Id: OTP-12845

Reltool 0.6.6

Fixed Bugs and Malfunctions

Fixed a minor typo in an error message from reltool_server.

Own Id: OTP-11977

Reltool 0.6.5

Fixed Bugs and Malfunctions

When adding a regexp to a filter in reltool using {add,Regexp}, and the existing regexp was undefined, reltool would crash since it got an improper list. This has been corrected. (Thanks to Håkan Mattsson)

Own Id: OTP-11591

Adapted reltool test server to common test usage of tc_status. (Note that this code is not used by OTP daily test runs.) (Thanks to Håkan Mattsson)

Own Id: OTP-11592

Application upgrade (appup) files are corrected for the following applications:

asn1, common_test, compiler, crypto, debugger, dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, inets, observer, odbc, os_mon, otp_mibs, parsetools, percept, public_key, reltool, runtime_tools, ssh, syntax_tools, test_server, tools, typer, webtool, wx, xmerl

A new test utility for testing appup files is added to test_server. This is now used by most applications in OTP.

(Thanks to Tobias Schlager)

Own Id: OTP-11744

Reltool 0.6.4.1

Improvements and New Features

The encoding of the notes.xml file has been changed from latin1 to utf-8 to avoid future merge problems.

Own Id: OTP-11310

Reltool 0.6.4

Fixed Bugs and Malfunctions

Fix receive support in erl_eval with a BEAM module. Thanks to Anthony Ramine.

Own Id: OTP-11137

Improvements and New Features

Reltool used to fail if an application was mentioned in the config file which was not found in the file system, even if the application was explicitly excluded in the config. This has been changed and will only produce a warning. If the application is not explicitly excluded it will still cause reltool to fail. Thanks to Håkan Mattsson!

Own Id: OTP-10988

Fix possibly "not owner" error while file copy with reltool. Thanks to Alexey Saltanov.

Own Id: OTP-11099

Reltool 0.6.3

Improvements and New Features

Some updates are made to reltool for handling unicode.

Own Id: OTP-10781

Reltool 0.6.2

Fixed Bugs and Malfunctions

If incl_cond was set to derived on module level, then reltool_server would crash with a case_clause. This has been corrected. incl_cond on module level now overwrites mod_cond on app or sys level as described in the documentation.

If a rel spec in the reltool config does not contain all applications that are listed as {applications,Applications} in a .app file, then these applications are automatically added when creating the .rel file. For 'included_applications', the behaviour was not the same. I.e. if a rel spec in the reltool config did not contain all applications that are listed as {included_applications,InclApplications} in a .app file, then reltool would fail with reason "Undefined applications" when creating the .rel file. This has been corrected, so both applications and included_applications are now automatically added if not already in the rel spec.

The rel specification now dictates the order in which included and used applications (specified in the .app file as included_applications and applications respectively) are loaded/started by the boot file. If the applications are not specified in the rel spec, then the order from the .app file is used. This was a bug earlier reported on systools, and is now also implemented in reltool.

Instead of only looking at the directory name, reltool now first looks for a .app file in order to figure out the name of an application.

Own Id: OTP-10012 Aux Id: kunagi-171 [82]

Improvements and New Features

Some examples overflowing the width of PDF pages have been corrected.

Own Id: OTP-10665

Reltool 0.6.1

Improvements and New Features

A new sys level configuration parameter {excl_lib,otp_root} is added. When this is set, the target system will not contain anything from $OTPROOT. It will only contain a releases directory with rel, script and boot files, and a lib directory with applications found outside of $OTPROOT (i.e. "your own" applications).

Own Id: OTP-9743

Reltool 0.6

Fixed Bugs and Malfunctions

Miscellaneous corrections:

Start of reltool GUI would sometimes crash with a badmatch in reltool_sys_win:do_init. This has been corrected.

Minor corrections of documentation and type specifications of app() and mod() are done.

If a module name is duplicated in an app file reltool would return an error. This is now changed to a warning.

Reltool would earlier not necessarily keep the order of applications as listed in the rel specification in the configuration. This has been corrected.

Reltool would earlier set the default for included applications to an empty list if it was not set in the rel specification in the configuration. This was correct according to sasl/systools documentation, but not according to sasl/systools implementation. We decided to change the documentation and reltool to use the value of included_applications from the .app file as default instead of the empty list, since this seems more intuitive and since systools always has done the same.

The value of included applications in the rel specification in the configuration did not overwrite included_applications in the .app file if it was set to an empty list. This has been corrected.

Reltool would earlier add load instructions in the script/boot files for ALL modules in the ebin directory of an application even if mod_cond was set to app (include only modules listed in the .app file). This has been corrected.

Reltool would earlier add start instructions in the script/boot file for included applications. This has been corrected - included applications shall only be loaded since the including application is responsible for starting them.

Status bar now indicates that reltool is working (Processing libraries...) for all configuration changes, and when generating target system.

Title of dependencies column in app and mod window is changed from "Modules used by others" to "Modules using this".

Own Id: OTP-9792

Configuration changes via the GUI had a few bugs related to error handling, rollback and undo. A major re-write of the reltool_server has been done in order to align the way reltool_server updates and uses its state and tables for all different kinds of configuration change.

All configuration changes (except undo) now cause a re-read of the file system, meaning that if something has changed in the file system it will be reflected in the result of the configuration change.

When loading a new configuration file via the GUI, the old configuration is now completely scratched, and only the new is valid.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-9794

Some bug fixes related to the handling of escripts:

Reltool could not handle escripts with inlined applications. This has been corrected. Inlined applications will be visible in the GUI, but not possible to include/exclude separately.

Loading a config which contains an escript via the GUI menu did not produce the same result as when using the same configuration at reltool start. Paths, version and label could differ. This has been corrected.

Loading config with same escript (source) twice caused reltool to add same module twice. This has been corrected.

Loading config with same escript (inlined beam) twice caused reltool to fail saying module is included by two different applications. This has been corrected.

Loading config which in addition to an existing escript also adds another escript, for which the name sorts before the existing one, would cause reltool to fail saying "Application name clash". This has been corrected.

Own Id: OTP-9968

Reltool would sometimes generate a .app file containing {start_phases,undefined}, which would cause an exception in systools at parse time. This has been corrected so reltool now omits the start_phases entry if the value is undefined. (Thanks to Juan Jose Comellas)

In order to align with reltool, sasl will also omit start_phases entries with value undefined in .script files.

Own Id: OTP-10003

Improvements and New Features

A warning list is added to the sys window of the reltool GUI. This list will continuously show all warnings produced by the current configuration.

Own Id: OTP-9967

As a way of specifying one specific version of an application, the following configuration parameter is added on application level:

{lib_dir,Dir}, Dir = string()

This can be useful if the parent directory of the application directory is not suitable to use as a lib dir on system level.

Own Id: OTP-9977

Reltool 0.5.7.1

Improvements and New Features

Added recommendation about RootDir parameter to reltool:eval_target_spec/3.

Own Id: OTP-9742

Reltool 0.5.7

Fixed Bugs and Malfunctions

If a module was duplicated in the library directories visible to reltool, and the configuration did not point out which file to use, then reltool:start would always fail. A pop-up is added which asks if you want to continue with a safe and minimal configuration.

Own Id: OTP-9383

wx would sometimes crash due to an empty radiobox on the 'releases' tab of the system window. This radiobox is removed, and replaced by a listbox which will always contain at least kernel and stdlib applications.

Own Id: OTP-9384

Reltool 0.5.6

Fixed Bugs and Malfunctions

The system level option app_files is documented to allow the values keep | strip | all, but it only allowed keep. This is corrected.

Own Id: OTP-9135

Allow the same module name in multiple applications visible to reltool, as long as all but one of the applications/modules are explicitly excluded. (Thanks to Andrew Gopienko and Jay Nelson)

Own Id: OTP-9229

Reltool 0.5.5

Fixed Bugs and Malfunctions

The reltool module contained two seriously erroneous specs which caused bogus warnings when dialyzing reltool and some correct code of users. These were fixed (specs for start_link/1 and eval_server/3)

- Code cleanups and simplifications - Fix a bug in the calculation of circular dependencies - Eliminate two dialyzer warnings - Put files alphabetically

Own Id: OTP-9120

Reltool 0.5.4

Improvements and New Features

Added function zip:foldl/3 to iterate over zip archives.

Added functions to create and extract escripts. See escript:create/2 and escript:extract/2.

The undocumented function escript:foldl/3 has been removed. The same functionality can be achieved with the more flexible functions escript:extract/2 and zip:foldl/3.

Record fields has been annotated with type info. Source files as been adapted to fit within 80 chars and trailing whitespace has been removed.

Own Id: OTP-8521

A new escript, called reltool, has been introduced in order to simplify the usage of the reltool application from makefiles.

The handling of applications included in releases has been improved. Applications that are required to be started before other applications in a release are now automatically included in the release. The Kernel and STDLIB applications are always included as they are mandatory.

Applications that are (explicitly or implicitly) included in a release are now automatically included as if they were explicitly included with the incl_cond flag.

A new embedded_app_type option has been introduced. It is intended to be used for embedded systems where all included applications must be loaded from the boot script, as these systems does not utilize dynamic code loading. If embedded_app_typeis set to something else than undefined, all included applications will be included in both the release as well as in the boot script. If the profile is embedded the embedded_app_type option defaults to load.

A new function called reltool:get_status/1 has been introduced. It returns status about the configuration in the server.

The API functions that may take PidOrOptions as input and actually gets Options does now print out warnings.

The internal error handling has been improved. For example {error,Reason} is always returned in case of errors even when the server dies.

app and appup files has been added as well as a corresponding test suite.

Various cleanups has been made in the code and in the documentation.

Own Id: OTP-8590

Reltool 0.5.3

Improvements and New Features

Removed spurious documentation files.

Own Id: OTP-8057

Reltool 0.5.2

Improvements and New Features

The documentation is now built with open source tools (xsltproc and fop) that exists on most platforms. One visible change is that the HTML frames are removed.

Own Id: OTP-8254

Reltool 0.5.1

Fixed Bugs and Malfunctions

In the new release of Reltool (0.5) there is a severe bug that may cause your source files to be deleted. The bug is triggered when you generate a target system WITH archive files AND your library directories are given with absolute paths. (Library directories are given with the ERL_LIBS environment variable or with the lib_dirs configuration parameter.)

Own Id: OTP-8199

Reltool 0.5

Improvements and New Features

The tool is still experimental. Feedback is appreciated.

Major improvements of the target system generation has been performed. Now it is possible to generate a relocatable target system that does not need to be re-installed if it is moved to a new location. Archive files are automatically generated. A detailed specification of the target system can be generated without actually creating the target system. Relocatable escripts are put in the bin directory of the target system. etc. etc.

Some new functions has been introduced in the reltool module: start/1, start_link/1, get_config/3, get_target_spec/1 and eval_target_spec/3.

Some new configuration parameters has been introduced: profile, incl_sys_filters, excl_sys_filters, incl_app_filters, excl_app_filters, incl_archive_filters, excl_archive_filters, archive_opts, escript and relocatable.

Some parameters have been obsoleted and given new semantics: incl_erts_dirs (incl_sys_filters), excl_erts_dirs (excl_sys_filters), incl_app_dirs (incl_app_filters), excl_app_dirs (excl_app_filters) and escripts (escript).

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-7949

Known Bugs and Problems

The application is experimental. Feedback is appreciated.

Reltool 0.2.2

Fixed Bugs and Malfunctions

The tool crashed when rel, script and boot files were generated via the GUI. This has been fixed.

Own Id: OTP-7999

Reltool 0.2.1

Improvements and New Features

Minor GUI fixes

Own Id: OTP-7840

Reltool 0.2

Improvements and new features

This is the first (experimental) release of Reltool.

Known Bugs and Problems

The application is experimental.

Introduction

Reltool is a release management tool. It analyses a given Erlang/OTP installation and determines various dependencies between applications. The graphical frontend depicts the dependencies and enables interactive customization of a target system. The backend provides a batch interface for generation of customized target systems.

Scope and Purpose

This manual describes the Reltool application, as a component of the Erlang/Open Telecom Platform development environment. It is assumed that the reader is familiar with the Erlang Development Environment, which is described in a separate User's Guide.

Prerequisites

The following prerequisites are required for understanding the material in the Reltool User's Guide:

familiarity with Erlang/OTP system principles and Erlang/OTP design principles

The application requires Erlang/OTP release R13B02 or later.

About This Manual

In addition to this introductory chapter, the Reltool User's Guide contains the following chapters:

Chapter 2: "Usage" describes the architecture and typical usage of the application.

Chapter 3: "Examples" gives some usage examples

Where to Find More Information

Refer to the following documentation for more information about Reltool and about the Erlang/OTP development system:

the Reference Manual of Reltool

the Erlang/OTP System Principles

the Erlang/OTP Design Principles

Programming Erlang: Software for a Concurrent World (2007), Pragmatic Bookshelf, ISBN13: 9781934356005.

Usage

Overview

This document focuses on the graphical parts of the tool. The concepts are explained in the reference manual for the module reltool.

System window

The system window is started with the function reltool:start/1. At startup the tool will process all beam files and app files in order to find out dependencies between applications and their modules. Once all this information has been derived, it will be possible to explore the tool.

The system window consists of four main pages (tabs):

Libraries

System settings

Applications

Releases

Click on a name tag to display its page.

Libraries

On the library page it is possible to control which sources the tool will use. The page is organized as a tree which can be expanded and collapsed by clicking on the little symbol in the beginning of the expandable/collapsible lines.

The Root directory can be edited by selecting the line where the path of the root directory is displayed and clicking the right mouse button. Choose edit in the menu that pops up.

Library directories can be added, edited or deleted. This is done by selecting the line where the path to a library directory is displayed and clicking the right mouse button. Choose add, edit or delete in the menu that pops up. New library directories can also be added by selecting the line Library directories and clicking the right mouse button. Choose add in the menu that pops up.

Escript files can be added, edited or deleted. This is done by selecting the line where the path to an escript file is displayed and clicking the right mouse button. Choose add, edit or delete in the menu that pops up. New escripts can also be added by selecting the line Escript files and clicking the right mouse button. Choose add in the menu that pops up.

When libraries and escripts are expanded, the names of their contained applications will be displayed. Double click on an application name to launch an application window.

System settings

On the system settings page it is possible to control some global settings that are used as defaults for all applications. Set the Application inclusion policy to include to include all applications that are not explicitly excluded. See incl_cond (application inclusion) and mod_cond (module inclusion) in the reference manual for the module reltool for more info.

The system settings page is rather incomplete.

Applications

There are four categories of applications on the applications page. Included contains applications that are explicitly included. Excluded contains applications that are explicitly excluded. Derived contains applications that either are used directly by explicitly included applications or by other derived applications. Available contains the remaining applications.

Select one or more applications and click on a button directly below the application column to change application category. For example, select an available application and click on its tick button to move the application to the included category. Clicking on the tick symbol for included applications will move the application back to the available category. The tick is undone.

The symbols in front of the application names are intended to describe the status of the application. There are error and warning symbols to signalize that there is something which needs attention. The tick symbol means that the application is included or derived and no problem has been detected. The cross symbol means that the application is excluded or available and no problem has been detected. Applications with error symbols are listed first in each category and are followed by the warnings and the normal ones (ticks and crosses) at the end.

Double click on an application to launch its application window.

Releases

The releases page is incomplete and very experimental.

File menu

Display application dependency graph - Launches an application force graph window. All included and derived applications and their dependencies will be shown in a graph.

Display module dependency graph - Launch a module force graph window. All included and derived modules and their dependencies will be shown in a graph.

Reset configuration to default

Undo configuration (toggle)

Load configuration - Loads a new configuration from file.

Save configuration - Saves the current configuration to file. Normally, only the explicit configuration parameters with values that differ from their defaults are saved. But the configuration with or without default values and with or without derived values may also be saved.

Generate rel, script and boot files

Generate target system

Close - Close the system window and all its subwindows.

Dependencies between applications or modules displayed as a graph

The dependency graph windows are launched from the file menu in the system window. The graph depicts all included and derived applications/modules and their dependencies.

It is possible to perform some limited manipulations of the graph. Nodes can be moved, selected, locked or deleted. Move a single node or the entire graph by moving the mouse while the left mouse button is pressed. A node can be locked into a fix position by holding down the shift button when the left mouse button is released. Select several nodes by moving the mouse while the control key and the left mouse button are pressed. Selected nodes can be locked, unlocked or deleted by clicking on a suitable button.

The algorithm that is used to draw a graph with as few crossed links as possible is called force graph. A force graph consists of nodes and directed links between nodes. Each node is associated with a repulsive force that pushes nodes away from each other. This force can be adjusted with the left slider or with the mouse wheel. Each link is associated with an attractive force that pulls the nodes nearer to each other. This force can be adjusted with the right slider. If this force becomes too strong, the graph will be unstable. The third parameter that can be adjusted is the length of the links. It is adjusted with the middle slider.

The Freeze button starts/stops the redrawing of the graph. Reset moves the graph to the middle of the window and resets all graph settings to default, with the exception of deleted nodes.

Application window

The application window is started by double clicking on an application name. The application window consists of four pages (tabs):

Application settings

Modules

Application dependencies

Module dependencies

Click on a name tag to display its page.

Application settings

Select version of the application in the Source selection policy part of the page. By default the latest version of the application is selected, but it is possible to override this by explicitly selecting another version.

Note that in order for reltool to sort application versions and thereby be able to select the latest, it is required that the version id for the application consists of integers and dots only, for example 1, 2.0 or 3.17.1.

By default the Application inclusion policy on system level is used for all applications. Set the value to include if you want to explicitly include one particular application. Set it to exclude if you want to exclude the application despite that it is used by another (explicitly or implicitly) included application. derived means that the application automatically will be included if some other (explicitly or implicitly) included application uses it.

By default the Module inclusion policy on system level is used for all applications. Set it to derived if you only want actually used modules to be included. Set it to app if you, besides derived modules, also want the modules listed in the app file to be included. Set it to ebin if you, besides derived modules, also want the modules that exist as beam files in the ebin directory to be included. Set it to all if you want all modules to be included, that is the union of modules found in the ebin directory and listed in the app file.

The application settings page is rather incomplete.

Modules

There are four categories of modules on the modules page. Included contains modules that are explicitly included. Excluded contains modules that are explicitly excluded. Derived contains modules that either are used directly by explicitly included modules or by other derived modules. Available contains the remaining modules.

Select one or more modules and click on a button directly below the module column to change module category. For example, select an available module and click on its tick button to move the module to the included category. Clicking on the tick symbol for included modules will move the module back to the available category. The tick is undone.

The symbols in front of the module names are intended to describe the status of the module. There are error and and warning symbols to signalize that there is something that needs attention. The tick symbol means that the module is included or derived and no problem has been detected. The cross symbol means that the module is excluded or available and no problem has been detected. Modules with error symbols are listed first in each category and are followed by warnings and the normal ones (ticks and crosses) at the end.

Double click on a module to launch its module window.

Application dependencies

There are four categories of applications on the Application dependencies page. If the application is used by other applications, these are listed under Used by. If the application requires other applications be started before it can be started, these are listed under Required. These applications are listed in the applications part of the app file. If the application includes other applications, these are listed under Included. These applications are listed in the included_applications part of the app file. If the application uses other applications, these are listed under Uses.

Double click on an application name to launch an application window.

Module dependencies

There are two categories of modules on the Module dependencies page. If the module is used by other modules, these are listed under Modules using this. If the module uses other modules, these are listed under Used modules.

Double click on an module name to launch a module window.

Module window

The module window is started by double clicking on an module name. The module window consists initially of two pages (tabs):

Dependencies

Code

Click on a name tag to display its page.

Dependencies

There are two categories of modules on the Dependencies page. If the module is used by other modules, these are listed under Modules using this. If the module uses other modules, these are listed under Used modules.

Double click on an module name to launch a module window.

Code

On the Code page the Erlang source code is displayed. It is possible to search forwards and backwards for text in the module. Enter a regular expression in the Find field and press enter. It is also possible to go to a certain line in the module. The Back button can be used to go back to the previous position.

Put the marker on a function name and double click to go to the definition of the function. If the function is defined in another module, that module will be loaded and added to the page list.

Examples

Start and stop windows and servers

The main process in Reltool is the server. It can be used as it is or be used via the GUI frontend process. When the GUI is started, a server process will automatically be started. The GUI process is started with reltool:start/0, reltool:start/1 or reltool:start_link/1. The pid of its server can be obtained with reltool:get_server/1

Erlang/OTP 20 [erts-9.0] [source-c13b302] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10]
[hipe] [kernel-poll:false]
Eshell V9.0  (abort with ^G)
1>
1> {ok, Win} = reltool:start([]).
{ok,<0.36.01>}
2> {ok, Server} = reltool:get_server(Win).
{ok,<0.37.01>}
3> reltool:get_config(Server).
{ok,{sys,[]}}
4>
4> {ok, Server2} = reltool:start_server([]).
{ok,<0.6535.01>}
5> reltool:get_config(Server2).
{ok,{sys,[]}}
6> reltool:stop(Server2).
ok

Inspecting the configuration

Erlang/OTP 20 [erts-9.0] [source-c13b302] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10]
[hipe] [kernel-poll:false]
Eshell V9.0  (abort with ^G)
1>
1> Config = {sys, [{escript, "examples/display_args", [{incl_cond, include}]},
		   {app, inets, [{incl_cond, include}]},
		   {app, mnesia, [{incl_cond, exclude}]},
		   {app, ssl, [{incl_cond, exclude}]},
		   {app, runtime_tools, [{incl_cond, exclude}]},
		   {app, syntax_tools, [{incl_cond, exclude}]}]}.
{sys,[{escript,"examples/display_args",[{incl_cond,include}]},
      {app,inets,[{incl_cond,include}]},
      {app,mnesia,[{incl_cond,exclude}]},
      {app,ssl,[{incl_cond,exclude}]},
      {app,runtime_tools,[{incl_cond,exclude}]},
      {app,syntax_tools,[{incl_cond,exclude}]}]}
2>
2> {ok, Server} = reltool:start_server([Config]).
{ok,<0.66.0>}
3>
3> reltool:get_config(Server).
{ok,{sys,[{escript,"/usr/local/lib/erlang/lib/reltool-0.7.3/examples/display_args",
                   [{incl_cond,include}]},
          {app,inets,[{incl_cond,include}]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,syntax_tools,[{incl_cond,exclude}]}]}}
4>
4> reltool:get_config(Server, false, false).
{ok,{sys,[{escript,"/usr/local/lib/erlang/lib/reltool-0.7.3/examples/display_args",
                   [{incl_cond,include}]},
          {app,inets,[{incl_cond,include}]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,syntax_tools,[{incl_cond,exclude}]}]}}
5>
5> reltool:get_config(Server, true, false).
{ok,{sys,[{root_dir,"/usr/local/lib/erlang"},
          {lib_dirs,[]},
          {escript,"/usr/local/lib/erlang/lib/reltool-0.7.3/examples/display_args",
                   [{incl_cond,include}]},
          {mod_cond,all},
          {incl_cond,derived},
          {app,inets,
               [{incl_cond,include},{vsn,undefined},{lib_dir,undefined}]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,syntax_tools,[{incl_cond,exclude}]},
          {boot_rel,"start_clean"},
          {rel,"start_clean","1.0",[]},
          {rel,"start_sasl","1.0",[sasl]},
          {emu_name,"beam"},
          {relocatable,true},
          {profile,development},
          {incl_sys_filters,[".*"]},
          {excl_sys_filters,[]},
          {incl_app_filters,[".*"]},
          {excl_app_filters,[]},
          {rel_app_type,...},
          {...}|...]}}
6>
6> reltool:get_config(Server, true, true).
{ok,{sys,[{root_dir,"/usr/local/lib/erlang"},
          {lib_dirs,[]},
          {escript,"/usr/local/lib/erlang/lib/reltool-0.7.3/examples/display_args",
                   [{incl_cond,include}]},
          {mod_cond,all},
          {incl_cond,derived},
          {erts,[{app,erts,
                      [{vsn,"10.0"},
                       {lib_dir,"/usr/local/lib/erlang/lib/erts-10.0"},
                       {mod,erl_prim_loader,[]},
                       {mod,erl_tracer,[]},
                       {mod,erlang,[]},
                       {mod,erts_code_purger,[]},
                       {mod,erts_dirty_process_signal_handler,[]},
                       {mod,erts_internal,[]},
                       {mod,erts_literal_area_collector,[]},
                       {mod,init,[]},
                       {mod,erl_init,...},
                       {mod,...},
                       {...}|...]}]},
          {app,compiler,
               [{vsn,"7.0.4"},
                {lib_dir,"/usr/local/lib/erlang/lib/compiler-7.0.4"},
                {mod,beam_a,[]},
                {mod,beam_asm,[]},
                {mod,beam_block,[]},
                {mod,beam_bs,[]},
                {mod,beam_bsm,[]},
                {mod,beam_clean,[]},
                {mod,beam_dead,[]},
                {mod,beam_dict,[]},
                {mod,beam_disasm,[]},
                {mod,beam_except,[]},
                {mod,beam_flatten,...},
                {mod,...},
                {...}|...]},
          {app,crypto,
               [{vsn,"3.7.4"},
                {lib_dir,"/usr/local/lib/erlang/lib/crypto-3.7.4"},
                {mod,crypto,[]},
                {mod,crypto_ec_curves,[]}]},
          {app,hipe,
               [{vsn,"3.15.4"},
                {lib_dir,"/usr/local/lib/erlang/lib/hipe-3.15.4"},
                {mod,cerl_cconv,[]},
                {mod,cerl_closurean,[]},
                {mod,cerl_hipeify,[]},
                {mod,cerl_lib,[]},
                {mod,cerl_messagean,[]},
                {mod,cerl_pmatch,[]},
                {mod,cerl_prettypr,[]},
                {mod,cerl_to_icode,[]},
                {mod,cerl_typean,...},
                {mod,...},
                {...}|...]},
          {app,inets,
               [{incl_cond,include},
                {vsn,"6.3.9"},
                {lib_dir,"/usr/local/lib/erlang/lib/inets-6.3.9"},
                {mod,ftp,[]},
                {mod,ftp_progress,[]},
                {mod,ftp_response,[]},
                {mod,ftp_sup,[]},
                {mod,http_chunk,[]},
                {mod,http_request,[]},
                {mod,http_response,...},
                {mod,...},
                {...}|...]},
          {app,kernel,
               [{vsn,"5.2"},
                {lib_dir,"/usr/local/lib/erlang/lib/kernel-5.2"},
                {mod,application,[]},
                {mod,application_controller,[]},
                {mod,application_master,[]},
                {mod,application_starter,[]},
                {mod,auth,[]},
                {mod,code,[]},
                {mod,code_server,...},
                {mod,...},
                {...}|...]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,sasl,
               [{vsn,"3.0.3"},
                {lib_dir,"/usr/local/lib/erlang/lib/sasl-3.0.3"},
                {mod,alarm_handler,[]},
                {mod,erlsrv,[]},
                {mod,format_lib_supp,[]},
                {mod,misc_supp,...},
                {mod,...},
                {...}|...]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,stdlib,
               [{vsn,"3.3"},
                {lib_dir,"/usr/local/lib/erlang/lib/stdlib-3.3"},
                {mod,array,[]},
                {mod,base64,...},
                {mod,...},
                {...}|...]},
          {app,syntax_tools,[{incl_cond,exclude}]},
          {app,tools,
               [{vsn,"2.9.1"},{lib_dir,[...]},{mod,...},{...}|...]},
          {boot_rel,"start_clean"},
          {rel,"start_clean","1.0",[]},
          {rel,"start_sasl","1.0",[...]},
          {emu_name,"beam"},
          {relocatable,true},
          {profile,...},
          {...}|...]}}
7>
7> reltool:get_config([{sys, [{profile, embedded}]}], true, false).
{ok,{sys,[{root_dir,"/usr/local/lib/erlang"},
          {lib_dirs,[]},
          {mod_cond,all},
          {incl_cond,derived},
          {boot_rel,"start_clean"},
          {rel,"start_clean","1.0",[]},
          {rel,"start_sasl","1.0",[sasl]},
          {emu_name,"beam"},
          {relocatable,true},
          {profile,embedded},
          {incl_sys_filters,["^bin","^erts","^lib","^releases"]},
          {excl_sys_filters,["^bin/(erlc|dialyzer|typer)(|\\.exe)$",
                             "^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$",
                             "^erts.*/bin/.*(debug|pdb)"]},
          {incl_app_filters,["^ebin","^include","^priv"]},
          {excl_app_filters,[]},
          {rel_app_type,permanent},
          {embedded_app_type,load},
          {app_file,keep},
          {debug_info,keep}]}}
8>
8> reltool:get_config([{sys, [{profile, standalone}]}], true, false).
{ok,{sys,[{root_dir,"/usr/local/lib/erlang"},
          {lib_dirs,[]},
          {mod_cond,all},
          {incl_cond,derived},
          {boot_rel,"start_clean"},
          {rel,"start_clean","1.0",[]},
          {rel,"start_sasl","1.0",[sasl]},
          {emu_name,"beam"},
          {relocatable,true},
          {profile,standalone},
          {incl_sys_filters,["^bin/(erl|epmd)(|\\.exe|\\.ini)$",
                             "^bin/start(|_clean).boot$","^erts.*/bin","^lib$"]},
          {excl_sys_filters,["^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$",
                             "^erts.*/bin/(start|escript|to_erl|run_erl)(|\\.exe)$",
                             "^erts.*/bin/.*(debug|pdb)"]},
          {incl_app_filters,["^ebin","^priv"]},
          {excl_app_filters,["^ebin/.*\\.appup$"]},
          {rel_app_type,permanent},
          {app_file,keep},
          {debug_info,keep}]}}

Generate release and script files

Erlang/OTP 20 [erts-10.0] [source-c13b302] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10]
[hipe] [kernel-poll:false]
Eshell V10.0  (abort with ^G)
1>
1> {ok, Server} = reltool:start_server([{config,
                                         {sys,
                                          [{boot_rel, "NAME"},
                                           {rel, "NAME", "VSN",
                                            [sasl],
                                            [{load_dot_erlang, false}]}]}}]).
{ok,<0.1288.0>}
2>
2> reltool:get_config(Server).
{ok,{sys,[{boot_rel,"NAME"},
          {rel,"NAME","VSN",[sasl]}]}}
3>
3> reltool:get_rel(Server, "NAME").
{ok,{release,{"NAME","VSN"},
             {erts,"10.0"},
             [{kernel,"5.2"},{stdlib,"3.3"},{sasl,"3.0.3"}]}}
4>
4> reltool:get_script(Server, "NAME").
{ok,{script,{"NAME","VSN"},
            [{preLoaded,[erl_prim_loader,erl_tracer,erlang,
                         erts_code_purger,erts_dirty_process_signal_handler,
                         erts_internal,erts_literal_area_collector,init,erl_init,
                         prim_eval,prim_file,prim_inet,prim_zip,zlib]},
             {progress,preloaded},
             {path,["$ROOT/lib/kernel-5.2/ebin",
                    "$ROOT/lib/stdlib-3.3/ebin"]},
             {primLoad,[error_handler]},
             {kernel_load_completed},
             {progress,kernel_load_completed},
             {path,["$ROOT/lib/kernel-5.2/ebin"]},
             {primLoad,[application,application_controller,
                        application_master,application_starter,auth,code,
                        code_server,disk_log,disk_log_1,disk_log_server,
                        disk_log_sup,dist_ac,dist_util,erl_boot_server|...]},
             {path,["$ROOT/lib/stdlib-3.3/ebin"]},
             {primLoad,[array,base64,beam_lib,binary,c,calendar,dets,
                        dets_server,dets_sup,dets_utils,dets_v9,dict|...]},
             {path,["$ROOT/lib/sasl-3.0.3/ebin"]},
             {primLoad,[alarm_handler,erlsrv,format_lib_supp,misc_supp,
                        rb,rb_format_supp,release_handler,release_handler_1,sasl,
                        sasl_report|...]},
             {progress,modules_loaded},
             {path,["$ROOT/lib/kernel-5.2/ebin",
                    "$ROOT/lib/stdlib-3.3/ebin","$ROOT/lib/sasl-3.0.3/ebin"]},
             {kernelProcess,heart,{heart,start,[]}},
             {kernelProcess,error_logger,{error_logger,start_link,[]}},
             {kernelProcess,application_controller,
                            {application_controller,start,[{...}]}},
             {progress,init_kernel_started},
             {apply,{application,load,[...]}},
             {apply,{application,load,...}},
             {progress,applications_loaded},
             {apply,{...}},
             {apply,...},
             {...}|...]}}
5>
5> reltool:stop(Server).
ok

Create a target system

Erlang/OTP 20 [erts-10.0] [source-c13b302] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10]
[hipe] [kernel-poll:false]
Eshell V10.0  (abort with ^G)
1>
1> Config = {sys, [{escript, "examples/display_args", [{incl_cond, include}]},
		   {app, inets, [{incl_cond, include}]},
		   {app, mnesia, [{incl_cond, exclude}]},
		   {app, ssl, [{incl_cond, exclude}]},
		   {app, runtime_tools, [{incl_cond, exclude}]},
		   {app, syntax_tools, [{incl_cond, exclude}]}]}.
{sys,[{escript,"examples/display_args",[{incl_cond,include}]},
      {app,inets,[{incl_cond,include}]},
      {app,mnesia,[{incl_cond,exclude}]},
      {app,ssl,[{incl_cond,exclude}]},
      {app,runtime_tools,[{incl_cond,exclude}]},
      {app,syntax_tools,[{incl_cond,exclude}]}]}
2>
2> {ok, Spec} = reltool:get_target_spec([Config]).
{ok,[{create_dir,"releases",
         [{write_file,"start_erl.data","10.0 1.0\n"},
          {create_dir,"1.0",
              [{write_file,"start_clean.rel",
                   [37,37,32,114,101,108,32,103,101,110,101,114,97,116|...]},
               {write_file,"start_clean.script",
                   [37,37,32,115,99,114,105,112,116,32,103,101,110|...]},
               {write_file,"start_clean.boot",
                   <<131,104,3,119,6,115,99,114,105,112,116,104,...>>},
               {write_file,"start_sasl.rel",
                   [37,37,32,114,101,108,32,103,101,110,101|...]},
               {write_file,"start_sasl.script",
                   [37,37,32,115,99,114,105,112,116,32|...]},
               {write_file,"start_sasl.boot",
                   <<131,104,3,119,6,115,99,114,105,...>>}]}]},
     {create_dir,"bin",
         [{copy_file,"display_args.escript",
              "/usr/local/lib/erlang/lib/reltool-0.7.3/examples/display_args"},
          {copy_file,"display_args","erts-10.0/bin/escript"},
          {copy_file,"start","erts-10.0/bin/start"},
          {copy_file,"ct_run","erts-10.0/bin/ct_run"},
          {copy_file,"dialyzer","erts-10.0/bin/dialyzer"},
          {copy_file,"run_erl","erts-10.0/bin/run_erl"},
          {copy_file,"erl","erts-10.0/bin/dyn_erl"},
          {copy_file,"to_erl","erts-10.0/bin/to_erl"},
          {copy_file,"epmd","erts-10.0/bin/epmd"},
          {copy_file,"erlc","erts-10.0/bin/erlc"},
          {copy_file,"typer","erts-10.0/bin/typer"},
          {copy_file,"escript","erts-10.0/bin/escript"},
          {write_file,"start_clean.boot",<<131,104,3,119,6,115,...>>},
          {write_file,"start_sasl.boot",<<131,104,3,119,6,...>>},
          {write_file,"start.boot",<<131,104,3,119,...>>}]},
     {copy_file,"Install"},
     {create_dir,"misc",
         [{copy_file,"format_man_pages"}]},
     {create_dir,"usr",
         [{create_dir,"lib",
              [{copy_file,"liberl_interface_st.a"},
               {copy_file,"libic.a"},
               {copy_file,"liberl_interface.a"},
               {copy_file,"libei_st.a"},
               {copy_file,"libei.a"}]},
          {create_dir,"include",
              [{copy_file,"driver_int.h"},
               {copy_file,"ei_connect.h"},
               {copy_file,"ei.h"},
               {copy_file,"erl_nif_api_funcs.h"},
               {copy_file,"erl_fixed_size_int_types.h"},
               {copy_file,"erl_int_sizes_config.h"},
               {copy_file,"erl_interface.h"},
               {copy_file,"eicode.h"},
               {copy_file,"erl_driver.h"},
               {copy_file,"erlang.idl"},
               {copy_file,[...]},
               {copy_file,...},
               {...}]}]},
     {create_dir,"erts-10.0",
         [{create_dir,"bin",
              [{copy_file,"start"},
               {copy_file,"ct_run"},
               {copy_file,"erlexec"},
               {copy_file,"dialyzer"},
               {copy_file,"beam.smp"},
               {copy_file,"run_erl"},
               {copy_file,"erl","erts-10.0/bin/dyn_erl"},
               {copy_file,"to_erl"},
               {copy_file,"epmd"},
               {copy_file,"erl_child_setup"},
               {copy_file,"heart"},
               {copy_file,[...]},
               {copy_file,...},
               {...}|...]},
          {create_dir,"lib",
              [{create_dir,"internal",
                   [{copy_file,"liberts_internal.a"},
                    {copy_file,"liberts_internal_r.a"},
                    {copy_file,"libethread.a"},
                    {copy_file,"README"}]},
               ]},
          {create_dir,"src",[{copy_file,"setuid_socket_wrap.c"}]},
          {create_dir,"doc",[]},
          {create_dir,"man",[]},
          {create_dir,"include",
              [{create_dir,"internal",
                   [{create_dir,"i386",[{...}|...]},
                    {copy_file,"erl_errno.h"},
                    {copy_file,[...]},
                    {copy_file,...},
                    {...}|...]},
               {copy_file,"driver_int.h"},
               {copy_file,"erl_nif_api_funcs.h"},
               {copy_file,"erl_fixed_size_int_types.h"},
               {copy_file,"erl_int_sizes_config.h"},
               {copy_file,[...]},
               {copy_file,...},
               {...}]}]},
     {create_dir,"lib",
         [{create_dir,"compiler-7.0.4",
              [{create_dir,"src",
                   [{copy_file,"beam_flatten.erl"},
                    {copy_file,[...]},
                    {copy_file,...},
                    {...}|...]},
               {create_dir,"ebin",
                   [{copy_file,[...]},{copy_file,...},{...}|...]}]},
          {create_dir,"crypto-3.7.4",
              [{create_dir,"src",[{copy_file,[...]},{copy_file,...}]},
               {create_dir,"ebin",[{copy_file,...},{...}|...]}]},
          {create_dir,"crypto-3.7.4",
              [{create_dir,"priv",
                   [{create_dir,"lib",[{copy_file,[...]},{copy_file,...}]},
                    {create_dir,"obj",[{copy_file,...},{...}|...]}]}]},
          {create_dir,"erts-10.0",
              [{create_dir,"src",[{...}|...]},
               {create_dir,"ebin",[...]}]},
          {create_dir,"hipe-3.15.4",
              [{create_dir,"flow",[...]},
               {copy_file,[...]},
               {create_dir,...},
               {...}|...]},
          {create_dir,"inets-6.3.9",
              [{create_dir,[...],...},{create_dir,...},{...}]},
          {create_dir,"inets-6.3.9",
              [{create_dir,"priv",[{create_dir,[...],...}]},
               {create_dir,"include",[{copy_file,...},{...}]}]},
          {create_dir,"kernel-5.2",[{...}|...]},
          {create_dir,"kernel-5.2",
              [{create_dir,"include",[{...}|...]}]},
          {create_dir,[...],...},
          {create_dir,...},
          {create_dir,"stdlib-3.3",[{create_dir,...}]},
          ...]}]}
3>
3> TargetDir = "/tmp/my_target_dir".
"/tmp/my_target_dir"
4>
4> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir).
{error,"/tmp/my_target_dir: no such file or directory"}
5>
5> file:make_dir(TargetDir).
ok
6>
6> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir).
ok
7>
7> file:list_dir(TargetDir).
{ok,["bin","Install","lib","misc","usr","erts-10.0",
     "releases"]}
8>
8> file:list_dir(filename:join([TargetDir,"lib"])).
{ok,["tools-2.9.1","inets-6.3.9",
     "kernel-5.2","sasl-3.0.3",
     "crypto-3.7.4","erts-10.0",
     "stdlib-3.3","compiler-7.0.4"]}
9>
9> file:make_dir("/tmp/yet_another_target_dir").
ok
10>
10> reltool:create_target([Config], "/tmp/yet_another_target_dir").
ok
11>
11> file:list_dir("/tmp/yet_another_target_dir").
{ok,["bin","Install","lib","misc","usr","erts-10.0",
     "releases"]}

reltool

Main API of the Reltool application

This is an interface module for the Reltool application.

Reltool is a release management tool. It analyses a given Erlang/OTP installation and determines various dependencies between applications. The graphical frontend depicts the dependencies and enables interactive customization of a target system. The backend provides a batch interface for generation of customized target systems.

The tool uses an installed Erlang/OTP system as input. root_dir is the root directory of the analysed system and it defaults to the system executing Reltool. Applications may also be located outside root_dir. lib_dirs defines library directories where additional applications may reside and it defaults to the directories listed by the operating system environment variable ERL_LIBS. See the module code for more info.

An application directory AppDir under a library directory is recognized by the existence of an AppDir/ebin directory. If this does not exist, Reltool will not consider AppDir at all when looking for applications.

It is recommended that application directories are named as the application, possibly followed by a dash and the version number. For example myapp or myapp-1.1.

Finally single modules and entire applications may be read from Escripts.

Some configuration parameters control the behavior of Reltool on system (sys) level. Others provide control on application (app) level and yet others are on module (mod) level. Module level parameters override application level parameters and application level parameters override system level parameters. Escript escript level parameters override system level parameters.

The following top level options are supported:

config - This is the main option and it controls the configuration of Reltool. It can either be a sys tuple or a name of a file containing a sys tuple.

trap_exit - This option controls the error handling behavior of Reltool. By default the window processes traps exit, but this behavior can altered by setting trap_exit to false.

wx_debug - This option controls the debug level of wx. As its name indicates it is only useful for debugging. See wx:debug/1 for more info.

Besides the already mentioned source parameters root_dir and lib_dirs, the following system (sys) level options are supported:

erts - Erts specific configuration. See application level options below.

escript - Escript specific configuration. An escript has a mandatory file name and escript level options that are described below.

app - Application specific configuration. An application has a mandatory name and application level options that are described below.

mod_cond - This parameter controls the module inclusion policy. It defaults to all which means that if an application is included (either explicitly or implicitly) all modules in that application will be included. This implies that both modules that exist in the ebin directory of the application, as well as modules that are named in the app file will be included. If the parameter is set to ebin, both modules in the ebin directory and derived modules are included. If the parameter is set to app, both modules in the app file and derived modules are included. derived means that only modules that are used by other included modules are included. The mod_cond setting on system level is used as default for all applications.

incl_cond - This parameter controls the application and escript inclusion policy. It defaults to derived which means that the applications that do not have any explicit incl_cond setting, will only be included if any other (explicitly or implicitly included) application uses it. The value include implies that all applications and escripts that do not have any explicit incl_cond setting will be included. exclude implies that all applications and escripts that do not have any explicit incl_cond setting will be excluded.

boot_rel - A target system may have several releases but the one given as boot_rel will be used as default when the system is booting up.

rel - Release specific configuration. Each release maps to a rel, script and boot file. See the module systools for more info about the details. Each release has a name, a version and a set of applications with a few release specific parameters such as type and included applications.

relocatable - This parameter controls whether the erl executable in the target system should automatically determine where it is installed or if it should use a hardcoded path to the installation. In the latter case the target system must be installed with reltool:install/2 before it can be used. If the system is relocatable, the file tree containing the target system can be moved to another location without re-installation. The default is true.

profile - The creation of the specification for a target system is performed in two steps. In the first step a complete specification is generated. It will likely contain much more files than you are interested in in your customized target system. In the second step the specification will be filtered according to your filters. There you have the ability to specify filters per application as well as system wide filters. You can also select a profile for your system. Depending on the profile, different default filters will be used. There are three different profiles to choose from: development, embedded and standalone. development is default. The parameters that are affected by the profile are: incl_sys_filters, excl_sys_filters, incl_app_filters and excl_app_filters.

app_file - This parameter controls the default handling of the app files when a target system is generated. It defaults to keep which means that app files are copied to the target system and their contents are kept as they are. strip means that a new app file is generated from the contents of the original app file where the non included modules are removed from the file. all does also imply that a new app file is generated from the contents of the original app file, with the difference that all included modules are added to the file. If the application does not have any app file a file will be created for all but not for keep and strip.

debug_info - The debug_info parameter controls what debug information in the beam file should be kept or stripped. keep keeps all debug info, strip strips all debug info, and a list of chunkids keeps only those chunks.

excl_lib

Warning

This option is experimental.

If the excl_lib option is set to otp_root then reltool will not copy anything from the Erlang/OTP installation ($OTPROOT) into the target structure. The goal is to create a "slim" release which can be used together with an existing Erlang/OTP installation. The target structure will therefore only contain a lib directory with the applications that were found outside of $OTPROOT (typically your own applications), and a releases directory with the generated .rel, .script and .boot files.

When starting this release, three things must be specified:

Which releases directory to use - Tell the release handler to use the releases directory in our target structure instead of $OTPROOT/releases. This is done by setting the SASL environment variable releases_dir, either from the command line (-sasl releases_dir <target-dir>/releases) or in sys.config.

Which boot file to use - The default boot file is $OTPROOT/bin/start, but in this case we need to specify a boot file from our target structure, typically <target-dir>/releases/<vsn>/<RelName>. This is done with the -boot command line option to erl

The location of our applications - The generated .script (and .boot) file uses the environment variable $RELTOOL_EXT_LIB as prefix for the paths to all applications. The -boot_var option to erl can be used for specifying the value of this variable, typically -boot_var RELTOOL_EXT_LIB <target-dir>/lib.

Example:

erl -sasl releases_dir \"mytarget/releases\" -boot mytarget/releases/1.0/myrel\
 -boot_var RELTOOL_EXT_LIB mytarget/lib

incl_sys_filters - This parameter normally contains a list of regular expressions that controls which files in the system should be included. Each file in the target system must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter in excl_sys_filters in order to be included. Which application files should be included is controlled with the parameters incl_app_filters and excl_app_filters. This parameter defaults to [".*"].

excl_sys_filters - This parameter normally contains a list of regular expressions that controls which files in the system should not be included in the target system. In order to be included, a file must match some filter in incl_sys_filters but not any filter in excl_sys_filters. This parameter defaults to [].

incl_app_filters - This parameter normally contains a list of regular expressions that controls which application specific files that should be included. Each file in the application must match at least one of the listed regular expressions in order to be included. Further the files may not match any filter in excl_app_filters in order to be included. This parameter defaults to [".*"].

excl_app_filters - This parameter normally contains a list of regular expressions that controls which application specific files should not be included in the target system. In order to be included, a file must match some filter in incl_app_filters but not any filter in excl_app_filters. This parameter defaults to [].

On application (escript) level, the following options are supported:

incl_cond - The value of this parameter overrides the parameter with the same name on system level.

On application (app) level, the following options are supported:

vsn - The version of the application. In an installed system there may exist several versions of an application. The vsn parameter controls which version of the application will be chosen.

This parameter is mutual exclusive with lib_dir. If vsn and lib_dir are both omitted, the latest version will be chosen.

Note that in order for reltool to sort application versions and thereby be able to select the latest, it is required that the version id for the application consists of integers and dots only, for example 1, 2.0 or 3.17.1.

lib_dir - The directory to read the application from. This parameter can be used to point out a specific location to fetch the application from. This is useful for instance if the parent directory for some reason is no good as a library directory on system level.

This parameter is mutual exclusive with vsn. If vsn and lib_dir are both omitted, the latest version will be chosen.

Note that in order for reltool to sort application versions and thereby be able to select the latest, it is required that the version id for the application consists of integers and dots only, for example 1, 2.0 or 3.17.1.

mod - Module specific configuration. A module has a mandatory name and module level options that are described below.

mod_cond - The value of this parameter overrides the parameter with the same name on system level.

incl_cond - The value of this parameter overrides the parameter with the same name on system level.

app_file - The value of this parameter overrides the parameter with the same name on system level.

debug_info - The value of this parameter overrides the parameter with the same name on system level.

incl_app_filters - The value of this parameter overrides the parameter with the same name on system level.

excl_app_filters - The value of this parameter overrides the parameter with the same name on system level.

On module (mod) level, the following options are supported:

incl_cond - This parameter controls whether the module is included or not. By default the mod_cond parameter on application and system level will be used to control whether the module is included or not. The value of incl_cond overrides the module inclusion policy. include implies that the module is included, while exclude implies that the module is not included. derived implies that the module is included if it is used by any other included module.

debug_info - The value of this parameter overrides the parameter with the same name on application level.

Summary

Types

app()

app_file()

app_name()

app_type()

app_vsn()

base_dir()

base_file()

boot_rel()

config()

debug_info()

dir()

escript()

escript_file()

excl_app_filters()

excl_lib()

excl_sys_filters()

file()

incl_app()

incl_app_filters()

incl_cond()

incl_defaults()

incl_derived()

incl_sys_filters()

lib_dir()

mod()

mod_cond()

mod_name()

option()

options()

profile()

re_regexp()

reason()

regexps()

rel_app()

rel_file()

rel_name()

rel_opt()

rel_vsn()

relocatable()

root_dir()

script_file()

server()

server_pid()

sys()

target_dir()

target_spec()

top_dir()

top_file()

warning()

window_pid()

Functions

create_target(PidOrOptions, TargetDir)

Create a target system.

eval_target_spec(Spec, SourceDir, TargetDir)

Create the actual target system from a specification generated by reltool:get_target_spec/1.

get_config(PidOrOption)

Equivalent to get_config(Server, false, false).

get_config(PidOrOptions, InclDef, InclDeriv)

Get reltool configuration.

get_rel(PidOrOptions, RelName)

Get contents of a release file. See rel for more details.

get_script(PidOrOptions, RelName)

Get contents of a boot script file. See script for more details.

get_server(WinPid)

Return the process identifier of the server process.

get_status(PidOrOptions)

Get status about the configuration

get_target_spec(PidOrOptions)

Return a specification of the target system. The actual target system can be created with reltool:eval_target_spec/3.

install(RelName, TargetDir)

Install a created target system

start()

Start a main window process with default options

start(Options)

Start a main window process with options

start_link(Options)

Start a main window process with options. The process is linked.

start_server(Options)

Start a server process with options. The server process identity can be given as an argument to several other functions in the API.

stop(Pid)

Stop a server or window process

Types

app()

(not exported)

-type app() ::
          {vsn, app_vsn()} |
          {lib_dir, lib_dir()} |
          {mod, mod_name(), [mod()]} |
          {mod_cond, mod_cond()} |
          {incl_cond, incl_cond()} |
          {app_file, app_file()} |
          {debug_info, debug_info()} |
          {incl_app_filters, incl_app_filters()} |
          {excl_app_filters, excl_app_filters()}.

app_file()

(not exported)

-type app_file() :: keep | strip | all.

app_name()

(not exported)

-type app_name() :: atom().

app_type()

(not exported)

-type app_type() :: permanent | transient | temporary | load | none.

app_vsn()

(not exported)

-type app_vsn() :: string().

base_dir()

(not exported)

-type base_dir() :: dir().

base_file()

(not exported)

-type base_file() :: file().

boot_rel()

(not exported)

-type boot_rel() :: rel_name().

config()

(not exported)

-type config() :: {sys, [sys()]}.

debug_info()

(not exported)

-type debug_info() :: keep | strip | [beam_lib:chunkid()].

dir()

(not exported)

-type dir() :: file:filename().

escript()

(not exported)

-type escript() :: {incl_cond, incl_cond()}.

escript_file()

(not exported)

-type escript_file() :: file().

excl_app_filters()

(not exported)

-type excl_app_filters() :: regexps().

excl_lib()

(not exported)

-type excl_lib() :: otp_root.

excl_sys_filters()

(not exported)

-type excl_sys_filters() :: regexps().

file()

(not exported)

-type file() :: file:filename().

incl_app()

(not exported)

-type incl_app() :: app_name().

incl_app_filters()

(not exported)

-type incl_app_filters() :: regexps().

incl_cond()

(not exported)

-type incl_cond() :: include | exclude | derived.

incl_defaults()

(not exported)

-type incl_defaults() :: boolean().

incl_derived()

(not exported)

-type incl_derived() :: boolean().

incl_sys_filters()

(not exported)

-type incl_sys_filters() :: regexps().

lib_dir()

(not exported)

-type lib_dir() :: dir().

mod()

(not exported)

-type mod() :: {incl_cond, incl_cond()} | {debug_info, debug_info()}.

mod_cond()

(not exported)

-type mod_cond() :: all | app | ebin | derived | none.

mod_name()

(not exported)

-type mod_name() :: atom().

option()

(not exported)

-type option() :: {wx_debug, term()} | {trap_exit, boolean()} | config() | {config, config() | file()}.

options()

(not exported)

-type options() :: [option()].

profile()

(not exported)

-type profile() :: development | embedded | standalone.

re_regexp()

(not exported)

-type re_regexp() :: string().

reason()

(not exported)

-type reason() :: string().

regexps()

(not exported)

-type regexps() :: [re_regexp()] | {add, [re_regexp()]} | {del, [re_regexp()]}.

rel_app()

(not exported)

-type rel_app() ::
          app_name() |
          {app_name(), app_type()} |
          {app_name(), [incl_app()]} |
          {app_name(), app_type(), [incl_app()]}.

rel_file()

(not exported)

-type rel_file() :: term().

rel_name()

(not exported)

-type rel_name() :: string().

rel_opt()

(not exported)

-type rel_opt() :: {load_dot_erlang, boolean()}.

rel_vsn()

(not exported)

-type rel_vsn() :: string().

relocatable()

(not exported)

-type relocatable() :: boolean().

root_dir()

(not exported)

-type root_dir() :: dir().

script_file()

(not exported)

-type script_file() :: term().

server()

(not exported)

-type server() :: server_pid() | options().

server_pid()

(not exported)

-type server_pid() :: pid().

sys()

(not exported)

-type sys() ::
          {mod_cond, mod_cond()} |
          {incl_cond, incl_cond()} |
          {debug_info, debug_info()} |
          {app_file, app_file()} |
          {profile, profile()} |
          {excl_lib, excl_lib()} |
          {incl_sys_filters, incl_sys_filters()} |
          {excl_sys_filters, excl_sys_filters()} |
          {incl_app_filters, incl_app_filters()} |
          {excl_app_filters, excl_app_filters()} |
          {root_dir, root_dir()} |
          {lib_dirs, [lib_dir()]} |
          {boot_rel, boot_rel()} |
          {rel, rel_name(), rel_vsn(), [rel_app()]} |
          {rel, rel_name(), rel_vsn(), [rel_app()], [rel_opt()]} |
          {relocatable, relocatable()} |
          {erts, app()} |
          {escript, escript_file(), [escript()]} |
          {app, app_name(), [app()]}.

target_dir()

(not exported)

-type target_dir() :: dir().

target_spec()

(not exported)

-type target_spec() ::
          [target_spec()] |
          {create_dir, base_dir(), [target_spec()]} |
          {create_dir, base_dir(), top_dir(), [target_spec()]} |
          {copy_file, base_file()} |
          {copy_file, base_file(), top_file()} |
          {write_file, base_file(), binary()} |
          {strip_beam_file, base_file()}.

top_dir()

(not exported)

-type top_dir() :: file().

top_file()

(not exported)

-type top_file() :: file().

warning()

(not exported)

-type warning() :: string().

window_pid()

(not exported)

-type window_pid() :: pid().

Functions

create_target(PidOrOptions, TargetDir)

-spec create_target(server(), target_dir()) -> ok | {error, reason()}.

Create a target system.

Gives the same result as {ok,TargetSpec}=reltool:get_target_spec(Server) and reltool:eval_target_spec(TargetSpec,RootDir,TargetDir).

eval_target_spec(Spec, SourceDir, TargetDir)

-spec eval_target_spec(target_spec(), root_dir(), target_dir()) -> ok | {error, reason()}.

Create the actual target system from a specification generated by reltool:get_target_spec/1.

The creation of the specification for a target system is performed in two steps. In the first step a complete specification will be generated. It will likely contain much more files than you are interested in your target system. In the second step the specification will be filtered according to your filters. There you have the ability to specify filters per application as well as system wide filters. You can also select a profile for your system. Depending on the profile, different default filters will be used.

The top directories bin, releases and lib are treated differently from other files. All other files are by default copied to the target system. The releases directory contains generated rel, script, and boot files. The lib directory contains the applications. Which applications are included and if they should be customized (stripped from debug info etc.) is specified with various configuration parameters. The files in the bin directory are copied from the erts-vsn/bin directory, but only those files that were originally included in the bin directory of the source system.

If the configuration parameter relocatable was set to true there is no need to install the target system with reltool:install/2 before it can be started. In that case the file tree containing the target system can be moved without re-installation.

In most cases, the RootDir parameter should be set to the same as the root_dir configuration parameter used in the call to reltool:get_target_spec/1 (or code:root_dir/0 if the configuration parameter is not set). In some cases it might be useful to evaluate the same target specification towards different root directories. This should, however, be used with great care as it requires equivalent file structures under all roots.

get_config(PidOrOption)

-spec get_config(server()) -> {ok, config()} | {error, reason()}.

Equivalent to get_config(Server, false, false).

get_config(PidOrOptions, InclDef, InclDeriv)

-spec get_config(server(), incl_defaults(), incl_derived()) -> {ok, config()} | {error, reason()}.

Get reltool configuration.

Normally, only the explicit configuration parameters with values that differ from their defaults are interesting. But the builtin default values can be returned by setting InclDefaults to true. The derived configuration can be returned by setting InclDerived to true.

get_rel(PidOrOptions, RelName)

-spec get_rel(server(), rel_name()) -> {ok, rel_file()} | {error, reason()}.

Get contents of a release file. See rel for more details.

get_script(PidOrOptions, RelName)

-spec get_script(server(), rel_name()) -> {ok, script_file()} | {error, reason()}.

Get contents of a boot script file. See script for more details.

get_server(WinPid)

-spec get_server(window_pid()) -> {ok, server_pid()} | {error, reason()}.

Return the process identifier of the server process.

get_status(PidOrOptions)

(since OTP R14B)

-spec get_status(server()) -> {ok, [warning()]} | {error, reason()}.

Get status about the configuration

get_target_spec(PidOrOptions)

-spec get_target_spec(server()) -> {ok, target_spec()} | {error, reason()}.

Return a specification of the target system. The actual target system can be created with reltool:eval_target_spec/3.

install(RelName, TargetDir)

-spec install(rel_name(), dir()) -> ok | {error, reason()}.

Install a created target system

start()

-spec start() -> {ok, window_pid()} | {error, reason()}.

Start a main window process with default options

start(Options)

-spec start(options()) -> {ok, window_pid()} | {error, reason()}.

Start a main window process with options

start_link(Options)

-spec start_link(options()) -> {ok, window_pid()} | {error, reason()}.

Start a main window process with options. The process is linked.

start_server(Options)

-spec start_server(options()) -> {ok, server_pid()} | {error, reason()}.

Start a server process with options. The server process identity can be given as an argument to several other functions in the API.

stop(Pid)

-spec stop(server_pid() | window_pid()) -> ok | {error, reason()}.

Stop a server or window process