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
Line 
1                eCos Host-side Software
2                =======================
3
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.
7
8The eCos host-side software is free software, released under the GNU
9General Public License. See the file COPYING for further details.
10
11
12Contents
13========
14
15The host-side sources include the following:
16
17infra/
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.
21
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.
28
29libcdl/
30    The CDL library lies at the heart of the eCos configuration system.   
31
32tools/configtool/
33    The sources to the various configuration tools can be found here.
34
35tools/configtool/standalone/common/
36    Contains the command line ecosconfig tool.
37
38tools/configtool/common/common/
39    Contains sources related to makefile generation.
40
41tools/configtool/common/win32/
42tools/configtool/standalone/win32/
43    Contains sources for the MFC-based, Windows-only graphical configuration
44    tool.
45
46tools/configtool/standalone/wxwin/
47    Contains sources for the wxWindows-based, Linux and Windows graphical
48    configuration tool.
49
50There are various other sub-directories related to the admin tool,
51testing support, and so on.
52
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.   
56
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.
62
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.
69
70More Information
71================
72
73Please see the eCos web site, http://sourceware.cygnus.com/ecos/, for
74further details. This includes the FAQ, a form for reporting problems,
75and details of the various mailing lists
76(http://sourceware.cygnus.com/ecos/intouch.html)
77At the time of writing there are no separate mailing lists for the
78eCos host-side sources, the main mailing list
79ecos-discuss@sourceware.cygnus.com should be used instead.
80
81
82Installation
83============
84
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
95platforms.
96
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.
102
103The instructions for installing under Linux are given first.
104Installation on other platforms is very similar, so only the
105differences will be noted.
106
107Installing on Linux
108===================
109
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
113well.
114
115  $ mkdir build
116  $ cd build
117
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.
126
127  $ <path>/configure <args>
128
129A list of the all the command-line options can be obtained by running
130"configure --help". The most important ones are as follows:
131
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:
137
138   $ <path>/configure --prefix=/usr/local/ecos <args>
139
1402) --enable-debug. By default all assertions and tracing are disabled.
141   When debugging any of the host-side software these must be enabled.
142
143   $ <path>/configure --enable-debug
144
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:
148
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
156
1573) --with-tcl=<path>, --with-tcl-header=<path>, --with-tcl-lib=<path>
158   and --with-tcl-version=<number>
159
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.
165
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:
174
175   $ <path>/configure --with-tcl=/usr <args>
176
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/tclConfig.sh.
182   The --with-tcl option has precedence and if used will override the
183   --with-tcl-header and --with-tcl-lib options.
184
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.:
189
190   $ <path>configure --with-tcl=/usr/local/scriptics --with-tcl-version=8.1 <args>
191
192Following the configure step the build tree should be set up
193correctly. All that remains is the actual build and install:
194
195   $ make
196   $ make install
197
198This should result in an ecosconfig executable, plus appropriate
199libraries and header files.   
200   
201
202Installing on cygwin
203====================
204
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.
212
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
221option.
222
223
224Installing on NT with VC++ (using Visual Studio)
225================================================
226
227It is possible to build both the graphical configuration tool and the
228ecosconfig command line tool using a Developer Studio project,
229tools/ecosconfig/standalone/win32/Configtool.dsw
230
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.
235
236The latter is available at:
237http://msdn.microsoft.com/library/tools/htmlhelp/wkshp/download.htm
238
239To prepare the machine for the build, it is necessary to:
240
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.
244
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.
247
248The following entries will need to be added (full paths are shown for clarity,
249the actual path may be different):
250
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
261
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.)
269
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:
272
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.
278
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.
283
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.)
288
2895) Click "Build... (F7)". The compiled binaries will be located in the Configtool
290folder on the V:\ drive.
291
292
293NOTES:
294
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.)
298
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.
302
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.)
305
306
307Installing on NT with VC++ (using Cygwin)
308=========================================
309
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:
316
317  $ mkdir build
318  $ cd build
319  $ CC=cl CXX=cl <path>/configure <args>
320
321The configure script will do the right thing if VC++ is specified in
322this way.
323
324It is likely that /usr/local will be an inappropriate install location
325for VC++ applications, so an alternative prefix needs to be specified:
326
327  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> <args>
328
329Note that the install path should be a cygwin path, i.e. cygwin mount
330points are accepted and forward slashes should be used.
331 
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 http://www.scriptics.com/.
335It is necessary to tell the configure script where this has been
336installed, for example:
337
338  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
339    --with-tcl=/d/local/scriptics/Tcl/tcl8.1 <args>
340
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:   
344
345  $ CC=cl CXX=cl <path>/configure --prefix=<install-path> \
346    --with-tcl=/d/local/scriptics/Tcl/tcl8.1 --with-tcl-version=81 <args>
347
348Following a successful configure, the tools can be built and installed
349in the normal fashion:
350
351  $ make
352  $ make install
353
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.
358 
359
360//####COPYRIGHTBEGIN####
361//                                                                         
362// ----------------------------------------------------------------------------
363// Copyright (C) 2000, 2001 Red Hat, Inc.
364//
365// This file is part of the eCos host tools.
366//
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.
371//
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.
376//
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.
380//
381// ----------------------------------------------------------------------------
382//                                                                         
383//####COPYRIGHTEND####
Note: See TracBrowser for help on using the repository browser.