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 script called pkgconf.tcl that should be used to create a build tree.

pkgconf.tcl is implemented in the scripting language Tcl/Tk, so it must be run from inside a suitable Tcl interpreter (Tcl 8.0 or later). Most Linux users will have an interpreter pre-installed, usually in /usr/bin/tclsh; if the installed interpreter is not version 8.0 or later then this will be detected at run-time and remedial action will be suggested. For Windows users, a suitable interpreter cygtclsh80.exe is shipped with the system as part of the Cygwin tools.

The command used to invoke pkgconf.tcl is:

$tclsh BASE_DIR/pkgconf.tcl <arguments>

Usually the pkgconf.tcl script 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 pkgconf.tcl. Once a build tree exists, it is possible to run pkgconf.tcl again inside the same build tree and change some of the coarse-grained configuration options; for example, it is possible to switch between a simulator and an evaluation board.

Given this build tree it is then possible to build the system and its testcases, and to change fine-grained configuration options. pkgconf.tcl itself deals with a number of coarse-grained configuration options such as the target platform and the packages that should be used.

pkgconf.tcl 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 the pkgconf.tcl script using the Tcl interpreter. Remembering that BASE_DIR is the base directory in which you installed eCos, on a UNIX machine the command for this would be:

$ tclsh BASE_DIR/pkgconf.tcl <arguments>

Under Windows NT, with the bash shell, the equivalent command would be:

$ cygtclsh80 BASE_DIR/pkgconf.tcl <arguments>

In the remainder of this chapter the UNIX version will be used for all examples, since eCos developers with Windows NT hosts are more likely to use the Configuration Tool.

pkgconf.tcl arguments

The available command line arguments for pkgconf.tcl are as follows:

--help

Provide basic online help for the available options

--target=<arch>

Select a specific architecture. The architectures available will depend on the exact release of eCos that you are using, and is defined in the file BASE_DIR/targets. If your release only supports a single architecture then this argument is optional since pkgconf.tcl will default to that architecture.

--targets

Use this to list of the supported architectures and the platforms available for each platform.

--platform=<platform>

Select a specific platform for the current architecture, for example “sim”. The default platform for a given architecture is the first one listed in the targets file. Use the option --targets to list the available architectures and platforms.

--startup=<value>

For some platforms it is possible to start up eCos in a number of ways. For a ROM start-up the application linked with eCos will typically be burned into EPROM’s and eCos will start up when the board is powered up. For a RAM start-up the application linked with eCos will be downloaded into a board that is already powered up and running a ROM monitor program of some sort. The default setting for all platforms is a RAM start-up.

--disable-<package>

In the current release all packages relevant to the architecture and platform are enabled by default. To disable a given package it is necessary to pass the appropriate command line argument to pkgconf.tcl. For example, to configure a system without the µITRON package use:

$ tclsh BASE_DIR/pkgconf.tcl --disable-uitron <other options>

Not all packages are completely self-contained. For example, there are routines in the C library such as strtod() which perform floating point operations and hence require the math library to be present. Therefore it is not sufficient to simply disable the math library using command line arguments to pkgconf, it is also necessary to change a number of fine-grained configuration options for the C library after running pkgconf.tcl.

--enable-<package>

If a given package has been disabled in an existing build tree and must now be reenabled, run pkgconf.tcl again using the --enable argument. For example, to reenable the µITRON package use the following command:

$ tclsh BASE_DIR/pkgconf.tcl --enable-uitron <other options>

--<package>-version=v0_4

As additional releases of the eCos system are made there may be multiple versions of a given package available. By default pkgconf.tcl will always use the most recent version of a given package, but if you want to use an older version of a package you can pass an appropriate argument to pkgconf.tcl. For example, to select a specific version of the µITRON package, use the following command:

$  tclsh BASE_DIR/pkgconf.tcl --uitron-version=v0_4 <other options>

--packages

Use this option to list the available packages and the available versions for each package.

--defaults

When pkgconf.tcl is first used to create a build tree it will save the various coarse grained configuration settings in a file pkgconf.sav. If pkgconf.tcl is run again inside the same build tree to change one of these settings then the script will read in the save file. The command line option --defaults causes the script to ignore the settings in the save file and apply the default settings instead.

