source: SVN/cambria/redboot/host/README @ 1

Last change on this file since 1 was 1, checked in by Tim Harvey, 2 years ago

restored latest version of files from server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 16.0 KB
1                eCos Host-side Software
2                =======================
4This directory contains the eCos host-side sources. This includes
5libcdl, the CDL library which underlies the whole eCos configuration
6system, and both the command-line and graphical configuration tools.
8The eCos host-side software is free software, released under the GNU
9General Public License. See the file COPYING for further details.
15The host-side sources include the following:
18    This is an implementation of the eCos infrastructure that can be
19    used on the host-side, and provides assertion, tracing and
20    testcase support.
22    NOTE: the eCos infrastructure facilities are not especially
23    well-suited to host-side development, in particular they are not
24    C++-oriented. There are plans to remove the current infrastructure
25    completely and replace it with something more suitable. People
26    planning new projects should be aware of this, and may wish to
27    avoid using the current infrastructure.
30    The CDL library lies at the heart of the eCos configuration system.   
33    The sources to the various configuration tools can be found here.
36    Contains the command line ecosconfig tool.
39    Contains sources related to makefile generation.
43    Contains sources for the MFC-based, Windows-only graphical configuration
44    tool.
47    Contains sources for the wxWindows-based, Linux and Windows graphical
48    configuration tool.
50There are various other sub-directories related to the admin tool,
51testing support, and so on.
53It should be noted that the eCos host-side software is still
54undergoing rapid development, and the sources are subject to change
55and reorganization at any time.   
57Much of the code is cross-platform. The obvious exception is the
58original, MFC-based graphical configuration tool which can only
59be built for Windows hosts and requires Visual C++. It should be
60possible to build the underlying libraries and the command-line
61configuration tool using gcc/g++ on any Unix platform.
63A combined Unix and Windows version of the graphical
64configuration tool, built using the wxWindows GUI toolkit, is
65under development and has its own ReadMe in
66tools/configtool/standalone/wxwin. Any further reference to the
67graphical configuration tool in this document refers to the
68original MFC-based version.
70More Information
73Please see the eCos web site,, for
74further details. This includes the FAQ, a form for reporting problems,
75and details of the various mailing lists
77At the time of writing there are no separate mailing lists for the
78eCos host-side sources, the main mailing list should be used instead.
85Test builds of the eCos host-side generally happen on the following
86platforms: Red Hat Linux 6.1 and later; Windows NT using cygwin 1.0 or
87later; and Windows NT using VC++ 6.0. The graphical configuration tool
88can only be built with VC++ and involves a Developer Studio project,
89see tools/configtool/standalone/win32/Configtool.dsw. The other
90software can be built using the conventional "configure/make/make
91install" steps. It should be noted that the eCos host-side software is
92not fully auto-confiscated, and some facilities like "make dist" will
93not work. Also, the existing DejaGnu-based testing facilities are
94minimal, only intended as a starting point, and may not work on all
97The eCos host-side software has a dependency on Tcl. This is not
98supplied with the sources, because many users will already have a
99suitable installation. Any release of Tcl from 8.0 onwards should be
100usable. There are some configure command-line options related to the
101Tcl installation, as described below.
103The instructions for installing under Linux are given first.
104Installation on other platforms is very similar, so only the
105differences will be noted.
107Installing on Linux
110It is strongly recommended that a separate build tree is used, as
111opposed to building directly in the source tree. The latter has not
112been tested and, given some of the build steps, may not work very
115  $ mkdir build
116  $ cd build
118The next step is to run the toplevel configure script, in other words
119the configure script in the same directory as this README file. This
120will automatically recurse into the various subdirectories for the
121infrastructure, libcdl, and so on. Note that all of the host-side
122software needs to be configured and built: it is not possible to
123invoke just the configure script for the ecosconfig tool and build
124just that tool, because there are dependencies on other parts of the
125host-side code.
127  $ <path>/configure <args>
129A list of the all the command-line options can be obtained by running
130"configure --help". The most important ones are as follows:
1321) --prefix. This can be used to specify the location of the install
133   tree, defaulting to /usr/local, so the ecosconfig program ends up
134   in /usr/local/bin/ecosconfig and the CDL library ends up in
135   /usr/local/lib/libcdl.a. If an alternative location is preferred
136   this can be specified with --prefix, for example:
138   $ <path>/configure --prefix=/usr/local/ecos <args>
1402) --enable-debug. By default all assertions and tracing are disabled.
141   When debugging any of the host-side software these must be enabled.
143   $ <path>/configure --enable-debug
145   It is also possible to control most of the assertion and tracing
146   macros at a finer grain. This is likely to be useful only to the
147   main developers:
149   --disable-asserts        disable all assertions
150   --disable-preconditions  disable a subset of the assertions
151   --disable-postconditions disable a subset of the assertions
152   --disable-invariants     disable a subset of the assertions
153   --disable-loopinvariants disable a subset of the assertions
154   --disable-tracing        disable tracing
155   --disable-fntracing      disable function entry/exit tracing
1573) --with-tcl=<path>, --with-tcl-header=<path>, --with-tcl-lib=<path>
158   and --with-tcl-version=<number>
160   The host-side tools have a dependency on Tcl, which is not supplied
161   with the sources because many people will already have a suitable
162   installation. Specifically it is necessary to have the header file
163   tcl.h and appropriate libraries such that -ltcl will work - this
164   can involve either static or shared libraries.
166   By default the configure script will assume that there is a
167   suitable Tcl installation in the install location, so if there is
168   no --prefix argument then it will look for /usr/local/include/tcl.h
169   and it will add -L/usr/local/lib to the library search path. If
170   Tcl is installed elsewhere then this can be specified with a
171   --with-tcl option. For example, if the default installation in
172   /usr should be used then the following configure option is
173   appropriate:
175   $ <path>/configure --with-tcl=/usr <args>
177   If the Tcl libraries and Tcl headers are installed in different
178   locations, such as when a seperate --prefix and --exec-prefix are
179   used, the --with-tcl-header and --with-tcl-lib options can be used
180   to specify both location.  The configure will expect to find
181   <tcl-header-dir>/include/tcl.h and <tcl-lib-dir>/lib/
182   The --with-tcl option has precedence and if used will override the
183   --with-tcl-header and --with-tcl-lib options.
185   It is possible to have multiple versions of Tcl installed, for
186   example libtcl8.0.a, libtcl8.1.a, and so on. Typically linking with
187   -ltcl will result in the latest version being used. It is possible
188   to specify a different version using --with-tcl-version, e.g.:
190   $ <path>configure --with-tcl=/usr/local/scriptics --with-tcl-version=8.1 <args>
192Following the configure step the build tree should be set up
193correctly. All that remains is the actual build and install:
195   $ make
196   $ make install
198This should result in an ecosconfig executable, plus appropriate
199libraries and header files.   
202Installing on cygwin
205Installing under cygwin requires essentially the same steps as
206under Linux. It is more likely that a suitable --prefix option will
207have to be used, and that the location of the Tcl installation needs
208to be specified with --with-tcl. However appropriate use of cygwin
209mount points may avoid some of these problems. If the full path to
210the configure script contains spaces, then the short form of the path
211should be used when invoking configure.
213One issue to be aware of is the naming convention for the Tcl library.
214On a Unix system this will typically be called libtcl8.0.a (adjusted
215according to the version number), with a symbolic link from libtcl.a
216to the most recent version. Under cygwin the equivalent library is
217called libtcl80.a, and symbolic links are not used. For a standard
218cygwin 1.0 installation the configure script knows how to pick up the
219appropriate library, but if a more recent version of Tcl has been
220installed then due care has to be taken with the --with-tcl-version
224Installing on NT with VC++ (using Visual Studio)
227It is possible to build both the graphical configuration tool and the
228ecosconfig command line tool using a Developer Studio project,
231Even if building the host tools from Visual Studio, it is still
232necessary to install Cygwin and Tcl 8.x. Additionally, there is a
233dependency on either the Microsoft Platform SDK or the Microsoft
234HTML Help Workshop.
236The latter is available at:
239To prepare the machine for the build, it is necessary to:
2411) Set the TCLHOME environment variable to the root of the Tcl installation.
242(For example, TCLHOME=C:\tcl) This can be set from the Enviroment Variables
243dialog on the Advanced tab of the System Properties dialog.
2452) It is also necessary to add several directories to Visual Studio's default
246file search paths. This is set from the Directories tab in the Options menu.
248The following entries will need to be added (full paths are shown for clarity,
249the actual path may be different):
251        a) Executable Files
252                c:\cygwin\bin
253        b) Include Files
254                c:\tcl\include
255                c:\program files\microsoft platform sdk\include _OR_
256                c:\program files\html help workshop\include
257        c) Library Files
258                c:\tcl\lib
259                c:\program files\microsoft platform sdk\lib _OR_
260                c:\program files\html help workshop\lib
2623) The build process as setup by default in the sources available from CVS is
263setup to build the host tools on the DOS v:\ drive. If this drive doesn't exist,
264it may be preferable to do a "subst v:\ c:\temp" command from a Windows command
265shell. This will effectively create a virtual disk which is located at c:\temp,
266and the build process will place all intermediate and build files in this location.
267(Alternatively, it is possible to go through the project settings in Visual Studio
268and adjust the drive letters manually.)
2704) If you have installed a version of Tcl other than version 8.2, it will be necessary
271to change the names of libraries linked with the projects. This can be done by:
273a) Selecting "Settings..." on the ChangeLog file in the cdl project in the
274Configtool workspace, you will see the custom build step for the project.
275At the end of the first line of the custom build step, there is an option
276--with-tcl_version=82. Change this value (82) to correspond to the version of Tcl
277installed on the machine.
279b) Selecting "Settings..." on the Configtool project in the workspace, you should
280go to the Link tab in the right-hand pane. In this pane you will see a line listing
281all the Libraries with which the project is being linked. Change the tcl82.lib entry
282to the name appropriate for the version of Tcl installed.
284(NOTE: These settings must be applied to all configurations you intend to build
285separately. The eCos host tools as shipped by RedHat are built using the
286"Win32 ANSI Release" Configuration. If you build the "Win32 Release" Configuration,
287you will also need to have the Unicode version of the MFC libraries and DLLs.)
2895) Click "Build... (F7)". The compiled binaries will be located in the Configtool
290folder on the V:\ drive.
2951) When using WinCVS, make sure to use the default Windows mode to get the tools.
296Using UNIX mode will break the Visual Studio project files and you won't be able
297to open them. (It is preferable, in general, to use Windows mode for all eCos files.)
2992) There will be many warnings related to STL header compilation. These are benign.
300There are also some warnings related to missing help files at the beginning of the
301Configtool project compilation. These can also be ignored.
3033) To build the other Win32 projects in the host tools, it may be necessary to repeat
304step 4.b) above. (Again, this depends on which version of Tcl is in use.)
307Installing on NT with VC++ (using Cygwin)
310It is also possible to build the command line tool and the various
311libraries using the configure script. At the time of writing the
312graphical configuration tool cannot yet be built that way. This still
313requires a cygwin installation because it needs the bash shell and GNU
314make. First, it is necessary to tell the configure script to use a
315compiler other than gcc:
317  $ mkdir build
318  $ cd build
319  $ CC=cl CXX=cl <path>/configure <args>
321The configure script will do the right thing if VC++ is specified in
322this way.
324It is likely that /usr/local will be an inappropriate install location
325for VC++ applications, so an alternative prefix needs to be specified:
327  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args>
329Note that the install path should be a cygwin path, i.e. cygwin mount
330points are accepted and forward slashes should be used.
332It is also necessary to use the right version of Tcl. For a VC++ build
333the cygwin release of Tcl should not be used. Instead a suitable
334prebuilt Tcl package can be obtained from
335It is necessary to tell the configure script where this has been
336installed, for example:
338  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
339    --with-tcl=/d/local/scriptics/Tcl/tcl8.1 <args>
341The library name will be of the form tcl81.lib, and there will not be
342a symbolic link from tcl.lib to the appropriate version. Typically it
343will be necessary to specify the Tcl version explicitly:   
345  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
346    --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args>
348Following a successful configure, the tools can be built and installed
349in the normal fashion:
351  $ make
352  $ make install
354This assumes that the cl.exe executable is on the shell's search path,
355and that appropriate environment variables such as INCLUDE and LIB are
356set up correctly. The VC++ documentation should be consulted for
357further information.
362// ----------------------------------------------------------------------------
363// Copyright (C) 2000, 2001 Red Hat, Inc.
365// This file is part of the eCos host tools.
367// This program is free software; you can redistribute it and/or modify it
368// under the terms of the GNU General Public License as published by the Free
369// Software Foundation; either version 2 of the License, or (at your option)
370// any later version.
372// This program is distributed in the hope that it will be useful, but WITHOUT
373// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
374// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
375// more details.
377// You should have received a copy of the GNU General Public License along with
378// this program; if not, write to the Free Software Foundation, Inc.,
379// 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
381// ----------------------------------------------------------------------------
Note: See TracBrowser for help on using the repository browser.