1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE chapter SYSTEM "chapter.dtd"> 3 4<chapter> 5 <header> 6 <copyright> 7 <year>2009</year> 8 <year>2016</year> 9 <holder>Ericsson AB, All Rights Reserved</holder> 10 </copyright> 11 <legalnotice> 12 Licensed under the Apache License, Version 2.0 (the "License"); 13 you may not use this file except in compliance with the License. 14 You may obtain a copy of the License at 15 16 http://www.apache.org/licenses/LICENSE-2.0 17 18 Unless required by applicable law or agreed to in writing, software 19 distributed under the License is distributed on an "AS IS" BASIS, 20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 See the License for the specific language governing permissions and 22 limitations under the License. 23 24 The Initial Developer of the Original Code is Ericsson AB. 25 </legalnotice> 26 27 <title>Usage</title> 28 <prepared>Håkan Mattsson</prepared> 29 <responsible>Håkan Mattsson</responsible> 30 <docno></docno> 31 <approved>Håkan Mattsson</approved> 32 <checked></checked> 33 <date></date> 34 <rev>%VSN%</rev> 35 <file>reltool_usage.xml</file> 36 </header> 37 38 <section> 39 <title>Overview</title> 40 <p>This document focuses on the graphical parts of the tool. The 41 concepts are explained in the reference manual for the module 42 <c>reltool</c>.</p> 43 </section> 44 45 <section> 46 <title>System window</title> 47 <p>The system window is started with the function 48 <c>reltool:start/1</c>. At startup the tool will process all 49 <c>beam</c> files and <c>app</c> files in order to find out dependencies 50 between applications and their modules. Once all this information has been 51 derived, it will be possible to explore the tool.</p> 52 53 <p>The system window consists of four main pages (tabs):</p> 54 55 <list> 56 <item>Libraries 57 </item> 58 <item>System settings 59 </item> 60 <item>Applications 61 </item> 62 <item>Releases 63 </item> 64 </list> 65 66 <p>Click on a name tag to display its page.</p> 67 68 <section> 69 <title>Libraries</title> 70 <p>On the library page it is possible to control which sources 71 the tool will use. The page is organized as a tree which 72 can be expanded and collapsed by clicking on the little symbol 73 in the beginning of the expandable/collapsible lines.</p> 74 75 <p>The <c>Root directory</c> can be edited by selecting the 76 line where the path of the root directory is displayed and 77 clicking the right mouse button. Choose edit in the menu 78 that pops up.</p> 79 80 <p>Library directories can be added, edited or deleted. This 81 is done by selecting the line where the path to a library 82 directory is displayed and clicking the right mouse 83 button. Choose add, edit or delete in the menu that pops 84 up. New library directories can also be added by selecting the 85 line <c>Library directories</c> and clicking the right 86 mouse button. Choose add in the menu that pops up.</p> 87 88 <p>Escript files can be added, edited or deleted. This is done 89 by selecting the line where the path to an escript file is 90 displayed and clicking the right mouse button. Choose 91 add, edit or delete in the menu that pops up. New escripts can 92 also be added by selecting the line <c>Escript files</c> and 93 clicking the right mouse button. Choose add in the menu 94 that pops up.</p> 95 96 <p>When libraries and escripts are expanded, the names of 97 their contained applications will be displayed. Double click 98 on an application name to launch an application window.</p> 99 </section> 100 101 <section> 102 <title>System settings</title> 103 <p>On the system settings page it is possible to control some 104 global settings that are used as defaults for all 105 applications. Set the <c>Application inclusion policy</c> to 106 <c>include</c> to include all applications that are not 107 explicitly excluded. See <c>incl_cond</c> (application 108 inclusion) and <c>mod_cond</c> (module inclusion) in the 109 reference manual for the module <c>reltool</c> for more 110 info.</p> 111 <p>The system settings page is rather incomplete.</p> 112 </section> 113 114 <section> 115 <title>Applications</title> 116 <p>There are four categories of applications on the 117 applications page. <c>Included</c> contains applications that 118 are explicitly included. <c>Excluded</c> contains applications 119 that are explicitly excluded. <c>Derived</c> contains 120 applications that either are used directly by explicitly 121 included applications or by other derived 122 applications. <c>Available</c> contains the remaining 123 applications.</p> 124 125 <p>Select one or more applications and click on a button 126 directly below the application column to change application 127 category. For example, select an available application and 128 click on its tick button to move the application to the 129 included category. Clicking on the tick symbol for included 130 applications will move the application back to the available 131 category. The tick is undone.</p> 132 133 <p>The symbols in front of the application names are intended 134 to describe the status of the application. There are error 135 and warning symbols to signalize that there is 136 something which needs attention. The tick symbol means that the 137 application is included or derived and no problem has been 138 detected. The cross symbol means that the application is 139 excluded or available and no problem has been 140 detected. Applications with error symbols are listed first in 141 each category and are followed by the warnings and the 142 normal ones (ticks and crosses) at the end.</p> 143 144 <p>Double click on an application to launch its application 145 window.</p> 146 </section> 147 148 <section> 149 <title>Releases</title> 150 <p>The releases page is incomplete and very experimental.</p> 151 </section> 152 153 <section> 154 <title>File menu</title> 155 156 <list> 157 <item> 158 <p><c>Display application dependency graph</c> - Launches an 159 application force graph window. All included and derived 160 applications and their dependencies will be shown in a 161 graph.</p> 162 </item> 163 <item> 164 <p><c>Display module dependency graph</c> - Launch a module 165 force graph window. All included and derived modules and 166 their dependencies will be shown in a graph.</p> 167 </item> 168 <item> 169 <p><c>Reset configuration to default</c></p> 170 </item> 171 <item> 172 <p><c>Undo configuration (toggle)</c></p> 173 </item> 174 <item> 175 <p><c>Load configuration</c> - Loads a new configuration from file.</p> 176 </item> 177 <item> 178 <p><c>Save configuration</c> - Saves the current 179 configuration to file. Normally, only the explicit 180 configuration parameters with values that differ from their 181 defaults are saved. But the configuration with or without 182 default values and with or without derived values may also 183 be saved.</p> 184 </item> 185 <item> 186 <p><c>Generate rel, script and boot files</c></p> 187 </item> 188 <item> 189 <p><c>Generate target system</c></p> 190 </item> 191 <item> 192 <p><c>Close</c> - Close the system window and all its subwindows.</p> 193 </item> 194 </list> 195 196 </section> 197 198 <section> 199 <title>Dependencies between applications or modules displayed as a graph</title> 200 201 <p>The dependency graph windows are launched from the file menu 202 in the system window. The graph depicts all included and derived 203 applications/modules and their dependencies.</p> 204 205 <p>It is possible to perform some limited manipulations of the 206 graph. Nodes can be moved, selected, locked or deleted. Move a 207 single node or the entire graph by moving the mouse while the 208 left mouse button is pressed. A node can be locked into a fix 209 position by holding down the shift button when the left mouse 210 button is released. Select several nodes by moving the mouse 211 while the control key and the left mouse button are 212 pressed. Selected nodes can be locked, unlocked or deleted by 213 clicking on a suitable button.</p> 214 215 <p>The algorithm that is used to draw a graph with as few 216 crossed links as possible is called force graph. A force graph 217 consists of nodes and directed links between nodes. Each node is 218 associated with a repulsive force that pushes nodes away from 219 each other. This force can be adjusted with the left slider or 220 with the mouse wheel. Each link is associated with an attractive 221 force that pulls the nodes nearer to each other. This force can be 222 adjusted with the right slider. If this force becomes too strong, 223 the graph will be unstable. The third parameter that can be 224 adjusted is the length of the links. It is adjusted with the 225 middle slider.</p> 226 227 <p>The <c>Freeze</c> button starts/stops the redrawing of the 228 graph. <c>Reset</c> moves the graph to the middle of the window 229 and resets all graph settings to default, with the exception of 230 deleted nodes.</p> 231 232 </section> 233 234 </section> 235 236 <section> 237 <title>Application window</title> 238 <p>The application window is started by double clicking on an 239 application name. The application window consists of four 240 pages (tabs):</p> 241 242 <list> 243 <item>Application settings 244 </item> 245 <item>Modules 246 </item> 247 <item>Application dependencies 248 </item> 249 <item>Module dependencies 250 </item> 251 </list> 252 253 <p>Click on a name tag to display its page.</p> 254 255 <section> 256 <title>Application settings</title> 257 <p>Select version of the application in the <c>Source selection 258 policy</c> part of the page. By default the latest version of the 259 application is selected, but it is possible to override this by 260 explicitly selecting another version.</p> 261 262 <p>Note that in order for reltool to sort application versions and 263 thereby be able to select the latest, it is required that the 264 version id for the application consits of integers and dots only, 265 for example <c>1</c>, <c>2.0</c> or <c>3.17.1</c>.</p> 266 267 <p>By default the <c>Application inclusion policy</c> on system 268 level is used for all applications. Set the value to 269 <c>include</c> if you want to explicitly include one particular 270 application. Set it to <c>exclude</c> if you want to exclude the 271 application despite that it is used by another (explicitly or 272 implicitly) included application. <c>derived</c> means that the 273 application automatically will be included if some other 274 (explicitly or implicitly) included application uses it.</p> 275 276 <p>By default the <c>Module inclusion policy</c> on system level 277 is used for all applications. Set it to <c>derived</c> if you only 278 want actually used modules to be included. Set it to <c>app</c> if 279 you, besides derived modules, also want the modules listed in the 280 app file to be included. Set it to <c>ebin</c> if you, besides 281 derived modules, also want the modules that exist as beam files 282 in the ebin directory to be included. Set it to <c>all</c> if you 283 want all modules to be included, that is the union of modules 284 found in the ebin directory and listed in the app file.</p> 285 286 <p>The application settings page is rather incomplete.</p> 287 </section> 288 289 <section> 290 <title>Modules</title> 291 292 <p>There are four categories of modules on the modules 293 page. <c>Included</c> contains modules that are explicitly 294 included. <c>Excluded</c> contains modules that are explicitly 295 excluded. <c>Derived</c> contains modules that either are used 296 directly by explicitly included modules or by other derived 297 modules. <c>Available</c> contains the remaining modules.</p> 298 299 <p>Select one or more modules and click on a button directly 300 below the module column to change module category. For 301 example, select an available module and click on its tick 302 button to move the module to the included category. Clicking 303 on the tick symbol for included modules will move the 304 module back to the available category. The tick is 305 undone.</p> 306 307 <p>The symbols in front of the module names are intended to 308 describe the status of the module. There are error and 309 and warning symbols to signalize that there is something that needs 310 attention. The tick symbol means that the module is included 311 or derived and no problem has been detected. The cross symbol 312 means that the module is excluded or available and no problem 313 has been detected. Modules with error symbols are listed 314 first in each category and are followed by warnings and the 315 normal ones (ticks and crosses) at the end.</p> 316 317 <p>Double click on a module to launch its module window.</p> 318 319 </section> 320 321 <section> 322 <title>Application dependencies</title> 323 <p>There are four categories of applications on the <c>Application 324 dependencies</c> page. If the application is used by other 325 applications, these are listed under <c>Used by</c>. If the 326 application requires other applications be started before it can 327 be started, these are listed under <c>Required</c>. These 328 applications are listed in the <c>applications</c> part of the 329 <c>app</c> file. If the application includes other applications, 330 these are listed under <c>Included</c>. These applications are 331 listed in the <c>included_applications</c> part of the <c>app</c> 332 file. If the application uses other applications, these 333 are listed under <c>Uses</c>.</p> 334 335 <p>Double click on an application name to launch an application window.</p> 336 337 </section> 338 339 <section> 340 <title>Module dependencies</title> 341 342 <p>There are two categories of modules on the <c>Module 343 dependencies</c> page. If the module is used by other modules, 344 these are listed under <c>Modules using this</c>. If the 345 module uses other modules, these are listed under <c>Used 346 modules</c>.</p> 347 348 <p>Double click on an module name to launch a module window.</p> 349 350 </section> 351 352 </section> 353 354 <section> 355 <title>Module window</title> 356 357 <p>The module window is started by double clicking on an module 358 name. The module window consists initially of two pages (tabs):</p> 359 360 <list> 361 <item>Dependencies 362 </item> 363 <item>Code 364 </item> 365 </list> 366 367 <p>Click on a name tag to display its page.</p> 368 369 <section> 370 <title>Dependencies</title> 371 372 <p>There are two categories of modules on the <c>Dependencies</c> 373 page. If the module is used by other modules, these are listed 374 under <c>Modules using this</c>. If the module uses other 375 modules, these are listed under <c>Used modules</c>.</p> 376 377 <p>Double click on an module name to launch a module window.</p> 378 379 </section> 380 381 <section> 382 <title>Code</title> 383 384 <p>On the <c>Code</c> page the Erlang source code is displayed. It 385 is possible to search forwards and backwards for text in the 386 module. Enter a regular expression in the <c>Find</c> field and 387 press enter. It is also possible to go to a certain line in the 388 module. The <c>Back</c> button can be used to go back to the 389 previous position.</p> 390 391 <p>Put the marker on a function name and double click to go to the 392 definition of the function. If the function is defined in another 393 module, that module will be loaded and added to the page list. 394 </p> 395 </section> 396 397 </section> 398 399</chapter> 400