<!-- {{{ Banner                         --><!-- =============================================================== --><!--                                                                 --><!--     config-tool.sgml                                            --><!--                                                                 --><!--     eCos User Guide                                             --><!--                                                                 --><!-- =============================================================== --><!-- ####COPYRIGHTBEGIN####                                          --><!--                                                                 --><!-- =============================================================== --><!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  --><!-- This material may be distributed only subject to the terms      --><!-- and conditions set forth in the Open Publication License, v1.0  --><!-- or later (the latest version is presently available at          --><!-- http://www.opencontent.org/openpub/)                            --><!-- Distribution of the work or derivative of the work in any       --><!-- standard (paper) book form is prohibited unless prior           --><!-- permission obtained from the copyright holder                   --><!-- =============================================================== --><!--                                                                 -->      <!-- ####COPYRIGHTEND####                                            --><!-- =============================================================== --><!-- #####DESCRIPTIONBEGIN####                                       --><!--                                                                 --><!-- ####DESCRIPTIONEND####                                          --><!-- =============================================================== --><!-- }}} --><part ID="THE-ECOS-CONFIGURATION-TOOL"><TITLE>The eCos Configuration Tool</TITLE><!-- {{{ Getting Started                --><CHAPTER id="config-tool-getting-started"><TITLE>Getting Started</TITLE><!-- ====================================================================== -->    <SECT1 id="config-tool-getting-started-intro"><TITLE>Introduction</TITLE><PARA> The <productname>eCos</productname> <application>Configuration Tool</application> is used	  to tailor <productname>eCos</productname> at source level, prior to compilation or	  assembly, and provides a configuration file and a set of	  files used to build user applications. The sources and other	  files used for building a configuration are provided in a	  <EMPHASIS>component repository</EMPHASIS>, which is loaded	  when the <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION>	  is invoked. The component repository includes a set of files	  defining the structure of relationships between the	  <application>Configuration Tool</application> and other components, and is written in a	  <FIRSTTERM>Component Definition Language</FIRSTTERM> (<ACRONYM>CDL</ACRONYM>).	  For a description of the concepts underlying component	  configuration, see <xref linkend="cdl-concepts">.</PARA></SECT1><!-- ====================================================================== -->    <SECT1 id="config-tool-invoking"><TITLE>Invoking the <productname>eCos</productname> <application>Configuration Tool</application></TITLE><SECT2><TITLE>On Linux</TITLE><PARA>Add the <productname>eCos</productname> <application>Configuration Tool</application> install directory to your PATH, for example:</PARA><PROGRAMLISTING>export PATH=/opt/ecos/ecos<replaceable>&Version;</replaceable>/bin:$PATH</PROGRAMLISTING><PARA>You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repository location, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of thesetwo arguments is not significant. For example:</PARA><PROGRAMLISTING>configtool /opt/ecos/ecos<replaceable>&Version;</replaceable>/packages myfile.ecc</PROGRAMLISTING><PARA>The <application>Configuration Tool</application> will be displayed (see <xref linkend="figure-configuration-tool">).</PARA></SECT2><SECT2><TITLE>On Windows</TITLE><PARA>There are two ways in which to invoke the <productname>eCos</productname> <application>Configuration Tool</application>:</PARA><ITEMIZEDLIST><LISTITEM><PARA>	      from the desktop explorer or program set up at installation	      time (by default 	      <EMPHASIS>Start</EMPHASIS>	      -&gt;	      <EMPHASIS>Programs</EMPHASIS>	      -&gt;	      <EMPHASIS>eCos</EMPHASIS>	      -&gt;	      <EMPHASIS>Configuration Tool</EMPHASIS>	      ).</PARA></LISTITEM><LISTITEM><PARA>type (at a command prompt or in the 	    <EMPHASIS>Start</EMPHASIS>	    menu&rsquo;s 	    <EMPHASIS>Run</EMPHASIS>	    item): &lt;foldername&gt;&bsol;ConfigTool.exe where &lt;foldername&gt; is	    the full path of the directory in which you installed the <productname>eCos</productname>	    <application>Configuration Tool</application>.</PARA><!--<para>XXXXX Change location of configtool in line with installation              instructions. XXXXX</para>-->            </LISTITEM><LISTITEM><PARA>The 	    <application>Configuration Tool</application>	    will be displayed (see <xref linkend="figure-configuration-tool">).</PARA></LISTITEM></ITEMIZEDLIST><PARA>You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repositorylocation, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of thesetwo arguments is not significant. For example:</PARA><PROGRAMLISTING>configtool "c:\Program Files\eCos\packages" myfile.ecc</PROGRAMLISTING><!--                <para>XXXXX Change location of eCos in line with installation instructions. XXXXX        </para>-->        <PARA>If you invoke the configuration tool from the command line with<EMPHASIS>--help</EMPHASIS>, you will see this output:</PARA><PROGRAMLISTING>Usage: eCos Configuration Tool [-h] [-e] [-v] [-c] [input file 1] [input file 2]  -h  --help        	displays help on the command line parameters  -e  --edit-only   	edit save file only  -v  --version     	print version  -c  --compile-help	compile online help only</PROGRAMLISTING><PARA>This summarizes valid parameters and switches. Switches are shown withboth short form and long form.</PARA><PARA><EMPHASIS>--help</EMPHASIS> shows valid options and parameters, as above.</PARA><PARA><EMPHASIS>--edit-only</EMPHASIS> runs the <application>Configuration Tool</application> in a mode thatsuppresses creation of a build tree, in case you only want to create and edit save files.</PARA><PARA><EMPHASIS>--version</EMPHASIS> shows version and build date information, and exits.</PARA><PARA><EMPHASIS>--compile-help</EMPHASIS> compiles help contents files from the HTML documentationfiles that the tool finds in the <productname>eCos</productname> repository, and exits.</PARA><FIGURE id="figure-configuration-tool"><TITLE><application>Configuration Tool</application></TITLE><GRAPHIC ENTITYREF="graphic1"></GRAPHIC></FIGURE></SECT2></SECT1><!-- ====================================================================== -->        <SECT1 id="config-tool-component-repository"><TITLE>The Component Repository</TITLE><PARA>When you invoke the <productname>eCos</productname> <application>Configuration Tool</application>, it accesses the Component	  Repository, a read-only location of configuration	  information. For an explanation of &ldquo;Component	  Repository&rdquo; see <xref linkend="cdl-concepts">.</PARA><PARA>The <productname>eCos</productname> <application>Configuration Tool</application> will look	  for a component repository using (in descending order of preference):</PARA><ITEMIZEDLIST><LISTITEM><PARA>A location specified on the command line</PARA></LISTITEM><LISTITEM><PARA>The component repository most recently used by thecurrent user</PARA></LISTITEM><LISTITEM><PARA>An <productname>eCos</productname> distribution under <filename>/opt/ecos</filename> (underLinux) or a default location set by the installation procedure (underWindows)</PARA></LISTITEM><LISTITEM><PARA>User input</PARA></LISTITEM></ITEMIZEDLIST><PARA>The final case above will normally only occur if the previous	  repository has been moved or (under Windows) installation information stored in	  the Windows registry has been modified; it will result in a dialog boxbeing displayed that allows you to specify the repository location:</PARA><FIGURE><TITLE>Repository relocation dialog box</TITLE><GRAPHIC ENTITYREF="graphic2"></GRAPHIC></FIGURE><PARA>Note that in order to use the <productname>eCos</productname> <application>Configuration Tool</application> you are obliged to provide a	  valid repository location. </PARA><PARA>In the rare event that you subsequently wish to change	  the component location, select	  <EMPHASIS>Build</EMPHASIS>-&gt;<EMPHASIS>Repository</EMPHASIS> 	  and the above dialog box will then be displayed.</PARA><PARA>You can check the location of the current repository, the current save filepath, and the current hardware template and default package,by selecting <EMPHASIS>Help</EMPHASIS>-&gt;<EMPHASIS>Repository Information...</EMPHASIS>.A summary will be displayed.</PARA></SECT1><!-- ====================================================================== -->       <SECT1 ID="config-tool-documents"><TITLE><productname>eCos</productname> <application>Configuration Tool</application> Documents</TITLE><SECT2><TITLE>Configuration Save File</TITLE><PARA><productname>eCos</productname> configuration settings and other information	    (such as disabled conflicts) that are set using the	    <productname>eCos</productname> <application>Configuration Tool</application> are saved to	    a file between sessions. By default, when the	    <productname>eCos</productname> <application>Configuration Tool</application> is first	    invoked, it reads and displays information from the	    Component Registry and displays the information in an	    untitled blank document. You can perform the following	    operations on a document:</PARA><SECT3><TITLE>Save the currently active document</TITLE><PARA>Use the &ldquo;<EMPHASIS>File-&gt;Save</EMPHASIS>&rdquo; menu	    item or click the <EMPHASIS>Save Document</EMPHASIS> icon on the	    toolbar; if the current document is unnamed, you will be prompted	    to supply a name for the configuration save file.</PARA><FIGURE><TITLE>Save As dialog box</TITLE><GRAPHIC ENTITYREF="graphic3"></GRAPHIC></FIGURE></SECT3><SECT3><TITLE>Open an existing document</TITLE><PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>Open</EMPHASIS>,	    or click the <EMPHASIS>Open Document</EMPHASIS> icon on the toolbar.	    You will be prompted to supply a name for the configuration save	    file. </PARA><FIGURE><TITLE>Open dialog box</TITLE><GRAPHIC ENTITYREF="graphic4"></GRAPHIC></FIGURE></SECT3><SECT3><TITLE>Open a document you have used recently</TITLE><PARA>Click its name at the bottom of the	    <EMPHASIS>File</EMPHASIS> menu. </PARA><PARA>Documents may also be opened by:</PARA><ITEMIZEDLIST><LISTITEM><PARA>double-clicking a Configuration Save File in the desktopexplorer (Windows only);</PARA></LISTITEM><LISTITEM><PARA>invoking the <productname>eCos</productname><application>Configuration Tool</application>with the name of a Configuration File as command-line argument,or by creating a shortcut to the <productname>eCos</productname> <application>Configuration Tool</application> with such an argument(under Windows or a suitable Linux desktop environment).</PARA></LISTITEM></ITEMIZEDLIST></SECT3><SECT3><TITLE>Create a new blank document based on the Component	      Registry</TITLE><PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>New</EMPHASIS>,or click the <EMPHASIS>New Document</EMPHASIS> icon on the toolbar.</PARA></SECT3><SECT3><TITLE>Save to a different file name</TITLE><PARA>Select <EMPHASIS>File</EMPHASIS>-&gt;<EMPHASIS>Save		As</EMPHASIS>. You will be prompted to supply a new	      name for the configuration save file.</PARA></SECT3></SECT2><SECT2><TITLE>Build and Install Trees</TITLE><PARA>The location of the build and install trees are	    derived from the <productname>eCos</productname> save file name as illustrated in the	    following example:</PARA><PARA>Save file name = &ldquo;c:&bsol;My	    eCos&bsol;config1.ecc&rdquo;</PARA><PARA>Install tree folder = &ldquo;c:&bsol;My	    eCos&bsol;config1_install&rdquo;</PARA><PARA>Build tree folder = &ldquo;c:&bsol;My	    eCos&bsol;config1_build&rdquo;</PARA><PARA>These names are automatically generated from the name	    of the save file.</PARA><PARA>See also <xref linkend="cdl-concepts">.</PARA></SECT2></SECT1></CHAPTER><!-- }}} --><!-- {{{ Getting Help                   --><CHAPTER id="config-tool-getting-help"><TITLE>Getting Help</TITLE><PARA>The <productname>eCos</productname> <application>Configuration Tool</application> containsseveral methods for accessing online help.</PARA><!-- ================================================== --><SECT1 id="config-tool-context-help-dialogs"><TITLE>Context-sensitive Help for Dialogs</TITLE><PARA>Most dialogs displayed by the <productname>eCos</productname> <application>Configuration Tool</application> are suppliedwith context-sensitive help. You can then get help relatingto any control within the current dialog box by</PARA><ITEMIZEDLIST><LISTITEM><PARA>Right-clicking the control (or pressing 	      <EMPHASIS>F1</EMPHASIS>	      )</PARA><PARA>A &ldquo;What&rsquo;s This?&rdquo; popup menu will	  be displayed. Click the menu to display a brief description of the	  function of the selected control.</PARA></LISTITEM><LISTITEM><PARA>Clicking the question mark icon in the dialog	    caption bar (Windows) or the question mark button on the dialog (Linux).</PARA><PARA>A question mark cursor will be displayed. Click on	      any control to display a brief description of its	      function.</PARA></LISTITEM></ITEMIZEDLIST><PARA>Some dialogs may have a <EMPHASIS>Help</EMPHASIS>	  button. You can press this to display a more general	  description of the function of the dialog box as a whole.	  This help will be in HTML form; for more information, see	  below.</PARA></SECT1><!-- ================================================== --><SECT1 id="config-tool-context-help-otherwin"><TITLE>Context-sensitive Help for Other Windows</TITLE><PARA>In the <EMPHASIS>Help</EMPHASIS> menu, click	  <EMPHASIS>Help On...</EMPHASIS><!-- (or press	  <EMPHASIS>F1</EMPHASIS>)-->and then click on a window (or click on the arrow/question mark buttonon the toolbar, then click on a window). A small popup window page describing thewindow will be displayed. The same thing can be achieved by right-clickingon a window and clicking on <EMPHASIS>What's This?</EMPHASIS>.<!--	  This help will normally be in HTML format; for more	  information, see <xref linkend="methods-of-displaying-html-help">.--></PARA></SECT1><SECT1 id="config-tool-context-help-config-items"><TITLE>Context-sensitive Help for Configuration Items</TITLE><PARA>In the configuration window, right-click on a configurationitem (or use <EMPHASIS>Shift+F10</EMPHASIS>). A contextmenu will be displayed; select <EMPHASIS>Visit Documentation</EMPHASIS> to display the page in the <productname>eCos</productname> documentation that most closelycorresponds to the selected item.</PARA></SECT1><SECT1 id="methods-of-displaying-html-help"><TITLE>Methods of Displaying HTML Help</TITLE>