<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     configuration.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="configuration-and-the-package-repository">
<TITLE>Configuration and the Package Repository</TITLE>
<PARTINTRO>
<PARA>The following chapters contain information on running
	<COMMAND>ecosconfig</COMMAND> (the command line tool that
	manipulates configurations and constructs build trees) and on
	managing a source repository across multiple versions of
	<productname>eCos</productname>. </PARA>
</PARTINTRO>
<CHAPTER id="manual-configuration">
<TITLE>Manual Configuration</TITLE>

    <PARA><productname>eCos</productname> developers will generally use the graphical
      Configuration Tool for configuring an <productname>eCos</productname> system and building
      the target library. However, some user prefer to use command
      line tools. These command line tools can also be used for batch
      operations on all platforms, for example as part of a nightly
      rebuild and testing procedure.
    </PARA>

<PARA>In the current release of the system the command line tools
      do not provide exactly the same functionality as the graphical
      tool. Most importantly, there is no facility to resolve
      configuration conflicts interactively.</PARA>
<PARA>The <productname>eCos</productname> configuration system, both graphical and command
      line tools, are under constant development and enhancement.
      Developers should note that the procedures described may change
      considerably in future releases. </PARA>

<SECT1 id="directory-tree-structure">
<TITLE>Directory Tree Structure</TITLE>
<PARA>When building <productname>eCos</productname> there are three main directory trees to
	consider: the source tree, the build tree, and the install
	tree.</PARA>
<PARA>The source tree, also known as the component repository,
	  is read-only. It is possible to use a single component
	  repository for any number of different configurations, and
	  it is also possible to share a component repository between
	  multiple users by putting it on a network drive.</PARA>
<PARA>The build tree contains everything that is specific to a
	  particular configuration, including header and other files
	  that contain configuration data, and the object files that
	  result from compiling the system sources for this
	  configuration. </PARA>
<PARA>The install tree is usually located in the <filename>install</filename> subdirectory
of the build tree. Once an <productname>eCos</productname> system has been built, the install
tree contains all the files needed for application development including
the header files and the target library. By making copies of the
install tree after a build it is possible to separate application
development and system configuration, which may be desirable for
some organizations. </PARA>
</SECT1>

<SECT1 id="creating-build-tree">
<TITLE>Creating the Build Tree</TITLE>
<PARA>Generating a build tree is a non-trivial operation and
	  should not be attempted manually. Instead, <productname>eCos</productname> is shipped
	  with a tool called <COMMAND>ecosconfig</COMMAND> that should
	  be used to create a build tree.</PARA>
<PARA>Usually <command>ecosconfig</command> will be
run inside the build tree itself. If you are creating a new build
tree then typically you will create a new empty directory using
the <command>mkdir</command> command, <command>cd</command> into
that directory, and then invoke <command>ecosconfig</command> to
create a configuration. By default, the configuration is stored
in a file <filename>ecos.ecc</filename> in the current
directory. The configuration may be modified by editing this file directly. <command>ecosconfig</command> itself
deals with a number of coarse-grained configuration options such
as the target platform and the packages that should be used.</PARA>
<PARA>The <command>ecosconfig</command> tool is also
used subsequently to generate a build tree for a configuration.
Once a build tree exists, it is possible to run <command>ecosconfig</command> again
inside the same build tree. This will be necessary if your wish
to change some of the configuration options.</PARA>
<PARA><COMMAND>ecosconfig</COMMAND> does not generate
the top-level directory of the build tree; you must do this
	yourself. </PARA>
<SCREEN>$ mkdir ecos-work
$ cd ecos-work</SCREEN>
<PARA>The next step is to run <COMMAND>ecosconfig</COMMAND>: </PARA>
<SCREEN>$ ecosconfig &lt;qualifiers&gt; &lt;command&gt;</SCREEN>
<SECT2>
<TITLE>ecosconfig qualifiers</TITLE>
<PARA>The available command line qualifiers for
	    <COMMAND>ecosconfig</COMMAND> are as follows. Multiple
	    qualifiers may be used on the command line:
	  </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><OPTION>--help</OPTION></TERM>
