Deleted obsolete file
[karo-tx-redboot.git] / README.host
1                 eCos Host-side Software
2                 =======================
3
4 This README file only describes the eCos host-side software. For
5 details of the eCos target-side software or the required toolchains,
6 please see other documentation. A good starting point is
7 http://sources.redhat.com/ecos
8                 
9 There are two categories of host-side software. The host subdirectory
10 contains generic software, primarily related to the eCos configuration
11 technology. All eCos users will need to use some of this technology to
12 configure and build eCos, either using pre-built binaries or by
13 building the host-side software from source. The generic software
14 should be portable to a wide range of host platforms.
15
16 There is also package-specific host-side software. Much of this is I/O
17 related. For example the generic USB-slave package contains some
18 programs related to testing; a test application is run on a target
19 with suitable USB slave-side hardware, and needs to interact with
20 another program running on the USB host; the latter is
21 package-specific host-side software and can be found in the
22 subdirectory packages/io/usb/slave. Code like this may have
23 significant platform dependencies and may only work on a single
24 platform or on a small number of platforms. There may also be
25 special requirements, for example it may be necessary to install some
26 programs suid root so that they have appropriate access to the
27 hardware. 
28
29
30 The host subdirectory includes the following:
31
32 infra/
33     This is an implementation of the eCos infrastructure that can be
34     used on the host-side, and provides assertion, tracing and
35     testcase support.
36
37     NOTE: the eCos infrastructure facilities are not especially
38     well-suited to host-side development, in particular they are not
39     C++-oriented. There are plans to remove the current infrastructure
40     completely and replace it with something more suitable. People
41     planning new projects should be aware of this, and may wish to
42     avoid using the current infrastructure.
43
44 libcdl/
45     The CDL library lies at the heart of the eCos configuration
46     technology. 
47
48 tools/configtool/
49     The sources to the various configuration tools can be found here.
50
51 tools/configtool/common/common/
52     Contains sources related to makefile generation, shared by the
53     command line and graphical tools.
54
55 tools/configtool/standalone/common/
56     Contains the command line ecosconfig tool.
57
58 tools/configtool/standalone/wxwin/
59     Contains sources for the wxWindows-based, Linux and Windows graphical
60     configuration tool. The Windows version can currently only be
61     built with Visual C++, not with cygwin g++.
62     
63 tools/configtool/common/win32/
64 tools/configtool/standalone/win32/
65     Contains sources for the older, MFC-based, Windows-only graphical
66     configuration tool. Again this can currently only be built with
67     Visual C++.
68
69 The two graphical configuration tools have their own build procedures,
70 described in tools/configtool/standalone/wxwin/ReadMe and
71 tools/configtool/standalone/win32/ReadMe respectively.
72
73 Package-specific host-side code lives in the host subdirectory of the
74 appropriate package, for example packages/io/usb/slave/<version>/host.
75 Most packages only provide target-side code and hence will not have a
76 host subdirectory. Users can install various packages from a variety
77 of sources, and where a package does have host-side software the
78 package documentation should be consulted for further information.
79
80
81 Installing on Linux, Other Unix Systems, and Cygwin
82 ---------------------------------------------------
83
84 Both generic host-side software (infra, libcdl and ecosconfig) and
85 package-specific software can be built with the conventional
86 "configure/make/make install" sequence. However the code does not
87 conform fully to GNU coding standards so some operations such as "make
88 dist" are not supported. There is limited support for DejaGnu-based
89 testing.
90
91 Much of the host-side software has a dependency on Tcl. This is not
92 supplied with the sources since many users will already have a
93 suitable installation, for example it is shipped as standard with all
94 major Linux distributions. The generic host-side software should work
95 with any release of Tcl from 8.0 onwards. The package-specific
96 software requires a more recent version, 8.3 or later. If no suitable
97 Tcl installation is available then the configure step will still
98 succeed but some of the package-specific software will not be built.
99
100 There are two main approaches to building the host-side software:
101
102 1) build the generic and the package-specific code in one build tree.
103    This uses the top-level configure script. The script automatically
104    invokes the configure script in the main host subdirectory. In
105    addition it searches the packages hierarchy for host subdirectories
106    containing their own configure scripts and will invoke those.
107
108    Note: the search for host subdirectories happens during configure
109    time, not during the make. If new packages with host-side code are
110    added to the repository then it will be necessary to re-run the
111    toplevel configure script.
112
113 2) build the generic code in one build tree, using the configure
114    script in the toplevel's host subdirectory. Then build some or all
115    of the package-specific code in separate build trees, using the
116    configure scripts in each package's host subdirectory.
117
118 The first approach is generally simpler. However some of the
119 package-specific code requires special installation, for example a
120 program may have to be installed suid root so that it has the right
121 privileges to access hardware, and hence the "make install" step has
122 to be run by the superuser. Also some of the package-specific code is
123 rather specialized and may be of no interest to many users. For
124 example, the USB testing code is only useful when developing
125 USB-based applications. Hence some users may prefer the second
126 approach, building just the generic code and a subset of the
127 package-specific code.
128
129 It is necessary to use a separate build tree rather than build
130 directly in the source tree. This is enforced by the configure scripts.
131
132   $ mkdir build
133   $ cd build
134
135 The next step is to run the desired configure script. To build all
136 the host-side software this means the toplevel configure script:
137
138   $ <path>/configure <args>
139
140 Alternatively to build just the generic host-side software, use the
141 configure script in the host subdirectory.
142
143   $ mkdir host
144   $ cd host
145   $ <path>/host/configure <args>
146
147 Or, to build just one package's host-side code:
148
149   $ mkdir -p packages/io/usb/slave/current/host
150   $ cd packages/io/usb/slave/current/host
151   $ <path>/packages/io/usb/slave/current/host/configure <args>
152
153 (It is not actually necessary to use the same directory structure in
154 the build tree as in the source tree, but doing so can avoid
155 confusion). 
156   
157 A list of all the command-line options can be obtained by running
158 "configure --help". The most important ones are as follows:
159
160 1) --prefix. This can be used to specify the location of the install
161    tree, defaulting to /usr/local, so the ecosconfig program ends up
162    in /usr/local/bin/ecosconfig and the CDL library ends up in
163    /usr/local/lib/libcdl.a. If an alternative location is preferred
164    this can be specified with --prefix, for example:
165
166    $ <path>/configure --prefix=/usr/local/ecos <args>
167
168 2) --enable-debug. By default all assertions and tracing are disabled.
169    When debugging any of the generic host-side software these should
170    be enabled. Some package-specific code may not have any extra
171    debug support, in which case --enable-debug would be ignored.
172
173    $ <path>/configure --enable-debug
174
175    It is also possible to control most of the assertion and tracing
176    macros at a finer grain. This is intended mainly for use by the
177    developers.
178
179    --disable-asserts        disable all assertions
180    --disable-preconditions  disable a subset of the assertions
181    --disable-postconditions disable a subset of the assertions
182    --disable-invariants     disable a subset of the assertions
183    --disable-loopinvariants disable a subset of the assertions
184    --disable-tracing        disable tracing
185    --disable-fntracing      disable function entry/exit tracing
186
187 3) --with-tcl=<path>
188    --with-tcl-version=<number>
189
190    The host-side tools have a dependency on Tcl, which is not supplied
191    with the sources because many people will already have a suitable
192    installation. Specifically it is necessary to have the header file
193    tcl.h and appropriate libraries such that -ltcl will work - this
194    can involve either static or shared libraries. Some tools may require
195    Tk as well as Tcl.
196
197    Unfortunately there is considerable variation in Tcl installations.
198    In theory all Tcl installations have a file tclConfig.sh which
199    defines exactly how to compile and link code that uses Tcl, and Tk
200    has a similar file tkConfig.sh. The eCos configure scripts look for
201    these files, first in $(prefix)/lib, then in /usr/lib. If the system
202    already has a Tcl installation in /usr then the configure script will
203    automatically find /usr/lib/tclConfig.sh and it is not necessary
204    to pass additional options when configuring the eCos host-side
205    software. Alternatively, if for example you have installed a more
206    recent version of Tcl/Tk in the same place that you want to install the
207    eCos software, e.g. /usr/local, then $(prefix)/lib/tclConfig.sh
208    will be read in.
209
210    It is also possible that a more recent version of Tcl has been installed
211    in a different location. For example, you may wish to install the eCos host
212    tools in /opt/ecos but use a version of Tcl installed in /usr/local. The
213    eCos configure scripts need to be told explicitly where to look for
214    the Tcl:
215
216    $ <path>/configure --with-tcl=/usr/local ...
217
218    Some systems, for example Debian Linux 3.0, do not install tclConfig.sh
219    in /usr/lib because that makes it more difficult to have several different
220    versions of Tcl installed at the same time. Instead tclConfig.sh is found
221    in a versioned directory such as /usr/lib/tcl8.3. Since several versions
222    may be installed the desired one must be specified explicitly.
223
224    $ <path>/configure --with-tcl-version=8.3
225
226    The --with-tcl and --with-tcl-version options are combined to give a search path:
227
228       <with>/lib/tclConfig.sh
229       <with>/lib/tcl<vsn>/tclConfig.sh
230       <prefix>/lib/tclConfig.sh
231       <prefix>/lib/tcl<vsn>/tclConfig.sh
232       /usr/lib/tclConfig.sh
233       /usr/lib/tcl<vsn>/tclConfig.sh
234
235    If tclConfig.sh cannot be found in any of these places then it is assumed
236    that Tcl has not been properly installed and the eCos configure script will
237    fail. The --with-tcl and --with-tcl-version are also used to give a search
238    path for tkConfig.sh
239
240       <with>/lib/tkConfig.sh
241       <with>/lib/tk<vsn>/tkConfig.sh
242       <prefix>/lib/tkConfig.sh
243       <prefix>/lib/tk<vsn>/tkConfig.sh
244       /usr/lib/tkConfig.sh
245       /usr/lib/tk<vsn>/tkConfig.sh
246
247    Again, the configure scripts must be able to find tkConfig.sh
248
249    Once tclConfig.sh and tkConfig.sh have been found and read in, the eCos
250    configure scripts should have all the information needed to compile and
251    link code that uses Tcl. First the location of key headers such as
252    <tcl.h> is needed. A tclConfig.sh file may define TCL_INC_DIR to give
253    a specific location, otherwise the header files should be in
254    $(TCL_PREFIX)/include. If <tcl.h> cannot be found then the eCos configure
255    scripts will fail.
256
257    Next it is necessary to work out how to link applications with Tcl. This
258    information should be provided by a tclConfig.sh variable TCL_LIB_SPEC.
259    Unfortunately not all Tcl installations set this, for example the cygwin
260    Tcl 8.4 release. If TCL_LIB_SPEC is not defined then instead the
261    configure script will look for a library libtcl<vsn>.a, where <vsn> is
262    specified using --with-tcl-version, then for a library libtcl.a
263
264 Following the configure step the build tree should be set up
265 correctly. All that remains is the actual build and install:
266
267    $ make
268    $ make install
269
270 This should result in an ecosconfig executable, plus appropriate
271 libraries and header files. If the install prefix is a system
272 location, for example /usr/local/, then "make install" will normally
273 require root privileges. Also some of the package-specific software
274 has special installation requirements, for example programs that need
275 to be installed suid root, and this will also need root privileges.
276
277
278 Installing with Visual C++
279 --------------------------
280
281 Under Windows it is possible to build the generic host-side software
282 (infra, libcdl and ecosconfig) with Visual C++ but this is deprecated.
283 Building with g++ under cygwin is preferred.
284
285 It is still necessary to run the configure script and a suitable make
286 utility. That requires a shell and a Unix-like environment, as
287 provided by cygwin. The Visual C++ compiler cl.exe needs to be on the
288 shell's search path, and some environment variables such as INCLUDE
289 and LIB may need to be set to point at the Visual C++ installation -
290 the details may vary depending on the version of the compiler. Then
291 the configure command should be run like this:
292
293   $ CC=cl CXX=cl <path>/host/configure <args>
294
295 Note that the path should be a cygwin path: cygwin mount points are
296 accepted and forward slashes should be used. The various configure
297 scripts now detect that Visual C++ should be used, and adapt
298 accordingly.
299
300 Depending on what cygwin mount points are set up, /usr/local may or
301 may not be an appropriate install location for VC++ applications.
302 If not, the install location should be specified with --prefix:
303
304   $ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args>
305
306 It is also necessary to use the right version of Tcl. For a VC++ build
307 the cygwin release of Tcl should not be used. Instead a suitable
308 prebuilt Tcl package can be obtained from http://www.tcl.tk/.
309 It is necessary to tell the configure script where this has been
310 installed, for example:
311
312   $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
313     --with-tcl=/cygdrive/d/local/scriptics/Tcl/tcl8.1 <args>
314
315 The library name will be of the form tcl81.lib, and there will not be
316 a symbolic link from tcl.lib to the appropriate version. It will be
317 necessary to specify the Tcl version explicitly since the default
318 version is currently 8.0.
319
320   $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
321     --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args>
322
323 Following a successful configure, the tools can be built and installed
324 in the normal fashion:
325
326   $ make
327   $ make install
328
329
330 More Information
331 ================
332
333 Please see the eCos web site, http://sources.redhat.com/ecos/, for
334 further details. This includes the FAQ, a form for reporting problems,
335 and details of the various mailing lists
336 (http://sources.redhat.com/ecos/intouch.html) At the time of writing
337 there are no separate mailing lists for the eCos host-side sources,
338 the main mailing list ecos-discuss@sources.redhat.com should be used
339 instead.
340
341 //####COPYRIGHTBEGIN####
342 //                                                                          
343 //----------------------------------------------------------------------------
344 // Copyright (C) 2002 Bart Veer
345 // Copyright (C) 2000, 2001 Red Hat, Inc.
346 //
347 // This file is part of the eCos host tools.
348 //
349 // This program is free software; you can redistribute it and/or modify it 
350 // under the terms of the GNU General Public License as published by the Free 
351 // Software Foundation; either version 2 of the License, or (at your option) 
352 // any later version.
353 // 
354 // This program is distributed in the hope that it will be useful, but WITHOUT 
355 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
356 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for 
357 // more details.
358 // 
359 // You should have received a copy of the GNU General Public License along with
360 // this program; if not, write to the Free Software Foundation, Inc., 
361 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
362 //
363 // ----------------------------------------------------------------------------
364 //                                                                          
365 //####COPYRIGHTEND####