<VARLISTENTRY>
<TERM><COMMAND>version &lt;version&gt; &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Selects the specified version of a
		  number of packages in the <productname>eCos</productname> configuration. By
		  default, the most recent version of each package is
		  used. This command will be used typically when an
		  older version of a package is required.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>check</COMMAND></TERM>
<LISTITEM>
<PARA>Presents the following information
		  concerning the current configuration:</PARA>
<ORDEREDLIST>
<LISTITEM>
<PARA>the selected target hardware</PARA>
</LISTITEM>
<LISTITEM>
<PARA>the selected template</PARA>
</LISTITEM>
<LISTITEM>
<PARA>additional packages</PARA>
</LISTITEM>
<LISTITEM>
<PARA>removed packages</PARA>
</LISTITEM>
<LISTITEM>
<PARA>the selected version of packages
		      where this is not the most recent
		      version</PARA>
</LISTITEM>
<LISTITEM>
<PARA>conflicts in the current configuration</PARA>
</LISTITEM>
</ORDEREDLIST>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>resolve</COMMAND></TERM>
<LISTITEM>
<PARA>Resolves conflicts identified in the
		  current <productname>eCos</productname> configuration by invoking an inference
		  capability. Resolved conflicts are reported, but not
		  all conflicts may be resolvable. This command will
		  be used typically following manual editing of the
		  configuration.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>export &lt;file&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Exports a minimal <productname>eCos</productname> configuration
		  save file with the specified name. This file
		  contains only those options which do not have their
		  default value. Such files are used typically to
		  transfer option values from one configuration to
		  another.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>import &lt;file&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Imports a minimal <productname>eCos</productname> configuration
		  save file with the specified name. The values of
		  those options specified in the file are applied to
		  the current configuration.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>tree</COMMAND></TERM>
<LISTITEM>
<PARA>Generates a build tree based on the current <productname>eCos</productname>
		  configuration. This command will be used typically
		  just before building <productname>eCos</productname>.Normally a build tree can
only be generated if if the configuration has no unresolved
conflicts, but <OPTION>--ignore-errors</OPTION> can be used to override
this.</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</SECT2>
</SECT1>
<SECT1 id="conflicts-and-constraints">
<TITLE>Conflicts and constraints</TITLE>
<PARA>Configuration options are not completely independent. For example
the C library's <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>
functions rely on the math library package to provide certain functionality. If the math library package is removed then the C
library can no longer provide these functions. Each package describes constraints like these in CDL <EMPHASIS>"requires"</EMPHASIS> properties. If a constraint is not satisfied, then the configuration contains a conflict. For any given conflict there can
be several resolution options. For example, it would be possible to add the math library package back to the
configuration, or to disable the <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION> functions.</PARA>
<PARA>
The <productname>eCos</productname> configuration tools will report any conflicts in the current configuration. If there are any such conflicts
then the configuration is usually unsafe and it makes no sense to build and run <productname>eCos</productname> in such circumstances. In fact,
any attempt at building <productname>eCos</productname> is likely to fail. In exceptional cases it is possible to override this by using e.g. the
<OPTION>--ignore-errors</OPTION> qualifier with ecosconfig. 
</PARA>
<PARA>
Many constraints are fairly simple in nature, and the configuration tools contain an inference engine which can
resolve the associated conflicts automatically. For example, if the math library package is removed then the
inference engine can resolve the resulting conflict by disabling the configuration option for <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>. All
such changes will be reported. Sometimes the inference engine cannot resolve a conflict, for example it is not
allowed to override a change that has been made explicitly by the user. Sometimes it will find a solution which does
not match the application's requirements. 
</PARA>
<PARA>
A typical session involving conflicts would look something like this: 
<SCREEN>
$ ecosconfig new pid
</SCREEN>This creates a new configuration with the default template. For most targets this will not result in any conflicts,
because the default settings for the various options meet the requirements of the default template.
</PARA><PARA> For some targets
there may be conflicts and the inference engine would come into play. 
<SCREEN>
$ ecosconfig remove libm 
U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 
U CYGFUN_LIBC_strtod, new inferred value 0 
U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 
</SCREEN>
ecosconfig reports that this change caused three conflicts, all in the C library. The inference engine was able to
resolve all the conflicts and update the relevant configuration options accordingly. </PARA>
<PARA>To suppress the inference engine <OPTION>--no-resolve</OPTION> can be used: 
<SCREEN>
$ ecosconfig new pid
$ ecosconfig --no-resolve remove libm 
C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
</SCREEN>
Three unresolved conflicts are reported.
</PARA>
<PARA>The <COMMAND>check</COMMAND> command can be used to get the current state of the
configuration, and the <OPTION>--verbose</OPTION> qualifier will provide additional information: </PARA>
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check 
Target: pid 
Template: default 
Removed:
 CYGPKG_LIBM 
3 conflict(s): 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
 Possible solution: 
    CYGFUN_LIBC_strtod -> 0 
    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 
C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
 Possible solution: 
    CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0 
C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
 Possible solution: 
    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 
</SCREEN>
<PARA>
If the proposed solutions are acceptable, the resolve command can be used to apply them: 
<SCREEN>
$ ecosconfig resolve 
U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 
U CYGFUN_LIBC_strtod, new inferred value 0 
U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 
</SCREEN></PARA>
<PARA>The current configuration is again conflict-free and it is possible to generate a build tree. The <OPTION>--quiet</OPTION> qualifier can
be used to suppress the change messages, if desired.
</PARA><PARA>
When changing individual configuration options by editing the ecos.ecc file (as described below), the resulting
system should be checked and any problems should be resolved. For example, if CYGFUN_LIBC_strtod is
explicitly enabled in the savefile:
<SCREEN>
$ edit ecos.ecc
$ ecosconfig check 
Target: pid 
Template: default 
Removed: 
    CYGPKG_LIBM 
