doc/sgml/user-guide/config-tool.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     config-tool.sgml                                            -->
   6 <!--                                                                 -->
   7 <!--     eCos User Guide                                             -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <part ID="THE-ECOS-CONFIGURATION-TOOL">
  33 <TITLE>The eCos Configuration Tool</TITLE>
  34
  35 <!-- {{{ Getting Started                -->
  36
  37 <CHAPTER id="config-tool-getting-started">
  38 <TITLE>Getting Started</TITLE>
  39
  40 <!-- ====================================================================== -->
  41
  42 <SECT1 id="config-tool-getting-started-intro">
  43 <TITLE>Introduction</TITLE>
  44
  45 <PARA> The <productname>eCos</productname> <application>Configuration Tool</application> is used
  46           to tailor <productname>eCos</productname> at source level, prior to compilation or
  47           assembly, and provides a configuration file and a set of
  48           files used to build user applications. The sources and other
  49           files used for building a configuration are provided in a
  50           <EMPHASIS>component repository</EMPHASIS>, which is loaded
  51           when the <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION>
  52           is invoked. The component repository includes a set of files
  53           defining the structure of relationships between the
  54           <application>Configuration Tool</application> and other components, and is written in a
  55           <FIRSTTERM>Component Definition Language</FIRSTTERM> (<ACRONYM>CDL</ACRONYM>).
  56           For a description of the concepts underlying component
  57           configuration, see <xref linkend="cdl-concepts">.</PARA>
  58 </SECT1>
  59
  60 <!-- ====================================================================== -->
  61
  62 <SECT1 id="config-tool-invoking">
  63 <TITLE>Invoking the <productname>eCos</productname> <application>Configuration Tool</application></TITLE>
  64
  65 <SECT2>
  66 <TITLE>On Linux</TITLE>
  67
  68 <PARA>Add the <productname>eCos</productname> <application>Configuration Tool</application> install directory to your PATH, for example:</PARA>
  69
  70 <PROGRAMLISTING>
  71 export PATH=/opt/ecos/ecos<replaceable>&Version;</replaceable>/bin:$PATH
  72 </PROGRAMLISTING>
  73
  74 <PARA>You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repository
  75  location, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of these
  76 two arguments is not significant. For example:</PARA>
  77
  78 <PROGRAMLISTING>
  79 configtool /opt/ecos/ecos<replaceable>&Version;</replaceable>/packages myfile.ecc
  80 </PROGRAMLISTING>
  81
  82 <PARA>The <application>Configuration Tool</application> will be displayed (see <xref linkend="figure-configuration-tool">).</PARA>
  83 </SECT2>
  84
  85 <SECT2>
  86 <TITLE>On Windows</TITLE>
  87
  88 <PARA>There are two ways in which to invoke the <productname>eCos</productname> <application>Configuration Tool</application>:</PARA>
  89 <ITEMIZEDLIST>
  90 <LISTITEM>
  91 <PARA>        from the desktop explorer or program set up at installation
  92               time (by default
  93               <EMPHASIS>Start</EMPHASIS>
  94               -&gt;
  95               <EMPHASIS>Programs</EMPHASIS>
  96               -&gt;
  97               <EMPHASIS>eCos</EMPHASIS>
  98               -&gt;
  99               <EMPHASIS>Configuration Tool</EMPHASIS>
 100               ).</PARA>
 101 </LISTITEM>
 102 <LISTITEM>
 103 <PARA>type (at a command prompt or in the
 104             <EMPHASIS>Start</EMPHASIS>
 105             menu&rsquo;s
 106             <EMPHASIS>Run</EMPHASIS>
 107             item): &lt;foldername&gt;&bsol;ConfigTool.exe where &lt;foldername&gt; is
 108             the full path of the directory in which you installed the <productname>eCos</productname>
 109             <application>Configuration Tool</application>.</PARA>
 110 <!--
 111 <para>
 112 XXXXX Change location of configtool in line with installation
 113               instructions. XXXXX
 114 </para>
 115 -->
 116
 117 </LISTITEM>
 118 <LISTITEM>
 119 <PARA>The
 120             <application>Configuration Tool</application>
 121             will be displayed (see <xref linkend="figure-configuration-tool">).</PARA>
 122 </LISTITEM>
 123 </ITEMIZEDLIST>
 124
 125 <PARA>
 126 You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repository
 127 location, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of these
 128 two arguments is not significant. For example:</PARA>
 129
 130 <PROGRAMLISTING>
 131 configtool "c:\Program Files\eCos\packages" myfile.ecc
 132 </PROGRAMLISTING>
 133
 134 <!--
 135         <para>
 136 XXXXX Change location of eCos in line with installation instructions. XXXXX
 137         </para>
 138 -->
 139
 140 <PARA>If you invoke the configuration tool from the command line with
 141 <EMPHASIS>--help</EMPHASIS>, you will see this output:</PARA>
 142
 143 <PROGRAMLISTING>
 144 Usage: eCos Configuration Tool [-h] [-e] [-v] [-c] [input file 1] [input file 2]
 145   -h  --help            displays help on the command line parameters
 146   -e  --edit-only       edit save file only
 147   -v  --version         print version
 148   -c  --compile-help    compile online help only
 149 </PROGRAMLISTING>
 150
 151 <PARA>This summarizes valid parameters and switches. Switches are shown with
 152 both short form and long form.</PARA>
 153
 154 <PARA><EMPHASIS>--help</EMPHASIS> shows valid options and parameters, as above.</PARA>
 155
 156 <PARA><EMPHASIS>--edit-only</EMPHASIS> runs the <application>Configuration Tool</application> in a mode that
 157 suppresses creation of a build tree, in case you only want to create and edit save files.</PARA>
 158
 159 <PARA><EMPHASIS>--version</EMPHASIS> shows version and build date information, and exits.</PARA>
 160
 161 <PARA><EMPHASIS>--compile-help</EMPHASIS> compiles help contents files from the HTML documentation
 162 files that the tool finds in the <productname>eCos</productname> repository, and exits.</PARA>
 163
 164 <FIGURE id="figure-configuration-tool">
 165 <TITLE><application>Configuration Tool</application></TITLE>
 166 <GRAPHIC ENTITYREF="graphic1"></GRAPHIC>
 167 </FIGURE>
 168 </SECT2>
 169 </SECT1>
 170
 171 <!-- ====================================================================== -->
 172
 173
 174 <SECT1 id="config-tool-component-repository">
 175 <TITLE>The Component Repository</TITLE>
 176 <PARA>When you invoke the <productname>eCos</productname> <application>Configuration Tool</application>, it accesses the Component
 177           Repository, a read-only location of configuration
 178           information. For an explanation of &ldquo;Component
 179           Repository&rdquo; see <xref linkend="cdl-concepts">.</PARA>
 180 <PARA>The <productname>eCos</productname> <application>Configuration Tool</application> will look
 181           for a component repository using (in descending order of preference):</PARA>
 182 <ITEMIZEDLIST>
 183 <LISTITEM>
 184 <PARA>A location specified on the command line
 185 </PARA>
 186 </LISTITEM>
 187 <LISTITEM>
 188 <PARA>The component repository most recently used by the
 189 current user</PARA>
 190 </LISTITEM>
 191 <LISTITEM>
 192 <PARA>An <productname>eCos</productname> distribution under <filename>/opt/ecos</filename> (under
 193 Linux) or a default location set by the installation procedure (under
 194 Windows)</PARA>
 195 </LISTITEM>
 196 <LISTITEM>
 197 <PARA>User input</PARA>
 198 </LISTITEM>
 199 </ITEMIZEDLIST>
 200 <PARA>The final case above will normally only occur if the previous
 201           repository has been moved or (under Windows) installation information stored in
 202           the Windows registry has been modified; it will result in a dialog box
 203 being displayed that allows you to specify the repository location:</PARA>
 204 <FIGURE>
 205 <TITLE>Repository relocation dialog box</TITLE>
 206 <GRAPHIC ENTITYREF="graphic2"></GRAPHIC>
 207 </FIGURE>
 208 <PARA>Note that in order to use the <productname>eCos</productname> <application>Configuration Tool</application> you are obliged to provide a
 209           valid repository location. </PARA>
 210 <PARA>In the rare event that you subsequently wish to change
 211           the component location, select
 212           <EMPHASIS>Build</EMPHASIS>-&gt;<EMPHASIS>Repository</EMPHASIS>
 213           and the above dialog box will then be displayed.</PARA>
 214 <PARA>You can check the location of the current repository, the current save file
 215 path, and the current hardware template and default package,
 216 by selecting <EMPHASIS>Help</EMPHASIS>-&gt;<EMPHASIS>Repository Information...</EMPHASIS>.
 217 A summary will be displayed.</PARA>
 218 </SECT1>
 219
 220 <!-- ====================================================================== -->
 221
 222
 223 <SECT1 ID="config-tool-documents">
 224 <TITLE><productname>eCos</productname> <application>Configuration Tool</application> Documents</TITLE>
 225 <SECT2>
 226 <TITLE>Configuration Save File</TITLE>
 227 <PARA><productname>eCos</productname> configuration settings and other information
 228             (such as disabled conflicts) that are set using the
 229             <productname>eCos</productname> <application>Configuration Tool</application> are saved to
 230             a file between sessions. By default, when the
 231             <productname>eCos</productname> <application>Configuration Tool</application> is first
 232             invoked, it reads and displays information from the
 233             Component Registry and displays the information in an
 234             untitled blank document. You can perform the following
 235             operations on a document:</PARA>
 236 <SECT3>
 237 <TITLE>Save the currently active document</TITLE>
 238 <PARA>Use the &ldquo;<EMPHASIS>File-&gt;Save</EMPHASIS>&rdquo; menu
 239             item or click the <EMPHASIS>Save Document</EMPHASIS> icon on the
 240             toolbar; if the current document is unnamed, you will be prompted
 241             to supply a name for the configuration save file.</PARA>
 242 <FIGURE>
 243 <TITLE>Save As dialog box</TITLE>
 244 <GRAPHIC ENTITYREF="graphic3"></GRAPHIC>
 245 </FIGURE>
 246 </SECT3>
 247 <SECT3>
 248 <TITLE>Open an existing document</TITLE>
 249 <PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>Open</EMPHASIS>,
 250             or click the <EMPHASIS>Open Document</EMPHASIS> icon on the toolbar.
 251             You will be prompted to supply a name for the configuration save
 252             file. </PARA>
 253 <FIGURE>
 254 <TITLE>Open dialog box</TITLE>
 255 <GRAPHIC ENTITYREF="graphic4"></GRAPHIC>
 256 </FIGURE>
 257 </SECT3>
 258 <SECT3>
 259 <TITLE>Open a document you have used recently</TITLE>
 260 <PARA>Click its name at the bottom of the
 261             <EMPHASIS>File</EMPHASIS> menu. </PARA>
 262 <PARA>Documents may also be opened by:</PARA>
 263 <ITEMIZEDLIST>
 264 <LISTITEM>
 265 <PARA>double-clicking a Configuration Save File in the desktop
 266 explorer (Windows only);</PARA>
 267 </LISTITEM>
 268 <LISTITEM>
 269 <PARA>invoking the <productname>eCos</productname>
 270 <application>Configuration Tool</application>
 271 with the name of a Configuration File as command-line argument,
 272 or by creating a shortcut to the <productname>eCos</productname> <application>Configuration Tool</application> with such an argument
 273 (under Windows or a suitable Linux desktop environment).</PARA>
 274 </LISTITEM>
 275 </ITEMIZEDLIST>
 276 </SECT3>
 277 <SECT3>
 278 <TITLE>Create a new blank document based on the Component
 279               Registry</TITLE>
 280 <PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>New</EMPHASIS>,
 281 or click the <EMPHASIS>New Document</EMPHASIS> icon on the toolbar.</PARA>
 282 </SECT3>
 283 <SECT3>
 284 <TITLE>Save to a different file name</TITLE>
 285 <PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>Save
 286                 As</EMPHASIS>. You will be prompted to supply a new
 287               name for the configuration save file.</PARA>
 288 </SECT3>
 289 </SECT2>
 290 <SECT2>
 291 <TITLE>Build and Install Trees</TITLE>
 292 <PARA>The location of the build and install trees are
 293             derived from the <productname>eCos</productname> save file name as illustrated in the
 294             following example:</PARA>
 295 <PARA>Save file name = &ldquo;c:&bsol;My
 296             eCos&bsol;config1.ecc&rdquo;</PARA>
 297 <PARA>Install tree folder = &ldquo;c:&bsol;My
 298             eCos&bsol;config1_install&rdquo;</PARA>
 299 <PARA>Build tree folder = &ldquo;c:&bsol;My
 300             eCos&bsol;config1_build&rdquo;</PARA>
 301 <PARA>These names are automatically generated from the name
 302             of the save file.</PARA>
 303 <PARA>See also <xref linkend="cdl-concepts">.</PARA>
 304 </SECT2>
 305 </SECT1>
 306 </CHAPTER>
 307
 308 <!-- }}} -->
 309 <!-- {{{ Getting Help                   -->
 310
 311 <CHAPTER id="config-tool-getting-help">
 312 <TITLE>Getting Help</TITLE>
 313
 314 <PARA>The <productname>eCos</productname> <application>Configuration Tool</application> contains
 315 several methods for accessing online help.</PARA>
 316
 317 <!-- ================================================== -->
 318
 319 <SECT1 id="config-tool-context-help-dialogs">
 320
 321 <TITLE>Context-sensitive Help for Dialogs</TITLE>
 322 <PARA>Most dialogs displayed by the <productname>eCos</productname> <application>Configuration Tool</application> are supplied
 323 with context-sensitive help. You can then get help relating
 324 to any control within the current dialog box by</PARA>
 325
 326 <ITEMIZEDLIST>
 327 <LISTITEM>
 328 <PARA>Right-clicking the control (or pressing
 329               <EMPHASIS>F1</EMPHASIS>
 330               )</PARA>
 331 <PARA>A &ldquo;What&rsquo;s This?&rdquo; popup menu will
 332           be displayed. Click the menu to display a brief description of the
 333           function of the selected control.</PARA>
 334 </LISTITEM>
 335 <LISTITEM>
 336 <PARA>Clicking the question mark icon in the dialog
 337             caption bar (Windows) or the question mark button on the dialog (Linux).</PARA>
 338 <PARA>A question mark cursor will be displayed. Click on
 339               any control to display a brief description of its
 340               function.</PARA>
 341 </LISTITEM>
 342 </ITEMIZEDLIST>
 343 <PARA>Some dialogs may have a <EMPHASIS>Help</EMPHASIS>
 344           button. You can press this to display a more general
 345           description of the function of the dialog box as a whole.
 346           This help will be in HTML form; for more information, see
 347           below.</PARA>
 348 </SECT1>
 349
 350 <!-- ================================================== -->
 351
 352 <SECT1 id="config-tool-context-help-otherwin">
 353 <TITLE>Context-sensitive Help for Other Windows</TITLE>
 354 <PARA>In the <EMPHASIS>Help</EMPHASIS> menu, click
 355           <EMPHASIS>Help On...</EMPHASIS>
 356 <!--
 357  (or press
 358           <EMPHASIS>F1</EMPHASIS>)
 359 -->
 360 and then click on a window (or click on the arrow/question mark button
 361 on the toolbar, then click on a window). A small popup window page describing the
 362 window will be displayed. The same thing can be achieved by right-clicking
 363 on a window and clicking on <EMPHASIS>What's This?</EMPHASIS>.
 364 <!--
 365           This help will normally be in HTML format; for more
 366           information, see <xref linkend="methods-of-displaying-html-help">.
 367 -->
 368 </PARA>
 369 </SECT1>
 370 <SECT1 id="config-tool-context-help-config-items">
 371 <TITLE>Context-sensitive Help for Configuration Items</TITLE>
 372 <PARA>In the configuration window, right-click on a configuration
 373 item (or use <EMPHASIS>Shift+F10</EMPHASIS>). A context
 374 menu will be displayed; select <EMPHASIS>Visit Documentation</EMPHASIS>
 375 to display the page in the <productname>eCos</productname> documentation that most closely
 376 corresponds to the selected item.</PARA>
 377 </SECT1>
 378
 379 <SECT1 id="methods-of-displaying-html-help">
 380 <TITLE>Methods of Displaying HTML Help</TITLE>
 381
 382 <ORDEREDLIST>
 383
 384 <LISTITEM>
 385 <PARA>
 386 Using the internal help system. This will show an internal viewer similar to Microsoft HTML Help, with a contents
 387 hierarchy on the left and HTML pages on the right; see <xref linkend="figure-help-viewer">. The index is regenerated for each repository. If the documentation in
 388 the repository has changed but the contents does not reflect this, please use the Tools Regenerate Help Index menu
 389 item.
 390 </PARA>
 391 </LISTITEM>
 392
 393 <LISTITEM>
 394 <PARA>
 395 Using the default HTML browser. On Unix, you will need a .mailcap entry similar to this:
 396 </PARA>
 397
 398 <PARA>
 399 <PROGRAMLISTING>
 400 text/html; netscape -no-about-splash %s
 401 </PROGRAMLISTING>
 402 </PARA>
 403 </LISTITEM>
 404
 405 <LISTITEM>
 406 <PARA>
 407 Using the specified browser.
 408 </PARA>
 409 </LISTITEM>
 410
 411 </ORDEREDLIST>
 412
 413
 414 <FIGURE id="figure-help-viewer">
 415 <TITLE>HTML Help viewer</TITLE>
 416 <GRAPHIC ENTITYREF="graphic5"></GRAPHIC>
 417 </FIGURE>
 418 <PARA>If you wish, you may choose to have <EMPHASIS>HTML Help</EMPHASIS> displayed
 419 in a browser of your choice. To do this, select <EMPHASIS>View</EMPHASIS>-&gt;<EMPHASIS>Settings</EMPHASIS> and
 420 use the controls in the View Documentation group to select the replacement browser.
 421 Note that the Navigation facilities of the built-in <EMPHASIS>HTML
 422 Help</EMPHASIS> system will be unavailable if you choose this method
 423 of displaying help.</PARA>
 424 </SECT1>
 425 </CHAPTER>
 426
 427 <!-- }}} -->
 428 <!-- {{{ Customization                  -->
 429
 430 <CHAPTER id="config-tool-customization">
 431 <TITLE>Customization</TITLE>
 432 <PARA>The following visual aspects of the <productname>eCos</productname> <application>Configuration Tool</application> can be changed to suit
 433         individual preferences. These aspects are saved on a per-user
 434         basis, so that when the <productname>eCos</productname> <application>Configuration Tool</application> is next invoked by the same
 435         user, the appearance will be as set in the previous
 436         session.</PARA>
 437 <SECT1 id="config-tool-window-placement">
 438 <TITLE>Window Placement</TITLE>
 439 <PARA>The relative sizes of all windows in the <productname>eCos</productname> <application>Configuration Tool</application> may be adjusted by dragging
 440           the splitter bars that separate the windows. The chosen
 441           sizes will be used the next time the <productname>eCos</productname> <application>Configuration Tool</application> is invoked by the current
 442           user. </PARA>
 443 <PARA>All windows except the <EMPHASIS>Configuration
 444             Window</EMPHASIS> may be shown or hidden by using the
 445           commands under the <EMPHASIS>View</EMPHASIS> menu (for
 446           example, <EMPHASIS>View-&gt;Output</EMPHASIS>) or the
 447           corresponding keyboard accelerators
 448           (<EMPHASIS>Alt+1</EMPHASIS> to
 449           <EMPHASIS>Alt+4</EMPHASIS>).
 450 <!--
 451 By default the
 452 conflicts window is hidden.
 453 -->
 454 </PARA>
 455 <PARA>Your chosen set of windows (and their relative sizes) will
 456 be preserved between invocations of the <productname>eCos</productname> <application>Configuration
 457 Tool</application>.</PARA>
 458 </SECT1>
 459 <!--
 460 <SECT1 id="config-tool-toolbars">
 461 <TITLE>Toolbars</TITLE>
 462 <PARA>Select
 463           <EMPHASIS>View</EMPHASIS>-&gt;<EMPHASIS>Toolbars</EMPHASIS>:
 464           each of the standard and Memory Layout toolbars may be
 465           hidden or shown.</PARA>
 466 </SECT1>
 467 -->
 468 <SECT1 id="config-tool-settings">
 469 <TITLE>Settings</TITLE>
 470 <PARA>To change other visual aspects, select
 471           <EMPHASIS>View</EMPHASIS>-&gt;<EMPHASIS>Settings</EMPHASIS>
 472           and then select the <EMPHASIS>Display</EMPHASIS> and
 473           <EMPHASIS>View</EMPHASIS> tabs depending on the settings
 474           you wish to alter..
 475           The options are as follows:
 476 </PARA>
 477
 478
 479 <SECT2>
 480 <TITLE>Settings: Display tab</TITLE>
 481
 482 <FIGURE>
 483 <TITLE>Settings dialog, Display tab</TITLE>
 484 <GRAPHIC ENTITYREF="graphic32"></GRAPHIC>
 485 </FIGURE>
 486
 487 <SECT3>
 488 <TITLE>Labels</TITLE>
 489
 490 <PARA>In the configuration window, you can choose to have
 491             either <EMPHASIS>descriptive names</EMPHASIS> (the
 492             default) or <EMPHASIS>macro names</EMPHASIS> displayed as
 493             tree item labels. Descriptive names are generally more
 494             comprehensible, but macro names are used in some contexts
 495             such as conflict resolution and may be directly related to
 496             the source code of the configuration. Note that it is
 497             possible to search for an item in the configuration view
 498             by selecting
 499             <EMPHASIS>Find</EMPHASIS>-&gt;<EMPHASIS>Edit</EMPHASIS>
 500             (see <xref linkend="config-tool-searching">). Both
 501             descriptive names and macro names can be searched.</PARA>
 502 </SECT3>
 503
 504 <SECT3>
 505 <TITLE>Integer Items</TITLE>
 506 <PARA>You can choose to have integer items in the
 507             Configuration Window displayed in decimal or hexadecimal
 508             format.</PARA>
 509 </SECT3>
 510
 511 <SECT3>
 512 <TITLE>Font</TITLE>
 513
 514 <PARA>
 515 Change the font for a particular window by selecting the window name using the drop-down list,
 516 then clicking on <EMPHASIS>Change Font</EMPHASIS> to select a font for that
 517 window. The changes will be applied when the press <EMPHASIS>OK</EMPHASIS> to dismiss the Settings dialog.
 518 If you never make font changes, then the windows will take
 519 the default setting determined by your current Windows or Unix environment.
 520 </PARA>
 521 </SECT3>
 522
 523 <SECT3>
 524 <TITLE>Miscellaneous</TITLE>
 525
 526 <PARA>
 527 If the <EMPHASIS>Splash Screen</EMPHASIS> checkbox is checked, a <EMPHASIS>splash</EMPHASIS>
 528 window will appear as the application is loading. Uncheck this to eliminate the splash screen.
 529 </PARA>
 530
 531 </SECT3>
 532 </SECT2>
 533
 534 <SECT2>
 535 <TITLE>Settings: Viewers tab</TITLE>
 536
 537 <FIGURE>
 538 <TITLE>Settings dialog, Viewers tab</TITLE>
 539 <GRAPHIC ENTITYREF="graphic6"></GRAPHIC>
 540 </FIGURE>
 541
 542 <SECT3>
 543 <TITLE>View header files</TITLE>
 544
 545 <PARA>You can change the viewer used to display header files.</PARA>
 546 </SECT3>
 547
 548 <SECT3>
 549 <TITLE>View documentation</TITLE>
 550
 551 <PARA>You can change the viewer used to display HTML files.
 552 See <xref linkend="methods-of-displaying-html-help">.
 553 </PARA>
 554
 555
 556
 557 </SECT3>
 558
 559 </SECT2>
 560
 561 </SECT1>
 562 </CHAPTER>
 563
 564 <!-- }}} -->
 565 <!-- {{{ Screen Layout                  -->
 566
 567 <CHAPTER id="config-tool-screen-layout">
 568 <TITLE>Screen Layout</TITLE>
 569 <PARA>The following windows are available within the
 570       <productname>eCos</productname> <application> Configuration
 571         Tool</application>:
 572     </PARA>
 573 <ITEMIZEDLIST>
 574 <LISTITEM>
 575 <PARA>          Configuration Window</PARA>
 576 </LISTITEM>
 577 <LISTITEM>
 578 <PARA>          Properties Window</PARA>
 579 </LISTITEM>
 580 <LISTITEM>
 581 <PARA>          Short Description</PARA>
 582 </LISTITEM>
 583 <LISTITEM>
 584 <PARA>          Conflicts</PARA>
 585 </LISTITEM>
 586 <LISTITEM>
 587 <PARA>          Output</PARA>
 588 </LISTITEM>
 589 </ITEMIZEDLIST>
 590
 591 <PARA>The layout of the windows may be adjusted to suit your
 592         preferences: see <xref linkend="config-tool-settings">.</PARA>
 593
 594 <SECT1 id="config-tool-configuration-window">
 595 <TITLE>Configuration Window</TITLE>
 596 <PARA>This is the principal window used to configure <productname>eCos</productname>. It
 597           takes the form of a tree-based representation of the
 598           configuration items within the currently loaded <productname>eCos</productname>
 599           packages.</PARA>
 600 <PARA>In the case of items whose values may be changed,
 601           controls are available to set the item values. These either
 602           take the form of check boxes or radio buttons within the
 603           tree itself or cells to the right of the thin vertical
 604           splitter bar. Controls in the tree may be used in the usual
 605           way; cells, however, must first be activated.</PARA>
 606 <PARA>To activate a cell, simply click on it: it will assume a sunken
 607 appearance and data can then be edited in the cell. To terminate
 608 in-cell editing, click elsewhere in the configuration window or
 609 press <EMPHASIS>ENTER</EMPHASIS>. To discard the partial results
 610 of in-cell editing and revert to the previous value, press <EMPHASIS>ESCAPE</EMPHASIS>.
 611 <!-- Not yet implemented
 612 Note that an asterisk appears against configuration items which have changed since the configuration
 613 was last saved.
 614 -->
 615 </PARA>
 616 <PARA><GRAPHIC ENTITYREF="graphic7"></GRAPHIC></PARA>
 617 <PARA>Cells come in three varieties, according to the type of
 618           data they accept:</PARA>
 619 <TABLE>
 620 <TITLE>Cell types</TITLE>
 621 <TGROUP COLS="2">
 622 <THEAD>
 623 <ROW>
 624 <ENTRY>Cell Type</ENTRY>
 625 <ENTRY><PARA>Data Accepted</PARA></ENTRY>
 626 </ROW>
 627 </THEAD>
 628 <TBODY>
 629 <ROW>
 630 <ENTRY>Integer</ENTRY>
 631 <ENTRY>Decimal or hexadecimal values</ENTRY>
 632 </ROW>
 633 <ROW>
 634 <ENTRY>Floating Point</ENTRY>
 635 <ENTRY>Floating point values</ENTRY>
 636 </ROW>
 637 <ROW>
 638 <ENTRY>String</ENTRY>
 639 <ENTRY>Any</ENTRY>
 640 </ROW>
 641 </TBODY>
 642 </TGROUP>
 643 </TABLE><!--
 644 <row>
 645 <cell><normal>Integer</normal></cell><cell><normal>Decimal or hexadecimal
 646 values</normal></cell></row>
 647 <row>
 648 <cell><normal>Floating Point</normal></cell><cell><normal>Floating
 649 point values</normal></cell></row>
 650 <row>
 651 <cell><normal>String</normal></cell><cell><normal>Any</normal></cell></row>
 652 </body></formata>
 653 -->
 654 <PARA>In the case of string cells, you can double-click the cell
 655 to display a dialog box containing a larger region in which to edit
 656 the string value. This is useful in the case of long strings, or
 657 those spanning multiple lines.</PARA>
 658 <SECT2>
 659 <TITLE>Disabled items</TITLE>
 660 <PARA>Some items will appear disabled. In this case the item
 661             label and any associated controls and cells will be
 662             grayed. It is not be possible to change the values of
 663             disabled items.</PARA>
 664 <SECT3>
 665 <TITLE>Right-Clicking</TITLE>
 666 <PARA>You can right-click on an item in the configuration
 667               window item to display a pop-up menu which (depending on
 668               the type of the item selected) allows you to:</PARA>
 669 <ITEMIZEDLIST>
 670 <LISTITEM>
 671 <PARA> <EMPHASIS>Properties</EMPHASIS> &ndash;
 672                   information relating to the currently selected item
 673                   is displayed. The information is equivalent to that
 674                   displayed in the Properties
 675                   Window.</PARA>
 676 </LISTITEM>
 677 <LISTITEM>
 678 <PARA> <EMPHASIS>Restore Defaults</EMPHASIS> -
 679                   the default value of the currently selected item is
 680                   restored.</PARA>
 681 </LISTITEM>
 682 <LISTITEM>
 683 <PARA><EMPHASIS>Visit Documentation</EMPHASIS>
 684                   - causes the HTML page most closely relating to the
 685                   currently selected item to be displayed. This has
 686                   the same effect as double-clicking the URL property
 687                   in the Properties Window.</PARA>
 688 </LISTITEM>
 689 <LISTITEM>
 690 <PARA> <EMPHASIS>View Header File</EMPHASIS>
 691                   &ndash; this causes the file containing the items to
 692                   be displayed. This is equivalent to double-clicking
 693                   on the File property in the Properties Window. The
 694                   viewer used for this purpose may be changed using
 695                   the <EMPHASIS>View-&gt;Settings</EMPHASIS> menu item
 696                   (see <xref linkend="config-tool-settings">).
 697                   Note that this operation is only possible when the
 698                   current configuration is saved, in order to avoid
 699                   the possibility of changing the source
 700                   repository.</PARA>
 701 </LISTITEM>
 702 <LISTITEM>
 703 <PARA><EMPHASIS>Unload Package</EMPHASIS> -
 704                   this is equivalent to using the
 705                   <EMPHASIS>Build-&gt;Packages</EMPHASIS> menu item to
 706                   select and unload the package in
 707                   question.</PARA>
 708 </LISTITEM>
 709 </ITEMIZEDLIST>
 710 </SECT3>
 711 </SECT2>
 712 <SECT2>
 713 <TITLE>Conflicts Window</TITLE>
 714 <PARA>This window exists to display any configuration item
 715             conflicts. Conflicts are the result of failures to meet
 716             the requirements between configuration items expressed in
 717             the CDL. See <xref linkend="cdl-conflicts"> <!--in &ldquo;CDL
 718             Concepts&rdquo; on&nbsp;page&nbsp;45 -->.<GRAPHIC ENTITYREF="graphic8"></GRAPHIC></PARA>
 719 <PARA>The window comprises three columns:</PARA>
 720 <ITEMIZEDLIST>
 721 <LISTITEM>
 722 <PARA>          <EMPHASIS>Item</EMPHASIS></PARA>
 723 <PARA>This is the macro name of the first item involved
 724                 in the conflict.</PARA>
 725 </LISTITEM>
 726 <LISTITEM>
 727 <PARA>
 728                 <EMPHASIS>Conflict</EMPHASIS></PARA>
 729 <PARA>This is a description of the conflict type. The currently
 730                 supported types are &ldquo;unresolved&rdquo;, &ldquo;illegal
 731                 value&rdquo;, &ldquo;evaluation exception&rdquo;, &ldquo;goal
 732                 unsatisfied&rdquo; and &ldquo;bad data&rdquo;.</PARA>
 733 </LISTITEM>
 734 <LISTITEM>
 735 <PARA>
 736                 <EMPHASIS>Property</EMPHASIS></PARA>
 737 <PARA>This contains a description of the configuration
 738                 item&rsquo;s property that caused the conflict.</PARA>
 739 <PARA>Within the conflicts window you can right-click on
 740                 any item to display a context menu which allows you to
 741                 choose from one of the following options:</PARA>
 742 </LISTITEM>
 743 </ITEMIZEDLIST>
 744
 745 <PARA>To locate the item involved in the
 746 conflict, double-click in the first or third column, or
 747 right-click over the item and choose <EMPHASIS>Locate</EMPHASIS>
 748 from the popup menu.
 749 </PARA>
 750
 751 <PARA>You can use the <EMPHASIS>Tools-&gt;Resolve Conflicts</EMPHASIS> menu
 752 item, or right-click over the item and select <EMPHASIS>Resolve</EMPHASIS> from the popup menu,
 753 to resolve conflicts &mdash; <xref linkend="resolving-conflicts">.</PARA>
 754 <SECT3>
 755 <TITLE>Output Window</TITLE>
 756 <PARA>This window displays any output generated by
 757               execution of external tools and any error messages that
 758               are not suitable for display in other forms (for
 759               example, as message boxes).</PARA>
 760 <PARA>Within the output window you can right-click to display a
 761 context menu which allows you to:</PARA>
 762 <ITEMIZEDLIST>
 763 <LISTITEM>
 764 <PARA>Save the contents of the window to a
 765                   file</PARA>
 766 </LISTITEM>
 767 <LISTITEM>
 768 <PARA>Clear the contents of the
 769                   window</PARA>
 770 </LISTITEM>
 771 </ITEMIZEDLIST>
 772 </SECT3>
 773 <SECT3>
 774 <TITLE>Properties Window</TITLE>
 775 <PARA>This window displays the CDL properties of the item
 776               currently selected in the configuration window. The same
 777               information may be displayed by right-clicking the item
 778               and selecting &ldquo;properties&rdquo;.</PARA>
 779 <PARA>        <GRAPHIC ENTITYREF="graphic9"></GRAPHIC></PARA>
 780 <PARA>Two properties may be double-clicked as
 781             follows:</PARA>
 782 <ITEMIZEDLIST>
 783 <LISTITEM>
 784 <PARA><EMPHASIS>URL</EMPHASIS> &ndash;
 785                   double-clicking on a URL property causes the
 786                   referenced HTML page to be displayed. This has the
 787                   same effect as right-clicking on the item and
 788                   choosing &ldquo;Visit
 789                   Documentation&rdquo;.</PARA>
 790 </LISTITEM>
 791 <LISTITEM>
 792 <PARA><EMPHASIS>File</EMPHASIS> &ndash;
 793                   double-clicking on a File property in a saved
 794                   configuration causes the File to be displayed. The
 795                   viewer used for this purpose may be changed using
 796                   the <EMPHASIS>View-&gt;Settings</EMPHASIS> menu
 797                   item. Note that this operation is only possible when
 798                   the current configuration is saved, in order to
 799                   avoid the possibility of changing the source
 800                   repository.</PARA>
 801 </LISTITEM>
 802 </ITEMIZEDLIST>
 803 </SECT3>
 804 <SECT3>
 805 <TITLE>Short Description Window</TITLE>
 806 <PARA>This window displays a short description of the item
 807               currently selected in the configuration window. More
 808               extensive documentation may be available by
 809               right-clicking on the item and choosing &ldquo;Visit
 810               Documentation&rdquo;.</PARA>
 811 </SECT3>
 812 </SECT2>
 813 </SECT1>
 814 </CHAPTER>
 815
 816 <!-- }}} -->
 817 <!-- {{{ Updating and Configuration     -->
 818
 819 <CHAPTER id="config-tool-updating-configuration">
 820 <TITLE>Updating the Configuration</TITLE>
 821 <SECT1 id="config-tool-adding-removing-packages">
 822 <TITLE>Adding and Removing Packages</TITLE>
 823 <PARA>To add or remove packages from the configuration, select
 824           <EMPHASIS>Build</EMPHASIS>-&gt;<EMPHASIS>Packages</EMPHASIS>.<!--<conditionaltext>-->
 825             The following dialog box will be displayed:</PARA>
 826 <FIGURE>
 827 <TITLE>Packages dialog box</TITLE>
 828 <GRAPHIC ENTITYREF="graphic14"></GRAPHIC>
 829 </FIGURE>
 830 <PARA>The left-hand list shows those packages that are available to
 831           be loaded. The right-hand list shows those that are
 832           currently loaded. In order to transfer packages from one
 833           list to another (that is, to load or unload packages)
 834           double-click the selection or click the
 835           <EMPHASIS>Add</EMPHASIS> or <EMPHASIS>Remove</EMPHASIS>
 836           buttons.</PARA>
 837
 838 <PARA>The version drop-down list displays the versions of the
 839           selected packages. When loading packages, this control may
 840           be used to load versions other than the most recent
 841           (current). Note that if more than one package is selected,
 842           the version drop-down list will display only the versions
 843           common to all the selected packages.</PARA>
 844
 845 <PARA>The window under the version displays a brief
 846           description of the selected package. If more than one
 847           package is selected, this window will be blank.</PARA>
 848
 849 <PARA>
 850         Under the description window there is a <EMPHASIS>Keywords</EMPHASIS>
 851 control into which you can type a string to be matched against
 852 package names, macro names and descriptions. The lists are updated
 853 a second or so after typing has stopped.
 854 If you type several separate words,
 855 all of these words must be associated with a given package
 856 for that package to be displayed. If you select
 857 the <EMPHASIS>Match exactly</EMPHASIS> checkbox, then the string
 858 is taken to be a complete fragment and matched against the beginning
 859 of a name, macro name or descriptions. All matches are done
 860 case-insensitively.</PARA>
 861
 862 <PARA>
 863 If you check <EMPHASIS>Omit hardware packages</EMPHASIS>, only
 864 non-hardware packages will be shown.
 865 </PARA>
 866
 867 </SECT1>
 868 <SECT1 id="config-tool-platform-selection">
 869 <TITLE>Platform Selection</TITLE>
 870 <PARA>To add, modify or remove entries in the list of
 871           platforms used for running tests, select
 872           <EMPHASIS>Tools-&gt;Platforms</EMPHASIS>. The following
 873           dialog will be displayed:</PARA>
 874 <FIGURE>
 875 <TITLE>Platforms dialog box</TITLE>
 876 <GRAPHIC ENTITYREF="graphic15"></GRAPHIC>
 877 </FIGURE>
 878 <PARA>You may add, modify or remove platform entries as you
 879           wish, but in order to run tests, a platform must be defined
 880           to correspond to the currently loaded hardware template. The
 881           information associated with each platform name is used to
 882           run tests.</PARA>
 883 <PARA>To modify a platform, click the
 884           <EMPHASIS>Modify</EMPHASIS> button with the appropriate
 885           platform selected, or double-click on an entry in the list.
 886           A dialog will be displayed that allows you to change the
 887           command prefix, platform type and arguments for
 888           <EMPHASIS>GDB</EMPHASIS>. </PARA>
 889 <FIGURE>
 890 <TITLE>Platform Modify dialog box</TITLE>
 891 <GRAPHIC ENTITYREF="graphic16"></GRAPHIC>
 892 </FIGURE>
 893 <PARA>To add a new platform, click the
 894           <EMPHASIS>Add</EMPHASIS> button. A similar dialog will be
 895           displayed that allows you to define a new platform. To
 896           remove a platform, click the <EMPHASIS>Delete</EMPHASIS>
 897           button or press the <EMPHASIS>DEL</EMPHASIS> key with the
 898           appropriate platform selected.</PARA>
 899
 900 <PARA>The command prefix is used when running tests in order
 901           to determine the names of the executables (such as gdb) to
 902           be used. For example, if the gdb executable name is
 903           &ldquo;arm-elf-gdb.exe&rdquo; the prefix should be set to
 904           &ldquo;arm-elf&rdquo;.</PARA>
 905 <PARA>The platform type indicates the capabilities of the platform
 906 - whether it is hardware or a simulator, and whether breakpoints
 907 are supported.</PARA>
 908 <PARA>The arguments for the <EMPHASIS>GDB</EMPHASIS> field allow
 909 additional arguments to be passed to gdb when it is used to run
 910 a test.  This is typically used in the case of simulators linked
 911 to gdb in order to define memory layout.</PARA>
 912 </SECT1>
 913 <SECT1 id="config-tool-using-templates">
 914 <TITLE>Using Templates</TITLE>
 915 <PARA>To load a configuration based on a template, select
 916           <EMPHASIS>Build</EMPHASIS>-&gt;<EMPHASIS>Templates</EMPHASIS>.<!--<conditionaltext>--></PARA>
 917 <PARA>The following dialog box will be displayed:</PARA>
 918 <FIGURE>
 919 <TITLE>Templates dialog box</TITLE>
 920 <GRAPHIC ENTITYREF="graphic18"></GRAPHIC>
 921 </FIGURE>
 922 <PARA>Change the hardware template, the packages template, or
 923           both. To select a hardware template, choose from the first
 924           drop-list. To choose a packages template, choose from the
 925           second. Brief descriptions of each kind of template are
 926           provided in the corresponding edit boxes.</PARA>
 927 <SECT2 id="resolving-conflicts">
 928 <TITLE>Resolving conflicts</TITLE>
 929 <PARA>During the process of configuring <productname>eCos</productname> it is possible
 930             that conflicts will be created. For more details of the
 931             meaning of conflicts, see <xref linkend="cdl-concepts">.</PARA>
 932 <PARA>The Conflicts Window displays all conflicts in the
 933             current configuration. Additionally, a window in the
 934             status bar displays a count of the conflicts. Because the
 935             resolution of conflicts can be time-consuming, a mechanism
 936             exists whereby conflicts can be resolved
 937             automatically.</PARA>
 938 <PARA>You can choose to have a conflicts resolution dialog
 939             box displayed by means of the <EMPHASIS>View-&gt;Settings...
 940               <!--<conditionaltext>--></EMPHASIS>menu item, on the <EMPHASIS>Conflict Resolution</EMPHASIS>
 941 tab of the dialog.</PARA>
 942 <FIGURE>
 943 <TITLE>Options</TITLE>
 944 <GRAPHIC ENTITYREF="graphic19"></GRAPHIC>
 945 </FIGURE>
 946 <PARA>You can choose to have conflicts checked under the
 947             following circumstances:</PARA>
 948 <ITEMIZEDLIST>
 949 <LISTITEM>
 950 <PARA>After any item is changed (in other words,
 951                 as soon as the conflict is created)</PARA>
 952 </LISTITEM>
 953 <LISTITEM>
 954 <PARA>Before saving the configuration (including
 955                 building)</PARA>
 956 </LISTITEM>
 957 <LISTITEM>
 958 <PARA>Never</PARA>
 959 </LISTITEM>
 960 </ITEMIZEDLIST>
 961 <PARA>The method you chose depends on how much you need
 962                 your configuration to be free of conflicts. You may
 963                 want to avoid having to clean up all the conflicts at
 964                 once, or you may want to keep the configuration
 965                 consistent at all times. If you have major changes to
 966                 implement, which may resolve the conflicts, then you
 967                 might want to wait until after you have completed
 968                 these changes before you check for conflicts.</PARA>
 969 <!-- <label>NOTE</label> -->
 970 <NOTE>
 971 <PARA>If you choose to check conflicts after any item
 972               is changed, only newly arising conflicts are displayed.
 973               If you choose to check for conflicts before saving the
 974               configuration, the complete set is
 975               displayed.</PARA>
 976 </NOTE>
 977 </SECT2>
 978 <SECT2>
 979 <TITLE>Automatic resolution</TITLE>
 980 <PARA>If you check the &ldquo;Automatically suggest
 981             fixes&rdquo; check box, a conflicts resolution dialog box
 982             will be displayed whenever new conflicts are created. The
 983             same dialog box may be displayed at any stage by means of
 984             the <EMPHASIS>Tools-&gt;Resolve Conflicts</EMPHASIS>
 985             <EMPHASIS><!--<conditionaltext>--></EMPHASIS>menu item.
 986             </PARA>
 987 <PARA>The conflicts resolution dialog box contains two major windows. </PARA>
 988 <FIGURE>
 989 <TITLE>Resolve conflicts window</TITLE>
 990 <GRAPHIC ENTITYREF="graphic20"></GRAPHIC>
 991 </FIGURE>
 992 <PARA>The upper contains the set of conflicts to be addressed; the
 993 format of the data being as that of the Conflicts Window. The lower
 994 window contains a set of proposed resolutions &ndash; each entry
 995 is a suggested configuration item value change that as a whole may
 996 be expected to lead to the currently selected conflict being resolved. </PARA>
 997 <PARA>Note that there is no guarantee:</PARA>
 998 <ITEMIZEDLIST>
 999 <LISTITEM>
1000 <PARA>that automatic resolutions will be determinable for every
1001 conflict.</PARA>
1002 </LISTITEM>
1003 <LISTITEM>
1004 <PARA>  that the resolutions for separate conflicts will be independent.
1005 In other words, the resolution of one conflict may serve to prevent
1006 the resolution of another.</PARA>
1007 </LISTITEM>
1008 <LISTITEM>
1009 <PARA>  that the resolution conflicts will not create further
1010 conflicts.</PARA>
1011 </LISTITEM>
1012 </ITEMIZEDLIST>
1013 <PARA>The above warnings are, however, conservative. In practice
1014 (so long as the number and extent of conflicts are limited) automatic
1015 conflict resolution may be used to good effect to correct problems
1016 without undue amounts of programmer intervention.</PARA>
1017 <PARA>In order to select the conflicts to be applied, select or
1018 clear the check boxes against the resolutions for each proposed
1019 resolution. By default all resolutions are selected; you can return
1020 to the default state (in other words, cause all check boxes for
1021 each conflict to again become checked) by pressing the &ldquo;Reset&rdquo; button.
1022 Note that multiple selection may be used in the resolutions control
1023 to allow ranges of check boxes to be toggled in one gesture.</PARA>
1024 <PARA>When you are happy to apply the selected resolutions for each
1025 conflict displayed, click <EMPHASIS>Apply</EMPHASIS>; this will
1026 apply the resolutions. Alternatively you may cancel from the dialog
1027 box without any resolutions being applied.</PARA>
1028 </SECT2>
1029 </SECT1>
1030 </CHAPTER>
1031
1032 <!-- }}} -->
1033 <!-- {{{ Searching                      -->
1034
1035 <CHAPTER id="config-tool-searching">
1036 <TITLE>Searching</TITLE>
1037 <PARA>Select <EMPHASIS>Edit </EMPHASIS>--&gt; <EMPHASIS>Find</EMPHASIS>.
1038 You will be presented with a Find dialog box:</PARA>
1039 <FIGURE>
1040 <TITLE>Find dialog box</TITLE>
1041 <GRAPHIC ENTITYREF="graphic21"></GRAPHIC>
1042 </FIGURE>
1043 <PARA>Using this dialog box you can search for an exact text string
1044 in any one of three ways, as specified by your selection in the &ldquo;Search
1045 in&rdquo; drop-list:</PARA>
1046 <ITEMIZEDLIST>
1047 <LISTITEM>
1048 <PARA>Macro names - the search is for a text match within
1049 configuration item macro names</PARA>
1050 </LISTITEM>
1051 <LISTITEM>
1052 <PARA>                  Item names - the search is for a text match within
1053 configuration item descriptive names</PARA>
1054 </LISTITEM>
1055 <LISTITEM>
1056 <PARA>                  Short descriptions - the search is for a text match
1057 within configuration item short descriptions</PARA>
1058 </LISTITEM>
1059 </ITEMIZEDLIST>
1060 <PARA>Note that to invoke <EMPHASIS>Find</EMPHASIS> you can also
1061 click the <EMPHASIS>Find</EMPHASIS> icon on the toolbar. </PARA>
1062 </CHAPTER>
1063
1064 <!-- }}} -->
1065 <!-- {{{ Building                       -->
1066
1067 <CHAPTER id="config-tool-building">
1068 <TITLE>Building</TITLE>
1069 <PARA>When you have configured <productname>eCos</productname>, you may build the configuration.</PARA>
1070 <PARA><!--<conditionaltext>-->On the <EMPHASIS>Build</EMPHASIS> menu, click:</PARA>
1071 <ITEMIZEDLIST>
1072 <LISTITEM>
1073 <PARA>
1074 <EMPHASIS>Library</EMPHASIS>
1075  (or click the Build Library icon on the toolbar) &ndash; this
1076 causes the <productname>eCos</productname> configuration to be built. The result of a successful
1077 build will be (among other things) a library against which user
1078 code can be linked</PARA>
1079 </LISTITEM>
1080 <LISTITEM>
1081 <PARA>
1082 <EMPHASIS>Tests</EMPHASIS>
1083  &ndash; this causes the <productname>eCos</productname> configuration to be built, and
1084 additionally builds the relevant test cases linked against the <productname>eCos</productname> library</PARA>
1085 </LISTITEM>
1086 <LISTITEM>
1087 <PARA>
1088 <EMPHASIS>Clean</EMPHASIS>
1089  &ndash; this removes all intermediate files, thus causing a
1090 subsequent build/library or build/tests operation
1091 to cause recompilation of all relevant files.</PARA>
1092 </LISTITEM>
1093 <LISTITEM>
1094 <PARA>
1095 <EMPHASIS>Stop</EMPHASIS>
1096  &ndash; this causes a currently executing build (any of the
1097 above steps) to be interrupted</PARA>
1098 </LISTITEM>
1099 </ITEMIZEDLIST>
1100 <PARA>Build options may be displayed by using the <EMPHASIS>Build-&gt;Options</EMPHASIS> menu
1101 item. This displays a dialog box containing a drop-list control
1102 and two windows. The drop-list control allows you to select the
1103 type of build option to be displayed (for example &ldquo;LDFLAGS&rdquo; are
1104 the options applied at link-time. The left-hand window is a tree
1105 view of the packages loaded in the current configuration. The right-hand
1106 window is a list of the build options that will be used for the
1107 currently selected package.</PARA>
1108 <PARA>Note that this dialog box currently affords only read-only
1109 access to the build options. In order to change build options you
1110 must edit the relevant string configuration item.</PARA>
1111 <PARA>A single level of inheritance is supported: each package&rsquo;s
1112 build options are combined with the global options (these are to
1113 be found in the &ldquo;Global build options&rdquo; folder
1114 in the configuration view).</PARA>
1115 <PARA><GRAPHIC ENTITYREF="graphic22"></GRAPHIC></PARA>
1116 <SECT1 id="config-tool-selecting-build-tools">
1117 <TITLE>Selecting Build Tools</TITLE>
1118 <PARA>Normally the installation process will supply the information
1119 required for the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION> to
1120 locate the build tools (compiler, linker, etc.) necessary
1121 to perform a build. However if this information is not registered,
1122 or it is necessary to specify the location manually (for example,
1123 when a new toolchain installation has been made), select <EMPHASIS>Tools</EMPHASIS>-&gt;<EMPHASIS>Paths</EMPHASIS>-&gt;<EMPHASIS>Build
1124 Tools</EMPHASIS>. The following dialog box will be displayed:</PARA>
1125 <FIGURE>
1126 <TITLE>Build tools</TITLE>
1127 <GRAPHIC ENTITYREF="graphic23"></GRAPHIC>
1128 </FIGURE>
1129 <PARA>This dialog box allows you to locate the folder containing
1130 the build tools. </PARA>
1131 </SECT1>
1132 <SECT1 id="config-tool-selecting-user-tools">
1133 <TITLE>Selecting User Tools</TITLE>
1134 <PARA>Normally the installation process will supply the information
1135 required for the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION> to
1136 locate the user tools (cat, ls, etc.) necessary to perform
1137 a build. However if this information is not registered, or it is
1138 necessary to specify the location manually (for example, when a
1139 new toolchain installation has been made), select <EMPHASIS>Tools</EMPHASIS>-&gt;<EMPHASIS>Paths</EMPHASIS>-&gt;<EMPHASIS>User
1140 Tools</EMPHASIS>. The following dialog box will be displayed:</PARA>
1141 <FIGURE>
1142 <TITLE>User tools</TITLE>
1143 <GRAPHIC ENTITYREF="graphic24"></GRAPHIC>
1144 </FIGURE>
1145 </SECT1>
1146 </CHAPTER>
1147
1148 <!-- }}} -->
1149 <!-- {{{ Execution                      -->
1150
1151 <CHAPTER id="config-tool-test-execution"><!--<conditionaltext>-->
1152 <TITLE>Execution</TITLE>
1153 <PARA>Test executables that have been linked using the Build/Tests
1154 operation against the current configuration can be executed by selecting <!--<conditionaltext>--><EMPHASIS>Tools</EMPHASIS>-&gt;<EMPHASIS>Run
1155 Tests<!--<conditionaltext>--></EMPHASIS>.</PARA>
1156 <PARA>When tests are run, the <application>Configuration Tool</application> looks
1157 for a platform name corresponding to the currently loaded hardware template.
1158 If no such platform is found, a dialog will be displayed for you
1159 to define one; this dialog is similar to that displayed by the <EMPHASIS>Add</EMPHASIS> function
1160 in the <EMPHASIS>Tools-&gt;Platforms</EMPHASIS> dialog, but
1161 in this case the platform name cannot be changed.</PARA>
1162 <PARA>When a test run is invoked, a property sheet is displayed,
1163 comprising three tabs: <EMPHASIS>Executables</EMPHASIS>, <EMPHASIS>Output</EMPHASIS> and <EMPHASIS>Summary</EMPHASIS>.</PARA>
1164 <PARA>Note that the property sheet is resizable.</PARA>
1165 <PARA>Three buttons appear on the property sheet itself: <EMPHASIS>Run/Stop</EMPHASIS>, <EMPHASIS>Close</EMPHASIS> and <EMPHASIS>Properties</EMPHASIS>.</PARA>
1166 <PARA>The <EMPHASIS>Run</EMPHASIS> button is used to initiate a
1167 test run. Those tests selected on the <EMPHASIS>Executables</EMPHASIS> tab
1168 are run, and the output recorded on the <EMPHASIS>Output</EMPHASIS> and <EMPHASIS>Summary</EMPHASIS> tabs.
1169 During the course of a run, the <EMPHASIS>Run</EMPHASIS> button
1170 changes to &ldquo;Stop&rdquo;. The button may be used to interrupt
1171 a test run at any point.</PARA>
1172 <SECT1 id="config-tool-test-properties">
1173 <TITLE>Properties</TITLE>
1174 <PARA>The <EMPHASIS>Properties</EMPHASIS> button is used to change
1175 the connectivity properties for the test run.</PARA>
1176 <FIGURE>
1177 <TITLE>Properties dialog box</TITLE>
1178 <GRAPHIC ENTITYREF="graphic25"></GRAPHIC>
1179 </FIGURE>
1180 <SECT2>
1181 <TITLE>Download Timeout</TITLE>
1182 <PARA>      This group of controls serves to set the maximum time that
1183             is allowed for downloading a test to the target board. If
1184             the time is exceeded, the test will be deemed to have
1185             failed for reason of &ldquo;Download Timeout&rdquo; and
1186             the execution of that particular test will be abandoned.
1187             This option only applies to tests run on hardware, not to
1188             those executed in a simulator. Times are in units of
1189             elapsed seconds.</PARA>
1190 <PARA>Three options are available using the drop-down
1191             list:</PARA>
1192 <ITEMIZEDLIST>
1193 <LISTITEM>
1194 <PARA>Calculated from file size - an estimate of the maximum
1195 time required for download is made using the (stripped) executable
1196 size and the currently used baud rate</PARA>
1197 </LISTITEM>
1198 <LISTITEM>
1199 <PARA>                  Specified - a user-specified value may be entered in
1200 the adjacent edit box</PARA>
1201 </LISTITEM>
1202 <LISTITEM>
1203 <PARA>                  None - no maximum download time is to be applied.</PARA>
1204 </LISTITEM>
1205 </ITEMIZEDLIST>
1206 </SECT2>
1207 <SECT2>
1208 <TITLE>Run time Timeout</TITLE>
1209 <PARA>This group of controls serves to set the maximum time
1210             that is allowed for executing a test on the target board
1211             or in a simulator. If the time is exceeded, the test will
1212             be deemed to have failed for reason of
1213             &ldquo;Timeout&rdquo; and the execution of that particular
1214             test will be abandoned. In the case of hardware, the time
1215             is measured in elapsed seconds: in the case of a simulator
1216             it is in CPU seconds.</PARA>
1217 <PARA>Three options are available using the drop-down
1218           list:</PARA>
1219 <ITEMIZEDLIST>
1220 <LISTITEM>
1221 <PARA>None - no maximum download time is to be
1222                 applied.</PARA>
1223 </LISTITEM>
1224 <LISTITEM>
1225 <PARA>Specified - a user-specified value may be
1226                 entered in the adjacent edit box</PARA>
1227 </LISTITEM>
1228 <LISTITEM>
1229 <PARA>Default - a default value of 30 seconds is
1230                 used</PARA>
1231 </LISTITEM>
1232 </ITEMIZEDLIST>
1233 </SECT2>
1234 <SECT2>
1235 <TITLE>Connection</TITLE>
1236 <PARA>The <EMPHASIS>Connection</EMPHASIS> controls may be used
1237             to specify how the target board is to be accessed.</PARA>
1238
1239 <PARA>If the target board is connected using a serial cable, the <EMPHASIS>Serial</EMPHASIS> radio
1240 button should be checked. In this case you can select a port (COM1,
1241 COM2, &hellip;) and an appropriate baud rate using drop-list boxes.</PARA>
1242 <PARA>If the target board is accessed remotely using GDB remote
1243 protocol, the &ldquo;TCP/IP&rdquo; radio button should
1244 be checked. In this case you can select a host name and TCP/IP port
1245 number using edit boxes.</PARA>
1246 </SECT2>
1247 <SECT2>
1248 <TITLE>Executables Tab</TITLE>
1249 <PARA>This is used to adjust the set of tests available for execution.
1250 A check box against each executable name indicates whether that
1251 executable will be included when the <EMPHASIS>Run</EMPHASIS> button
1252 is pressed. The <EMPHASIS>Check All</EMPHASIS> and <EMPHASIS>Uncheck
1253 All</EMPHASIS> buttons may be used to check or uncheck all items.</PARA>
1254 <PARA>When the property sheet is first displayed, it will be pre-populated
1255 with those test executables that have been linked using the Build/Tests
1256 operation against the current configuration. </PARA>
1257 <FIGURE>
1258 <TITLE>Run tests </TITLE>
1259 <GRAPHIC ENTITYREF="graphic27"></GRAPHIC>
1260 </FIGURE>
1261 <PARA>You can right-click in the window to display a context menu
1262 containing <EMPHASIS>Add</EMPHASIS> and <EMPHASIS>Remove</EMPHASIS> items.
1263 Clicking <EMPHASIS>Remove</EMPHASIS>  will remove those executables
1264 selected. Clicking <EMPHASIS>Add</EMPHASIS> will display a dialog
1265 box that allows you to add to the set of items. Equivalently the <EMPHASIS>Add</EMPHASIS> button
1266 may be used to add executables, and the <EMPHASIS>DEL</EMPHASIS> key
1267 may be used to remove them.</PARA>
1268 <PARA>You can use the <EMPHASIS>Add from Folder</EMPHASIS> button
1269 to add a number of executables in a specified folder (optionally
1270 including subfolders, if you click on <EMPHASIS>Yes</EMPHASIS> when
1271 asked).</PARA>
1272 <FIGURE>
1273 <TITLE>Add files from folder </TITLE>
1274 <GRAPHIC ENTITYREF="graphic28"></GRAPHIC>
1275 </FIGURE>
1276
1277 <!--
1278 <PARA>The &ldquo;Add from subfolders&rdquo; check box should
1279 be checked if you wish the search for executables to descend into
1280 subfolders (in the example above the whole of the C drive would
1281 be searched).</PARA>
1282
1283 <PARA>The &ldquo;Files of type&rdquo; edit box should be used
1284 to specify the extension of those files to be matched &lsqb;for
1285 example, &ldquo;*.exe&rdquo;&rsqb;.</PARA>
1286 -->
1287 </SECT2>
1288 <SECT2>
1289 <TITLE>Output Tab</TITLE>
1290 <PARA>This tab is used to display the output from running tests.
1291 The output can be saved to a file or cleared by means of the popup
1292 menu displayed when you right-click in the window.</PARA>
1293 </SECT2>
1294 <SECT2>
1295 <TITLE>Summary Tab</TITLE>
1296 <PARA>This tab is used to display a record, in summary form, of
1297 those tests executed. For each execution, the following information
1298 is displayed:</PARA>
1299 <ITEMIZEDLIST>
1300 <LISTITEM>
1301 <PARA>                  <EMPHASIS>Time</EMPHASIS> - the date and time of execution</PARA>
1302 </LISTITEM>
1303 <LISTITEM>
1304 <PARA>                  <EMPHASIS>Host</EMPHASIS> - the host name of the machine
1305 from which the test was downloaded</PARA>
1306 </LISTITEM>
1307 <LISTITEM>
1308 <PARA>                  <EMPHASIS>Platform</EMPHASIS> - the platform on which
1309 the test was executed</PARA>
1310 </LISTITEM>
1311 <LISTITEM>
1312 <PARA>                  <EMPHASIS>Executable</EMPHASIS> - the executable (file
1313 name) of the test executed</PARA>
1314 </LISTITEM>
1315 <LISTITEM>
1316 <PARA>                  <EMPHASIS>Status</EMPHASIS> - the result of executing
1317 the test. This will be one of the following:</PARA>
1318 </LISTITEM>
1319 <LISTITEM>
1320 <PARA>                          Not started</PARA>
1321 </LISTITEM>
1322 <LISTITEM>
1323 <PARA>No result</PARA>
1324 </LISTITEM>
1325 <LISTITEM>
1326 <PARA>Inapplicable</PARA>
1327 </LISTITEM>
1328 <LISTITEM>
1329 <PARA>                          Pass</PARA>
1330 </LISTITEM>
1331 <LISTITEM>
1332 <PARA>DTimeout</PARA>
1333 </LISTITEM>
1334 <LISTITEM>
1335 <PARA>Timeout</PARA>
1336 </LISTITEM>
1337 <LISTITEM>
1338 <PARA>Cancelled</PARA>
1339 </LISTITEM>
1340 <LISTITEM>
1341 <PARA>                          Fail</PARA>
1342 </LISTITEM>
1343 <LISTITEM>
1344 <PARA>Assert fail</PARA>
1345 </LISTITEM>
1346 <LISTITEM>
1347 <PARA>                  <EMPHASIS>Size</EMPHASIS> - the size &lsqb;stripped/unstripped&rsqb; of
1348 the test executed</PARA>
1349 </LISTITEM>
1350 <LISTITEM>
1351 <PARA>                  <EMPHASIS>Download</EMPHASIS> - the download time &lsqb;mm:ss/mm:ss&rsqb; used.
1352 The first of the two times displayed represents the actual time
1353 used: the second the limit time.</PARA>
1354 </LISTITEM>
1355 <LISTITEM>
1356 <PARA>                  <EMPHASIS>Elapsed</EMPHASIS> - the elapsed time &lsqb;mm:ss&rsqb; used.</PARA>
1357 </LISTITEM>
1358 <LISTITEM>
1359 <PARA>                  <EMPHASIS>Execution</EMPHASIS> - the execution time
1360  &lsqb;mm:ss/mm:ss&rsqb; used. The first of the
1361 two times displayed represents the actual time used: the second
1362 the limit time.</PARA>
1363 </LISTITEM>
1364 </ITEMIZEDLIST>
1365 <PARA>The output can be saved to a file or cleared by means of the
1366 popup menu displayed when you right-click in the window.</PARA>
1367 </SECT2>
1368 </SECT1>
1369 </CHAPTER>
1370
1371 <!-- }}} -->
1372 <!-- {{{ Creating a Shell               -->
1373
1374 <CHAPTER id="config-tool-creating-a-shell">
1375 <TITLE>Creating a Shell</TITLE>
1376 <PARA>To call up a shell window, select <EMPHASIS>Tools</EMPHASIS>-&gt;<EMPHASIS>Shell</EMPHASIS>.
1377 Under Windows, you will get a Cygwin shell similar to the one below. On Linux, you will
1378 get a standard Linux shell window.</PARA>
1379 <GRAPHIC ENTITYREF="graphic29"></GRAPHIC>
1380 <SECT1 id="config-tool-keyboard-accelerators">
1381 <TITLE>Keyboard Accelerators</TITLE>
1382 <PARA>The following table presents the list of keyboard accelerators
1383 that can be used with the <application>Configuration Tool</application>. </PARA>
1384
1385 <table id="keyboard-accelerators"><title>Keyboard accelerators</title>
1386 <tgroup cols="2">
1387           <thead>
1388             <row>
1389               <entry>Accelerator</entry>
1390               <entry>Action</entry>
1391               <entry>Remarks</entry>
1392             </row>
1393           </thead>
1394 <tbody>
1395
1396 <row>
1397 <entry><emphasis>Alt+1</emphasis></entry>
1398 <entry>hide/show properties window</entry>
1399 <entry></entry>
1400 </row>
1401
1402 <row>
1403 <entry><emphasis>Alt+2</emphasis></entry>
1404 <entry>hide/show output window</entry>
1405 <entry></entry></row>
1406
1407 <row>
1408 <entry><emphasis>Alt+3</emphasis></entry>
1409 <entry>hide/show short description window</entry>
1410 <entry></entry></row>
1411
1412 <row>
1413 <entry><emphasis>Alt+4</emphasis></entry>
1414 <entry>hide/show conflicts window</entry>
1415 <entry></entry>
1416 </row>
1417
1418 <row>
1419 <entry><emphasis>Ctrl+A</emphasis></entry>
1420 <entry>select all</entry><entry>output
1421 window and in-cell editing</entry></row>
1422 <row>
1423 <entry><emphasis>Ctrl+C</emphasis></entry>
1424 <entry>copy</entry><entry>output window
1425 and in-cell editing</entry></row>
1426 <row>
1427 <entry><emphasis>Ctrl+F</emphasis></entry>
1428 <entry>Edit-&gt;Find</entry><entry></entry></row>
1429 <row>
1430 <entry><emphasis>Ctrl+N</emphasis></entry>
1431 <entry>File-&gt;New</entry><entry></entry></row>
1432 <row>
1433 <entry><emphasis>Ctrl+O</emphasis></entry>
1434 <entry>File-&gt;Open</entry><entry></entry></row>
1435 <row>
1436 <entry><emphasis>Ctrl+S</emphasis></entry>
1437 <entry>File-&gt;Save</entry><entry></entry></row>
1438 <row>
1439 <entry><emphasis>Ctrl+V</emphasis></entry>
1440 <entry>Paste</entry><entry>in-cell editing
1441 only</entry></row>
1442 <row>
1443 <entry><emphasis>Ctrl+X</emphasis></entry>
1444 <entry>Cut</entry><entry>in-cell-editing
1445 only</entry></row>
1446 <row>
1447 <entry><emphasis>Ctrl+Z</emphasis></entry>
1448 <entry>Undo</entry><entry>in-cell editing
1449 only</entry></row>
1450 <row>
1451 <entry><emphasis>F1</emphasis></entry>
1452 <entry>Context-sensitive help</entry><entry></entry></row>
1453 <row>
1454 <entry><emphasis>F3</emphasis></entry>
1455 <entry>Find next</entry><entry></entry></row>
1456 <row>
1457 <entry><emphasis>F7</emphasis></entry>
1458 <entry>Build-&gt;Library</entry><entry></entry></row>
1459 <row>
1460 <entry><emphasis>Shift+F7</emphasis></entry>
1461 <entry>Build-&gt;Tests</entry><entry></entry></row>
1462 <row>
1463 <entry><emphasis>Alt+F6</emphasis></entry>
1464 <entry>View-&gt;Next window</entry>
1465 <entry></entry></row>
1466 <row>
1467 <entry><emphasis>Shift+Alt+0</emphasis></entry>
1468 <entry>View-&gt;Previous window</entry>
1469 <entry></entry></row>
1470 <row>
1471 <entry><emphasis>Shift+Ins</emphasis></entry>
1472 <entry>Paste</entry><entry>in-cell editing
1473 only</entry></row>
1474 <row>
1475 <entry><emphasis>Shift+F10</emphasis></entry>
1476 <entry>Display context menu</entry><entry>Configuration
1477 window</entry></row>
1478 <row>
1479 <entry><emphasis>Alt+Enter</emphasis></entry>
1480 <entry>Display properties dialog box</entry>
1481 <entry>Configuration window</entry></row>
1482 <row>
1483 <entry><emphasis>&gt;</emphasis></entry>
1484 <entry>Increment item value</entry><entry>Configuration
1485 window</entry></row>
1486 <row>
1487 <entry>&lt;</entry><entry>Decrement
1488 item value</entry><entry>Configuration window</entry></row>
1489 <row>
1490 <entry><emphasis>Space</emphasis></entry>
1491 <entry>Toggle item value</entry><entry>Configuration
1492 window</entry></row>
1493           </tbody>
1494         </tgroup>
1495       </table>
1496
1497 </SECT1>
1498 </CHAPTER>
1499
1500 <!-- }}} -->
1501
1502
1503 </PART>
1504 <!-- Keep this comment at the end of the file
1505 Local variables:
1506 mode: sgml
1507 sgml-omittag:nil
1508 sgml-shorttag:t
1509 sgml-namecase-general:t
1510 sgml-general-insert-case:lower
1511 sgml-minimize-attributes:nil
1512 sgml-always-quote-attributes:t
1513 sgml-indent-step:2
1514 sgml-indent-data:t
1515 sgml-parent-document:("user-guide.sgml" "book" "part")
1516 sgml-exposed-tags:nil
1517 sgml-local-catalogs:nil
1518 sgml-local-ecat-files:nil
1519 End:
1520 -->