aboutsummaryrefslogtreecommitdiffstats
path: root/lib/reltool/doc/src/reltool_usage.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/reltool/doc/src/reltool_usage.xml')
-rw-r--r--lib/reltool/doc/src/reltool_usage.xml393
1 files changed, 393 insertions, 0 deletions
diff --git a/lib/reltool/doc/src/reltool_usage.xml b/lib/reltool/doc/src/reltool_usage.xml
new file mode 100644
index 0000000000..885828d1f0
--- /dev/null
+++ b/lib/reltool/doc/src/reltool_usage.xml
@@ -0,0 +1,393 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2009</year>
+ <year>2009</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>Usage</title>
+ <prepared>H&aring;kan Mattsson</prepared>
+ <responsible>H&aring;kan Mattsson</responsible>
+ <docno></docno>
+ <approved>H&aring;kan Mattsson</approved>
+ <checked></checked>
+ <date></date>
+ <rev>%VSN%</rev>
+ <file>reltool_usage.xml</file>
+ </header>
+
+ <section>
+ <title>Overview</title>
+ <p>This document focuses on the graphical parts of the tool. The
+ concepts are explained in the reference manual for the module
+ <c>reltool</c>.</p>
+ </section>
+
+ <section>
+ <title>System window</title>
+ <p>The system window is started with the function
+ <c>reltool:start/1</c>. At startup the tool will process the all
+ <c>beam</c> files and <c>app</c> 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.</p>
+
+ <p>The system window consists of four main pages (tabs):</p>
+
+ <list>
+ <item>Libraries
+ </item>
+ <item>System settings
+ </item>
+ <item>Applications
+ </item>
+ <item>Releases
+ </item>
+ </list>
+
+ <p>Click on a name tag to display its page.</p>
+
+ <section>
+ <title>Libraries</title>
+ <p>On the library page it is possible to control which sources
+ that 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.</p>
+
+ <p>The <c>Root directory</c> can be edited by selecting the
+ line where the path of the root directory is displayed and
+ clicking with the right mouse button. Choose edit in the menu
+ that pops up. </p>
+
+ <p>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 with 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 <c>Library directories</c> and clicking with the right
+ mouse button. Choose add in the menu that pops up.</p>
+
+ <p>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 with 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 <c>Escript files</c> and
+ clicking with the right mouse button. Choose add in the menu
+ that pops up.</p>
+
+ <p>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.</p>
+ </section>
+
+ <section>
+ <title>System settings</title>
+ <p>On the system settings page it is possible to control some
+ global settings that are used as defaults for all
+ applications. Set the <c>Application inclusion policy</c> to
+ <c>include</c> to include all applications that not are
+ explicitly excluded. See <c>incl_cond</c> (application
+ inclusion) and <c>mod_cond</c> (module inclusion) in the
+ reference manual for the module <c>reltool</c> for more
+ info.</p>
+ <p>The system settings page is rather incomplete.</p>
+ </section>
+
+ <section>
+ <title>Applications</title>
+ <p>There are four categories of applications on the
+ applications page. <c>Included</c> contains applications that
+ are explicitly included. <c>Excluded</c> contains applications
+ that are explicitly excluded. <c>Derived</c> contains
+ applications that either are used directly by explicitly
+ included applications or by other derived
+ applications. <c>Available</c> contains the remaining
+ applications.</p>
+
+ <p>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.</p>
+
+ <p>The symbols in front of the application names are intended
+ to describe the status of the application. There are error
+ symbols and warning symbols that means that there are
+ something that 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, then comes the warnings and the normal ones
+ (ticks and crosses) are found at the end.</p>
+
+ <p>Double click on an application to launch its application
+ window.</p>
+ </section>
+
+ <section>
+ <title>Releases</title>
+ <p>The releases page is incomplete and very experimental.</p>
+ </section>
+
+ <section>
+ <title>File menu</title>
+
+ <list>
+ <item>
+ <p><c>Display application dependency graph</c> - Launches an
+ application force graph window. All included and derived
+ applications and their dependencies will be shown in a
+ graph.</p>
+ </item>
+ <item>
+ <p><c>Display module dependency graph</c> - Launch a module
+ force graph window. All included and derived modules and
+ their dependencies will be shown in a graph.</p>
+ </item>
+ <item>
+ <p><c>Reset configuration to default</c></p>
+ </item>
+ <item>
+ <p><c>Undo configuration (toggle)</c></p>
+ </item>
+ <item>
+ <p><c>Load configuration</c> - Loads a new configuration from file.</p>
+ </item>
+ <item>
+ <p><c>Save configuration</c> - Saves the current
+ configuration to file. Normally, only the explictit
+ configuration parameters with values that differs from their
+ defaults are saved. But the configuration with or without
+ default values and with or without derived values may also
+ be saved.</p>
+ </item>
+ <item>
+ <p><c>Generate rel, script and boot files</c></p>
+ </item>
+ <item>
+ <p><c>Generate target system</c></p>
+ </item>
+ <item>
+ <p><c>Close</c> - Close the system window and all its subwindows.</p>
+ </item>
+ </list>
+
+ </section>
+
+ <section>
+ <title>Dependencies between applications or modules displayed as a graph</title>
+
+ <p>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.</p>
+
+ <p>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 is 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 i
+ pressed. Selected nodes can be locked, unlocked or deleted by
+ klicking on a suitable button.</p>
+
+ <p>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 link 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 each other. This force can be
+ adjusted with the right slider. If this force becomes to 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.</p>
+
+ <p>The <c>Freeze</c> button starts/stops the redrawing of the
+ graph. <c>Reset</c> moves the graph to the middle of the window
+ and resets all graph settings to default, with the exception of
+ deleted nodes.</p>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Application window</title>
+ <p>The application window is started by double clicking on an
+ application name. The application window consists of four
+ pages (tabs):</p>
+
+ <list>
+ <item>Application settings
+ </item>
+ <item>Modules
+ </item>
+ <item>Application dependencies
+ </item>
+ <item>Module dependencies
+ </item>
+ </list>
+
+ <p>Click on a name tag to display its page.</p>
+
+ <section>
+ <title>Application settings</title>
+ <p>Select version of the application in the <c>Source selection
+ policy</c> part of the page. By default the latest version of the
+ application is selected, but it is possible to override this by
+ explicitly select another version.</p>
+
+ <p>By default the <c>Application inclusion policy</c> on system
+ level is used for all applications. Set the value to
+ <c>include</c> if you want to explicitly include one particular
+ application. Set it to <c>exclude</c> if you want to exclude the
+ application despite that it is used by another (explicitly or
+ implicitly) included application. <c>derived</c> means that the
+ application automatically will be included if some other
+ (explicitly or implicitly) included application uses it.</p>
+
+ <p>By default the <c>Module inclusion policy</c> on system level
+ is used for all applications. Set it to <c>derived</c> if you only
+ want actually used modules to be included. Set it to <c>app</c> if
+ you, besides derived modules, also want the modules listed in the
+ app file to be included. Set it to <c>ebin</c> if you, besides
+ derived modules, also want the modules that exists as beam files
+ on the ebin directory to be included. Set it to <c>all</c> if you
+ want all modules to be included, that is the union of modules
+ found on the ebin directory and listed in the app file.</p>
+
+ <p>The application settings page is rather incomplete.</p>
+ </section>
+
+ <section>
+ <title>Modules</title>
+
+ <p>There are four categories of modules on the modules
+ page. <c>Included</c> contains modules that are explicitly
+ included. <c>Excluded</c> contains modules that are explicitly
+ excluded. <c>Derived</c> contains modules that either are used
+ directly by explicitly included modules or by other derived
+ modules. <c>Available</c> contains the remaining modules.</p>
+
+ <p>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.</p>
+
+ <p>The symbols in front of the module names are intended to
+ describe the status of the module. There are error symbols
+ and warning symbols that means that there are 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, then comes the warnings and the normal
+ ones (ticks and crosses) are found at the end.</p>
+
+ <p>Double click on an module to launch its module window.</p>
+
+ </section>
+
+ <section>
+ <title>Application dependencies</title>
+ <p>There are four categories of applications on the <c>Application
+ dependencies</c> page. If the application is used by other
+ applications, these are listed under <c>Used by</c>. If the
+ application requires other applications be started before it can
+ be started, these are listed under <c>Required</c>. These
+ applications are listed in the <c>applications</c> part of the
+ <c>app</c> file. If the application includes other applications,
+ these are listed under <c>Included</c>. These applications are
+ listed in the <c>included_applications</c> part of the <c>app</c>
+ file. If the application uses modules other applications, these
+ are listed under <c>Uses</c>.</p>
+
+ <p>Double click on an application name to launch an application window.</p>
+
+ </section>
+
+ <section>
+ <title>Module dependencies</title>
+
+ <p>There are two categories of modules on the <c>Module
+ dependencies</c> page. If the module is used by other modules,
+ these are listed under <c>Modules used by others</c>. If the
+ module uses modules other modules, these are listed under <c>Used
+ modules</c>.</p>
+
+ <p>Double click on an module name to launch a module window.</p>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Module window</title>
+
+ <p>The module window is started by double clicking on an module
+ name. The module window consists initially of two pages (tabs):</p>
+
+ <list>
+ <item>Dependencies
+ </item>
+ <item>Code
+ </item>
+ </list>
+
+ <p>Click on a name tag to display its page.</p>
+
+ <section>
+ <title>Dependencies</title>
+
+ <p>There are two categories of modules on the <c>Dependencies</c>
+ page. If the module is used by other modules, these are listed
+ under <c>Modules used by others</c>. If the module uses modules
+ other modules, these are listed under <c>Used modules</c>.</p>
+
+ <p>Double click on an module name to launch a module window.</p>
+
+ </section>
+
+ <section>
+ <title>Code</title>
+
+ <p>On the <c>Code</c> 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 <c>Find</c> field and
+ press enter. It is also possible to goto a certain line on the
+ module. The <c>Back</c> button can be used to go back to the
+ previous position.</p>
+
+ <p>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.
+ </p>
+ </section>
+
+ </section>
+
+</chapter>