1 conflict(s): 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
$ ecosconfig resolve 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
</SCREEN>
In this case the inference engine cannot resolve the conflict automatically because that would involve changing a
user setting. Any attempt to generate a build tree will fail: 
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc tree 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
Unable to generate build tree, this configuration still contains conflicts.
Either resolve the conflicts or use --ignore-errors 
</SCREEN>
</PARA><PARA>
It is still possible to generate a build tree: 
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
$ make 
</SCREEN>
In this case <productname>eCos</productname> will fail to build. In other cases of unresolved conflicts <productname>eCos</productname> may build, but may not run. In
general all conflicts should be resolved by editing the <FILENAME>ecos.ecc</FILENAME> file, by letting the inference engine make appropriate
changes, or by other means, before any attempt is made to build or run <productname>eCos</productname>. 
</PARA>
</SECT1>
<SECT1 id="building-the-system">
<TITLE>Building the System</TITLE>
<PARA>Once a build tree has been generated with
	  <COMMAND>ecosconfig</COMMAND>, <!-- <index></index>
	  -->building <productname>eCos</productname> is straightforward:</PARA>
<SCREEN>$ make</SCREEN>
<PARA>The build tree contains the subdirectories, makefiles,
	  and everything else that is needed to generate the default
	  configuration for the selected architecture and platform.
	  The only requirement is that the tools needed for that
	  architecture, for example
	  <COMMAND>powerpc-eabi-g++</COMMAND>,
	  are available using the standard search path. If this is not
	  the case then the <COMMAND>make</COMMAND> will
	  fail with an error message. If you have a multiprocessor
	  system then it may be more efficient to use:</PARA>
<SCREEN>$ make -j <REPLACEABLE>n</REPLACEABLE></SCREEN>
<PARA>where <REPLACEABLE>n</REPLACEABLE> is equal to the
	  number of processors on your system.</PARA>
<PARA>Once the <COMMAND>make</COMMAND> process
	  has completed, the install tree will contain the header
	  files and the target library that are needed for application
	  development. </PARA>
<PARA>It is also possible to build the system&rsquo;s test cases
for the current configuration:</PARA>
<SCREEN>$ make tests</SCREEN>
<PARA>The resulting test executables will end up in a
	  <FILENAME>tests</FILENAME> subdirectory of the
	  <!-- <index></index> -->install tree. </PARA>
<PARA>If disk space is scarce then it is possible to make the copy
of the install tree for application development purposes, and then
use: </PARA>
<SCREEN>$ make clean</SCREEN>
<PARA>The build tree will now use up a minimum of disk space &mdash; the
bulk of what is left consists of configuration header files that
you may have edited and hence should not be deleted automatically.
However, it is possible to rebuild the system at any time without
re-invoking <COMMAND>ecosconfig</COMMAND>, just by
running <COMMAND>make</COMMAND> again. </PARA>
<PARA>Under exceptional circumstances it may be necessary to run <COMMAND>make
clean</COMMAND> for other reasons, such as when a new release
of the toolchain is installed. The toolchain includes a number of
header files which are closely tied to the compiler, for example <filename>limits.h</filename>,
and these header files are not and should not be duplicated by <productname>eCos</productname>.
The makefiles perform header file dependency analysis, so that when
a header file is changed all affected sources will be rebuilt during
the next <COMMAND>make</COMMAND>. This is very useful
when the configuration header files are changed, but it also means
that a build tree containing information about the locations of
header files must be rebuilt. If a new version of the toolchain
is installed and the old version is removed then this location information
is no longer accurate, and <COMMAND>make</COMMAND> will
complain that certain dependencies cannot be satisfied. Under such circumstances
it is necessary to do a <COMMAND>make clean</COMMAND> first. </PARA>
</SECT1>
<SECT1 id="ecos-packages">
<TITLE>Packages</TITLE>
<PARA><productname>eCos</productname> is a component architecture. The system comes as a
	  number of <!-- <index></index> -->packages which can be
	  enabled or disabled as required, and new packages can be
	  added as they become available. Unfortunately, the packages
	  are not completely independent: for example the &micro;ITRON
	  compatibility package relies almost entirely on
	  functionality provided by the kernel package, and it would
	  not make sense to try to build &micro;ITRON if the kernel
	  was disabled. The C library has fewer dependencies: some
	  parts of the C library rely on kernel functionality, but it
	  is possible to disable these parts and thus build a system
	  that has the C library but no kernel. The
	<command>ecosconfig</command> tool has the capability of
	    checking that all the dependencies are satisfied, but it
	    may still be possible to produce configurations that will
	    not build or (conceivably) that will build but not run.
	    Developers should be aware of this and take appropriate
	    care.</PARA>
<PARA>By default, <!-- <index></index> --><command>ecosconfig</command> will
include all packages that are appropriate for the specified hardware
in the configuration. The common <!-- <index></index> -->HAL package and
the <productname>eCos</productname> infrastructure must be present in every configuration. In
addition, it is always necessary to have one architectural HAL package
and one platform HAL package. Other packages are optional, and can
be added or removed from a configuration as required.</PARA>
<PARA>The application may not require all of the packages; for example,
it might not need the &micro;ITRON compatibility
package, or the floating point support provided by the math library.
There is a slight overhead when <productname>eCos</productname> is built because the packages
will get compiled, and there is also a small disk space penalty.
However, any unused facilities will get stripped out at link-time,
so having redundant packages will not affect the final executable. </PARA>