<LISTITEM>
<PARA>Provides basic usage guidelines for the
	      available commands and qualifiers.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--config=&lt;file&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies an <productname>eCos</productname> configuration save file for
		  use by the tool. By default, the file
		  <filename>ecos.ecc</filename> in the
		  current directory is used. Developers may prefer to
		  use a common location for all their <productname>eCos</productname>
		  configurations rather than keep the configuration
		  information in the base of the build tree.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--prefix=&lt;dir&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies an alternative location for the
		  install tree. By default, the install tree resides
		  inside the <filename>install</filename>
		  directory in the build tree. Developers may prefer
		  to locate the build tree in a temporary file
		  hierarchy but keep the install tree in a more
		  permanent location.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--srcdir=&lt;dir&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies the location of the component
		  repository. By default, the tool uses the location
		  specified in the
		  <REPLACEABLE>ECOS_REPOSITORY</REPLACEABLE>
		  environment variable. Developers may prefer to use
		  of this qualifier if they are working with more than
		  one repository.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--no-resolve</OPTION></TERM>
<LISTITEM>
<PARA>Disables the implicit resolution of conflicts
		  while manipulating the configuration data.
		  developers may prefer to resolve conflicts by
		  editing the <productname>eCos</productname> configuration save file
		  manually.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--ignore-errors</OPTION></TERM>
<TERM><OPTION>-i</OPTION></TERM>
<LISTITEM>
<PARA>
By default, ecosconfig will exit with an error code if the current
configuration contains any conflicts, and it is not possible to
generate or update a build tree for such configurations. This
qualifier causes ecosconfig to ignore such problems, and hence it is
possible to generate a build tree even if there are still
conflicts. Of course, there are no guarantees that the resulting
system will actually do anything.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--verbose</OPTION></TERM>
<TERM><OPTION>-v</OPTION></TERM>
<LISTITEM>
<PARA>
Display more information.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--quiet</OPTION></TERM>
<TERM><OPTION>-q</OPTION></TERM>
<LISTITEM>
<PARA>
Display less information.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
The <OPTION>--config</OPTION>, <OPTION>--prefix</OPTION> and
<OPTION>--srcdir</OPTION> qualifiers can also be written with two arguments,
for example:
</para>
<SCREEN>
ecosconfig --srcdir <REPLACEABLE>&lt;dir&gt;</REPLACEABLE> ...
</SCREEN>
<para>
This simplifies filename completion with some shells.
</PARA>
</SECT2>
<SECT2>
<TITLE>ecosconfig commands</TITLE>
<PARA>The available commands for
	    <COMMAND>ecosconfig</COMMAND> are as
	    follows:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><COMMAND>list</COMMAND></TERM>
<LISTITEM>
<PARA>Lists the available packages, targets and
		  templates as installed in the <productname>eCos</productname> repository.
		  Aliases and package versions are also
		  reported.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>new &lt;target&gt; [&lt;template&gt; [&lt;version&gt;]]</COMMAND></TERM>
<LISTITEM>
<PARA>Creates a new <productname>eCos</productname> configuration for
		  the specified target hardware and saves it. A
		  software template may also be specified. By default,
		  the template named &lsquo;default&rsquo; is used. If
		  the template version is not specified, the latest
		  version is used.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>target &lt;target&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Changes the target hardware selection
		  for the <productname>eCos</productname> configuration. This has the effect of
		  unloading packages supporting the target selected
		  previously and loading the packages which support
		  the new hardware. This command will be used
		  typically when switching between a simulator and
		  real hardware.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>template &lt;template&gt; [&lt;version&gt;]</COMMAND></TERM>
<LISTITEM>
<PARA>Changes the template selection for the <productname>eCos</productname>
		  configuration. This has the effect of unloading
		  packages specified by the template selected
		  previously and loading the packages specified by the
		  new template. By default, the latest version of the
		  specified template is used.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>remove &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Removes the specified packages from the <productname>eCos</productname>
		  configuration. This command will be used typically
		  when the template on which a configuration is based
		  contains packages which are not required.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>add &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Adds the specified packages to the <productname>eCos</productname> configuration. This
command will be used typically when the template on which a
configuration is based does not contain all the packages which are
required.For example, add-on packages provided by third parties will
not be known to the standard templates, so they will have to be added
explicitly. </PARA>
</LISTITEM>
</VARLISTENTRY>