|
290
|
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 and Other Unix Systems |
|
|
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 |
|
|
94 all major Linux distributions. Any release of Tcl from 8.0 onwards |
|
|
95 should be usable. |
|
|
96 |
|
|
97 There are two main approaches to building the host-side software: |
|
|
98 |
|
|
99 1) build the generic and the package-specific code in one build tree. |
|
|
100 This uses the top-level configure script. The script automatically |
|
|
101 invokes the configure script in the main host subdirectory. In |
|
|
102 addition it searches the packages hierarchy for host subdirectories |
|
|
103 containing their own configure scripts and will invoke those. |
|
|
104 |
|
|
105 Note: the search for host subdirectories happens during configure |
|
|
106 time, not during the make. If new packages with host-side code are |
|
|
107 added to the repository then it will be necessary to re-run the |
|
|
108 toplevel configure script. |
|
|
109 |
|
|
110 2) build the generic code in one build tree, using the configure |
|
|
111 script in the toplevel's host subdirectory. Then build some or all |
|
|
112 of the package-specific code in separate build trees, using the |
|
|
113 configure scripts in each package's host subdirectory. |
|
|
114 |
|
|
115 The first approach is generally simpler. However some of the |
|
|
116 package-specific code requires special installation, for example a |
|
|
117 program may have to be installed suid root so that it has the right |
|
|
118 privileges to access hardware, and hence the "make install" step has |
|
|
119 to be run by the superuser. Also some of the package-specific code is |
|
|
120 rather specialized and may be of no interest to many users. For |
|
|
121 example, the USB testing code is only useful when developing |
|
|
122 USB-based applications. Hence some users may prefer the second |
|
|
123 approach, building just the generic code and a subset of the |
|
|
124 package-specific code. |
|
|
125 |
|
|
126 It is necessary to use a separate build tree rather than build |
|
|
127 directly in the source tree. This is enforced by the configure scripts. |
|
|
128 |
|
|
129 $ mkdir build |
|
|
130 $ cd build |
|
|
131 |
|
|
132 The next step is to run the desired configure script. To build all |
|
|
133 the host-side software this means the toplevel configure script: |
|
|
134 |
|
|
135 $ <path>/configure <args> |
|
|
136 |
|
|
137 Alternatively to build just the generic host-side software, use the |
|
|
138 configure script in the host subdirectory. |
|
|
139 |
|
|
140 $ mkdir host |
|
|
141 $ cd host |
|
|
142 $ <path>/host/configure <args> |
|
|
143 |
|
|
144 Or, to build just one package's host-side code: |
|
|
145 |
|
|
146 $ mkdir -p packages/io/usb/slave/current/host |
|
|
147 $ cd packages/io/usb/slave/current/host |
|
|
148 $ <path>/packages/io/usb/slave/current/host/configure <args> |
|
|
149 |
|
|
150 (It is not actually necessary to use the same directory structure in |
|
|
151 the build tree as in the source tree, but doing so can avoid |
|
|
152 confusion). |
|
|
153 |
|
|
154 A list of all the command-line options can be obtained by running |
|
|
155 "configure --help". The most important ones are as follows: |
|
|
156 |
|
|
157 1) --prefix. This can be used to specify the location of the install |
|
|
158 tree, defaulting to /usr/local, so the ecosconfig program ends up |
|
|
159 in /usr/local/bin/ecosconfig and the CDL library ends up in |
|
|
160 /usr/local/lib/libcdl.a. If an alternative location is preferred |
|
|
161 this can be specified with --prefix, for example: |
|
|
162 |
|
|
163 $ <path>/configure --prefix=/usr/local/ecos <args> |
|
|
164 |
|
|
165 2) --enable-debug. By default all assertions and tracing are disabled. |
|
|
166 When debugging any of the generic host-side software these should |
|
|
167 be enabled. Some package-specific code may not have any extra |
|
|
168 debug support, in which case --enable-debug would be ignored. |
|
|
169 |
|
|
170 $ <path>/configure --enable-debug |
|
|
171 |
|
|
172 It is also possible to control most of the assertion and tracing |
|
|
173 macros at a finer grain. This is intended mainly for use by the |
|
|
174 developers. |
|
|
175 |
|
|
176 --disable-asserts disable all assertions |
|
|
177 --disable-preconditions disable a subset of the assertions |
|
|
178 --disable-postconditions disable a subset of the assertions |
|
|
179 --disable-invariants disable a subset of the assertions |
|
|
180 --disable-loopinvariants disable a subset of the assertions |
|
|
181 --disable-tracing disable tracing |
|
|
182 --disable-fntracing disable function entry/exit tracing |
|
|
183 |
|
|
184 3) --with-tcl=<path> |
|
|
185 --with-tcl-header=<path> |
|
|
186 --with-tcl-lib=<path> |
|
|
187 --with-tcl-version=<number> |
|
|
188 |
|
|
189 The host-side tools have a dependency on Tcl, which is not supplied |
|
|
190 with the sources because many people will already have a suitable |
|
|
191 installation. Specifically it is necessary to have the header file |
|
|
192 tcl.h and appropriate libraries such that -ltcl will work - this |
|
|
193 can involve either static or shared libraries. |
|
|
194 |
|
|
195 By default the configure script will assume that there is a |
|
|
196 suitable Tcl installation in the install location, so if there is |
|
|
197 no --prefix argument then it will look for /usr/local/include/tcl.h |
|
|
198 and it will add -L/usr/local/lib to the library search path. If |
|
|
199 Tcl is installed elsewhere then this can be specified with a |
|
|
200 --with-tcl option. For example, if the default installation in |
|
|
201 /usr should be used then the following configure option is |
|
|
202 appropriate: |
|
|
203 |
|
|
204 $ <path>/configure --with-tcl=/usr <args> |
|
|
205 |
|
|
206 If the Tcl libraries and Tcl headers are installed in different |
|
|
207 locations, such as when a separate --prefix and --exec-prefix are |
|
|
208 used, the --with-tcl-header and --with-tcl-lib options can be used |
|
|
209 to specify both location. The configure script will expect to find |
|
|
210 <tcl-header-dir>/include/tcl.h and <tcl-lib-dir>/lib/tclConfig.sh. |
|
|
211 The --with-tcl option has precedence and if used will override the |
|
|
212 --with-tcl-header and --with-tcl-lib options. |
|
|
213 |
|
|
214 It is possible to have multiple versions of Tcl installed, for |
|
|
215 example libtcl8.0.a, libtcl8.1.a, and so on. Typically linking with |
|
|
216 -ltcl will result in the latest version being used. It is possible |
|
|
217 to specify a different version using --with-tcl-version, e.g.: |
|
|
218 |
|
|
219 $ <path>configure --with-tcl=/usr/local/scriptics --with-tcl-version=8.1 <args> |
|
|
220 |
|
|
221 Following the configure step the build tree should be set up |
|
|
222 correctly. All that remains is the actual build and install: |
|
|
223 |
|
|
224 $ make |
|
|
225 $ make install |
|
|
226 |
|
|
227 This should result in an ecosconfig executable, plus appropriate |
|
|
228 libraries and header files. If the install prefix is a system |
|
|
229 location, for example /usr/local/, then "make install" will normally |
|
|
230 require root privileges. Also some of the package-specific software |
|
|
231 has special installation requirements, for example programs that need |
|
|
232 to be installed suid root, and this will also need root privileges. |
|
|
233 |
|
|
234 |
|
|
235 Installing under Cygwin |
|
|
236 ----------------------- |
|
|
237 |
|
|
238 Installing under cygwin requires essentially the same steps as |
|
|
239 under Linux. It is more likely that a suitable --prefix option will |
|
|
240 have to be used, and that the location of the Tcl installation needs |
|
|
241 to be specified with --with-tcl. However appropriate use of cygwin |
|
|
242 mount points may avoid some of these problems. If the full path to |
|
|
243 the configure script contains spaces, then the short form of the path |
|
|
244 should be used when invoking configure. |
|
|
245 |
|
|
246 One issue to be aware of is the naming convention for the Tcl library. |
|
|
247 On a Unix system this will typically be called libtcl8.3.a (adjusted |
|
|
248 according to the version number), with a symbolic link from libtcl.a |
|
|
249 to the most recent version. Under cygwin the equivalent library is |
|
|
250 called libtcl80.a, and symbolic links are not used. For a standard |
|
|
251 cygwin installation the configure script knows how to pick up the |
|
|
252 appropriate library, but if a more recent version of Tcl has been |
|
|
253 installed then due care has to be taken with the --with-tcl-version |
|
|
254 option. |
|
|
255 |
|
|
256 |
|
|
257 Installing with Visual C++ |
|
|
258 -------------------------- |
|
|
259 |
|
|
260 Under Windows it is possible to build the generic host-side software |
|
|
261 (infra, libcdl and ecosconfig) with Visual C++ but this is deprecated. |
|
|
262 Building with g++ under cygwin is preferred. |
|
|
263 |
|
|
264 It is still necessary to run the configure script and a suitable make |
|
|
265 utility. That requires a shell and a Unix-like environment, as |
|
|
266 provided by cygwin. The Visual C++ compiler cl.exe needs to be on the |
|
|
267 shell's search path, and some environment variables such as INCLUDE |
|
|
268 and LIB may need to be set to point at the Visual C++ installation - |
|
|
269 the details may vary depending on the version of the compiler. Then |
|
|
270 the configure command should be run like this: |
|
|
271 |
|
|
272 $ CC=cl CXX=cl <path>/host/configure <args> |
|
|
273 |
|
|
274 Note that the path should be a cygwin path: cygwin mount points are |
|
|
275 accepted and forward slashes should be used. The various configure |
|
|
276 scripts now detect that Visual C++ should be used, and adapt |
|
|
277 accordingly. |
|
|
278 |
|
|
279 Depending on what cygwin mount points are set up, /usr/local may or |
|
|
280 may not be an appropriate install location for VC++ applications. |
|
|
281 If not, the install location should be specified with --prefix: |
|
|
282 |
|
|
283 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args> |
|
|
284 |
|
|
285 It is also necessary to use the right version of Tcl. For a VC++ build |
|
|
286 the cygwin release of Tcl should not be used. Instead a suitable |
|
|
287 prebuilt Tcl package can be obtained from http://www.scriptics.com/. |
|
|
288 It is necessary to tell the configure script where this has been |
|
|
289 installed, for example: |
|
|
290 |
|
|
291 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \ |
|
|
292 --with-tcl=/cygdrive/d/local/scriptics/Tcl/tcl8.1 <args> |
|
|
293 |
|
|
294 The library name will be of the form tcl81.lib, and there will not be |
|
|
295 a symbolic link from tcl.lib to the appropriate version. It will be |
|
|
296 necessary to specify the Tcl version explicitly since the default |
|
|
297 version is currently 8.0. |
|
|
298 |
|
|
299 $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \ |
|
|
300 --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args> |
|
|
301 |
|
|
302 Following a successful configure, the tools can be built and installed |
|
|
303 in the normal fashion: |
|
|
304 |
|
|
305 $ make |
|
|
306 $ make install |
|
|
307 |
|
|
308 |
|
|
309 More Information |
|
|
310 ================ |
|
|
311 |
|
|
312 Please see the eCos web site, http://sources.redhat.com/ecos/, for |
|
|
313 further details. This includes the FAQ, a form for reporting problems, |
|
|
314 and details of the various mailing lists |
|
|
315 (http://sources.redhat.com/ecos/intouch.html) At the time of writing |
|
|
316 there are no separate mailing lists for the eCos host-side sources, |
|
|
317 the main mailing list ecos-discuss@sources.redhat.com should be used |
|
|
318 instead. |
|
|
319 |
|
|
320 //####COPYRIGHTBEGIN#### |
|
|
321 // |
|
|
322 //---------------------------------------------------------------------------- |
|
|
323 // Copyright (C) 2002 Bart Veer |
|
|
324 // Copyright (C) 2000, 2001 Red Hat, Inc. |
|
|
325 // |
|
|
326 // This file is part of the eCos host tools. |
|
|
327 // |
|
|
328 // This program is free software; you can redistribute it and/or modify it |
|
|
329 // under the terms of the GNU General Public License as published by the Free |
|
|
330 // Software Foundation; either version 2 of the License, or (at your option) |
|
|
331 // any later version. |
|
|
332 // |
|
|
333 // This program is distributed in the hope that it will be useful, but WITHOUT |
|
|
334 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
|
335 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for |
|
|
336 // more details. |
|
|
337 // |
|
|
338 // You should have received a copy of the GNU General Public License along with |
|
|
339 // this program; if not, write to the Free Software Foundation, Inc., |
|
|
340 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
|
|
341 // |
|
|
342 // ---------------------------------------------------------------------------- |
|
|
343 // |
|
|
344 //####COPYRIGHTEND#### |
