OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [README.host] - Blame information for rev 606

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 25 unneback
                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//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
  $ /configure 
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
  $ /host/configure 
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
  $ /packages/io/usb/slave/current/host/configure 
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
   $ /configure --prefix=/usr/local/ecos 
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
   $ /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=
188
   --with-tcl-version=
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
   $ /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
   $ /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
      /lib/tclConfig.sh
229
      /lib/tcl/tclConfig.sh
230
      /lib/tclConfig.sh
231
      /lib/tcl/tclConfig.sh
232
      /usr/lib/tclConfig.sh
233
      /usr/lib/tcl/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
      /lib/tkConfig.sh
241
      /lib/tk/tkConfig.sh
242
      /lib/tkConfig.sh
243
      /lib/tk/tkConfig.sh
244
      /usr/lib/tkConfig.sh
245
      /usr/lib/tk/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
    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  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.a, where  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 /host/configure 
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 /configure --prefix= 
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 /configure --prefix= \
313
    --with-tcl=/cygdrive/d/local/scriptics/Tcl/tcl8.1 
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 /configure --prefix= \
321
    --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 
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####

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.