#1 Get started

For development, both Linux or Windows (using cygwin) host machine is possible. The best place to start with is the eCos "get started" web page. There, you will find links to download the complete setup (GNU cross compiler, configuration tools and eCos source code). Once you have extracted the compiler, source code and configuration tools, the eCos environement variable needs to be set to reflect the eCos package directory location ( .e.g. ECOS_REPOSITORY=/home/ecos/packages ). Additionally, the eCos compiler and utility tools ( ecosconfig and configtool ) shall be added to the PATH variable.

I. eCos source code

The source code installed from the eCos installation web page is release 3.0 (release date: March 2009). To have access to the latest features, fetch the source from the CVS or Mercurial public tree:
CVS: cvs -z3 -d :pserver:anoncvs@ecos.sourceware.org:/cvs/ecos co -P ecos
HG: hg clone http://hg-pub.ecoscentric.com/ecos/

II. eCos directory structure

The figure above presents the eCos directory structure.The eCos package database ( ecos.db ) is located under \ecos\packages\. The database file contains all the packages and targets configuration of the eCos repository and is used by eCos configuration tools. When adding a new package to eCos, the ecos.db file must be updated accordingly to reflect the location and name of the added package. It is also possible to maintain separate databases. To do so, create a new directory ( .e.g. \ecos\my_packages\ ) and a new database file ( .e.g. \ecos\my_packages\ecos.db ). The eCos repository variable must be updated to include the path to the new database ( .e.g. ECOS_REPOSITORY=/home/ecos/packages:/home/ecos/my_packages ). The order the databases are listed matters, in case of a duplicated package, the package will be extracted form the first location.

eCos uses a configuration file ( ecos.ecc ) to gather all the packages and configuration options of your project. This configuration file is generated either from the graphical tool ( configtool ) or the command line version ( ecosconfig ). When building eCos boot loader (Redboot), the compilation results in an elf and binary files. When building the eCos kernel (plus the required services etc...), the compilation results in a library including the linker script.

III. Redboot compilation example

As an example, lets compile Redboot for the AT91SAM7S evaluation boards using the command line interface.

First, create a new directory for eCos to import all the project structure.
$ mkdir at91_redboot
$ cd at91_redboot

Then create the configuration file for this target using the redboot template.
$ ecosconfig new at91sam7sek redboot

The ecos.ecc file has been created containing the target board configuration. You can edit it manually to change all specifics of your platform. You can check the validity of the configuration with:
$ ecosconfig check

To generate the directory structure, use:
$ ecosconfig tree

Finally compile redboot:
$ make

The resulting binary file ( redboot.bin ) is located in at91_redboot\install\bin\. The binary file can be progammed to the target using a FLASH programmer.

IV. eCos based application

In this example, we compile the default template for the AT91SAM7S evaluation boards using the command line interface. The default template includes the eCos kernel.
$ mkdir at91_default
$ cd at91_default
$ ecosconfig new at91sam7sek default
$ ecosconfig tree
$ make

The resulting library and linker script are located under at91_default\install\lib\

V. Adding a new package

Section under construction

VI. Tips

Consider updating the compiler prefix name according to your compiler name by editing the value of CYGBLD_GLOBAL_COMMAND_PREFIX in your ecos.ecc .

Packages are added using the command ecosconfig add PKG_NAME and removed using the command ecosconfig remove PKG_NAME

Most eCos packages come along with test applications. They are compiled with make tests and will be located under at91_default\install\tests\

Some targets with limited memory ressources can't link all the tests cases. To ignore linking errors when building the tests applications, use: make -s tests IGNORE_LINK_ERRORS=y

VII. Generate latest PDF documentation

Openjade and docbook are required to build the eCos PDF documentation.

To generate the latest user guide ( PDF), from ecos\doc\sgml\user-guide\:
$ make pdfa4

To generate the latest reference manual ( PDF), from ecos\doc\sgml\:
$ ./makemakefile
$ make pdfa4

When creating new eCos documentation, the doclist file from ecos\doc\sgml\ must be updated.