Mercurial > ecos

comparison doc/sgml/user-guide/config-tool.sgml @ 208:e0c0827131d1 ecos

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