--srcdir=<dir>

Typically the pkgconf.tcl script resides at the top level of the eCos component repository, and hence the script can identify the location of the component repository by examining its own pathname. If it is necessary to use an alternative eCos source tree, use the --srcdir command line argument, for example:

$ tclsh BASE_DIR/pkgconf.tcl --srcdir=/tmp/new-ecossrc <other options>

--builddir=<dir>

By default pkgconf.tcl assumes that the current directory is the build tree, and it will create various files and subdirectories there. If it is necessary to specify an alternative build tree, use the --builddir option, for example:

$  tclsh BASE_DIR/pkgconf.tcl --builddir=/tmp/ecosobj <other options> 

--prefix=<dir>

In addition to the build tree, pkgconf.tcl will generate an install tree. The various header files, the library libtarget.a, and any other files needed to develop applications, will end up in this install tree. By default, the install tree resides inside the install directory in the build tree, but it is possible to specify an alternative directory if necessary. In some environments this would make it easier to share the built eCos system between developers.

$ tclsh BASE_DIR/pkgconf.tcl --prefix=//share/ecosobj <other options>

Working with pkgconf.tcl

When a build tree is first created it is necessary to specify the target hardware. For details of the hardware that is supported in the current distribution, it is possible to invoke pkgconf.tcl with a --targets arguments.

$ tclsh BASE_DIR/pkgconf.tcl --targets

This will result in a fairly significant amount of output, which will increase further as eCos is ported to more and more architectures. The output is organized on a per-architecture basis. The supported architectures include MN10300, TX39, PowerPC, SPARClite, ARM, and (in part, for the synthetic target) i386. The desired architecture has to be specified on the command line.

$ tclsh BASE_DIR/pkgconf.tcl --target=mn10300

This will create a build tree corresponding to the MN10300 architecture and the default platform for that architecture, the stdeval1 evaluation board. It will also use the default start-up for that platform, RAM start-up, which means that any executables produced will be suitable for downloading into a board equipped with the CygMon ROM monitor. The alternative start-up, ROM, would be appropriate if the executable is intended to be burned into EPROM’s.

pkgconf.tcl is fairly flexible in its argument parsing so it will accept a number of different ways of specifying its arguments. All of the following commands are equivalent:

$ tclsh BASE_DIR/pkgconf.tcl --target=mn10300
% tclsh BASE_DIR/pkgconf.tcl --target mn10300
$ tclsh BASE_DIR/pkgconf.tcl -target mn10300
$ tclsh BASE_DIR/pkgconf.tcl -target=mn10300

In addition, pkgconf.tcl will accept several aliases for the architecture. For example, it is possible to specify --target=mn10300-elf, matching the architecture prefix that is used for the compiler mn10300-elf-gcc and other tools. All recognized aliases will be listed in the output of pkgconf.tcl --targets.

For most architectures there will be some number of supported platforms, also listed in the output of pkgconf.tcl --targets. For example, the supported platforms for the TX39 architecture include the JMR3904 evaluation board and a minimal simulator. By default pkgconf.tcl will use the first listed platform for a given architecture. It is possible to override this using the --platform command line argument, for example:

$ tclsh BASE_DIR/pkgconf.tcl --target=tx39 --platform=sim

Some platforms support multiple start-ups. This is not true of the TX39 simulator where RAM start-up is the only option, but on the JMR3904 board both RAM and ROM start-up are possible. The output from pkgconf.tcl --targets includes details of all the start-ups that are available for a given platform. By default pkgconf.tcl will use the first one that is listed, but it is possible to override this using the --startup command line argument:

$ tclsh BASE_DIR/pkgconf.tcl --target=tx39 --platform=jmr3904 --startup=rom

The output from pkgconf.tcl --targets also includes details of software packages that are associated with particular architectures and platforms.

Since pkgconf.tcl is located at the top level of the component repository it is not necessary to specify the location of the repository explicitly; instead this can be determined automatically by examining the arguments passed to tclsh. You can override this location on the command line by using the --srcdir argument, but this should rarely be necessary. pkgconf.tcl assumes that the current directory is the build tree, but this can be overridden using the --builddir command line argument. It also assumes that the install tree should be in an “install” directory inside the build tree, but this can be overridden using the --prefix arguments.