Creating the Build Tree

Generating a build tree is a non-trivial operation and should not be attempted manually. Instead, eCos is shipped with a tool called ecosconfig that should be used to create a build tree.

Usually ecosconfig 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 mkdir command, cd into that directory, and then invoke ecosconfig to create a configuration. Alternatively you can also use the --builddir option to specify the build directory if the build directory is to be stored in a location other than the current directory. By default, the configuration is stored in a file ecos.ecc in the current directory. The configuration may be modified by editing this file directly. ecosconfig itself deals with a number of coarse- grained configuration options such as the target platform and the packages that should be used.

The ecosconfig tool is also used subsequently to generate a build tree for a configuration. Once a build tree exists, it is possible to run ecosconfig again inside the same build tree. This will be necessary if your wish to change some of the configuration options.

ecosconfig does not generate the top-level directory of the build tree; you must do this yourself.

$ mkdir ecos-work
$ cd ecos-work

The next step is to run ecosconfig:

$ ecosconfig <qualifiers> <command>

ecosconfig qualifiers

The available command line qualifiers for ecosconfig are as follows. Multiple qualifiers may be used on the command line:


Provides basic usage guidelines for the available commands and qualifiers.


Specifies an eCos configuration save file for use by the tool. By default, the file ecos.ecc in the current directory is used. Developers may prefer to use a common location for all their eCos configurations rather than keep the configuration information in the base of the build tree.


Specifies an alternative location for the install tree. By default, the install tree resides inside the install 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.


Specifies the location of the component repository. By default, the tool uses the location specified in the ECOS_REPOSITORY environment variable. Developers may prefer to use of this qualifier if they are working with more than one repository.


Specifies an alternative location for the build directory. By default, the build directory will be created inside the current directory. Developers may prefer to locate the build tree in a temporary file hierarchy but keep the install tree in a more permanent location.


Disables the implicit resolution of conflicts while manipulating the configuration data. developers may prefer to resolve conflicts by editing the eCos configuration save file manually.

--ignore-errors, -i

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.

--compat, -c

This option invokes the compatability mode of ecosconfig with the GUI configtool. It sets both the build and install directories of ecosconfig to the directories, relative to the configuration file, that would be created and used by the GUI configtool respectively. This option therefore cannot be used in conjuction with either the --prefix=<dir> or --builddir=<dir> options. This option is useful to application developers that regularly switch between using the CLI and GUI configuration tools.

--long, -l

Display long listing of packages, templates, targets and attributes.

--verbose, -v

Display more information.

--quiet, -q

Display less information.

The --config, --prefix and --srcdir qualifiers can also be written with two arguments, for example:

ecosconfig --srcdir <dir> ...

This simplifies filename completion with some shells.

ecosconfig commands

The available commands for ecosconfig are as follows:

list [<packages> | <templates> | <targets>]

Lists the available packages, targets and templates as installed in the eCos repository. The additional options <packages>, <templates> and <targets> restrict output to packages, templates and targets respectively and include the --long option support to provide additional information. Aliases and package versions are also reported.

new <target> [<template> [<version>]]

Creates a new eCos configuration for the specified target hardware and saves it. A software template may also be specified. By default, the template named ‘default’ is used. If the template version is not specified, the latest version is used.

target <target>

Changes the target hardware selection for the eCos 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.

Note: When switching targets between minor CPU variants, users are advised that inferred changes within common hardware packages are not reset or re-inferred unless a conflict arises as a result of the switch. For example, while a template may contain the SPI package, this package may be disabled in a configuration through inference as a result of the initial hardware lacking an SPI device. However, when switching to a processor variant with more cells (device support), such as one that includes an SPI device, the SPI package could remain disabled when the configuration is switched to the more superior variant unless it is marked as required within the CDL (i.e. it would conflict). Users are therefore advised that switching targets within a configuration may have unanticipated results and are recommended to use the process described in the Section called Switching Targets, Repositories and Versions in Chapter 15.

template <template> [<version>]

Changes the template selection for the eCos 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.

add <packages>

Adds the specified packages to the eCos 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.

remove <packages>

Removes the specified packages from the eCos configuration. This command will be used typically when the template on which a configuration is based contains packages which are not required.

packages [loaded | active]

Provides package information regarding the eCos configuration rather than the eCos repository (as provided by the list command). The optional argument loaded (the default) will list what packages have been loaded into the eCos configuration while active will list active packages. The -- long option may also be included to provide additional information.

present <package> [<package> ...]

Tests for the presense of the packages and returns a status code of 0 if all the packages are present in the eCos configuration, or an error if not. This is useful for automated scripting of the creation of eCos configurations from the command line.

version <version> <packages>

Selects the specified version of a number of packages in the eCos 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.


Presents the following information concerning the current configuration:

  1. the selected target hardware

  2. the selected template

  3. additional packages

  4. removed packages

  5. the selected version of packages where this is not the most recent version

  6. conflicts in the current configuration


Resolves conflicts identified in the current eCos 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.

export <file>

Exports a minimal eCos 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.

import <file>

Imports a minimal eCos configuration save file with the specified name. The values of those options specified in the file are applied to the current configuration.


Generates a build tree based on the current eCos configuration. This command will be used typically just before building eCos.Normally a build tree can only be generated if if the configuration has no unresolved conflicts, but --ignore-errors can be used to override this.


User comments within eCos configurations are not preserved when modified with the configtool or ecosconfig. However, from eCosPro version 4.0 and above, the eCos Configuration file (normal prefix <.ecc>) the eCos Configuration file can contain user comments. The are located at the top of the Configuration file and can be fetched with this command. For example, both tools use User comments to store additional matedata information such as the name of the eCosPro profile used to generate the configuration. If no profile information is provided to either the configtool or ecosconfig, both tools will use this comment to set a default profile for the configuration of the profile is valid.

add_comment <comment>

Append the comment <comment> to the user comments within the eCos configuration file.

set_comment <comment>

Replaces the user comments within the eCos configuration file with <comment>. This will erase any profile indicators stored within the configuration file when the eCos configuration was created.

Documentation license for this page: Open Publication License