1 eCos Cross-platform Configuration Tool
2 Copyright (c) Red Hat Inc., 2001-2002
3 ======================================
11 * What's in this release?
12 * Installing the Configuration Tool
13 * Running the Configuration Tool
14 * Frequently Asked Questions
15 * Building the Configuration Tool under Linux
16 * Building the Configuration Tool under Windows
22 Welcome to the eCos Configuration Tool, a graphical tool to
23 help a user configure and build a custom version of the
24 eCos operating system.
26 This is a cross-platform version built using the wxWindows
27 toolkit. The tool uses the GTK+ widget set on Linux, and the
28 WIN32 API on Windows 9x, Windows NT and Windows 2000. It is
29 similar to the MFC, Windows-only version but at present lacks
30 a few of its features, such as the Memory Layout Tool and the
31 ability to run tests from within the tool.
33 Please note that this is alpha-level code. However, all feedback to
34 the eCos team is appreciated, via ecos-discuss@sources.redhat.com or the
35 bug reporting form at http://sources.redhat.com/ecos/problemreport.html.
37 These are the instructions for running and building the eCos
38 Configuration Tool for Linux and Windows.
41 What's in this release?
42 =======================
44 This version allows you to edit, load, save and build eCos
45 configurations much as the original Windows Configuration Tool.
46 However the following features are missing with respect to the
50 - Administration functionality (initial code present but untested)
51 - Gauge indicating time left to build library and tests
53 The following features are present in the new tool but not in the
56 - Repository Information dialog (available from the Help menu)
57 - Most dialogs are resizeable
59 Documentation works a little differently. Instead of using a
60 precompiled HTML Help file, this version compiles a documentation
61 index on the fly for use with its own internal HTML help viewer. The
62 cached indexes are placed in the .eCosDocs directory under the
63 user's home directory (Linux) or in the installed repository
64 (Windows). The internal viewer cannot cope with all of the eCos
65 and GNUPro documentation, so for these occasions please use an
66 external browser (see the Settings dialog).
68 The documentation for the Configuration Tool is supplied in its
69 install directory as HTML only, and is a modified version of the
70 eCos User's Guide. Invoke the tool help from the
71 "Help|Configuration Tool Help" menu item, or from the internal
72 help viewer's index, under "Linux Configuration Tool Guide".
76 - The documentation index only lists the packages in the
77 configuration active when the documentation was indexed
78 (normally when the repository is first seen by the
86 Installing the Configuration Tool
87 =================================
89 The Configuration Tool can be used with existing eCos
90 installations and CVS source hierarchies. You can get the
91 binaries from ftp://sources.redhat.com/pub/ecos/ct2/.
93 See also mirror sites at:
95 http://sources.redhat.com/ecos/mirror.html
96 http://sources.redhat.com/mirrors.html
98 Please try to use a mirror site close to you, as it will be
104 ftp://sources.redhat.com/pub/ecos/ct2/configtool-2.0-i386.tar.gz
107 Unarchive the tar file into a suitable directory and add the
108 directory to your path. You do not have to install it as root.
111 % mkdir -p /opt/ecos/configtool/bin
112 % cd /opt/ecos/configtool/bin
113 % tar xvfz /cdrom/configtool-2.0.tar.gz
114 % export PATH=/opt/ecos/configtool/bin:$PATH
116 The following files will be extracted to the installation directory:
125 Optionally, untar the contents of ecosplatforms.tar.gz into your
126 home directory, where it will create a directory called
127 .eCosPlatforms. The information in these files isn't yet used
128 by the Configuration Tool, but will keep the tool from
129 generating some warnings.
131 The executable is statically linked to the wxWindows library,
132 but does require the GTK+ 1.2, GDK 1.2 and Tcl 8.x libraries
137 Download configtool-2.0-setup.exe (or similar name).
139 Run the installer provided, preferably having installed eCos
140 for Windows on your PC previously so the tool can pick up the
141 relevant registry information added by the eCos installer.
142 A new eCos Configuration Tool group will be added to your
143 Start menu and a shortcut to the Configuration Tool will
144 appear on your desktop.
147 Running the Configuration Tool
148 ==============================
150 Run the configtool executable and (on Linux) ignore any
151 initial console messages, which may be suppressed by
152 unarchiving ecosplatforms.tar.gz as per the installation
155 You can invoke the tool with zero, one, or two parameters. The
156 two parameters can be the location of the repository and/or
157 the location of a save file (extension .ecc). If no parameters
158 are passed, the tool will look in the current directory for a
159 save file and also (on Linux) in the /opt/ecos directory for a
160 suitable repository. Failing that, the tool will use the last
161 loaded repository or ask the user for a suitable location.
163 For detailed information about the Configuration Tool, please
164 refer to the HTML manual which may be invoked from the Help
165 menu or by clicking on the "Linux Configuration Tool Guide" in
166 the internal help system's contents. This is similar to but
167 different from "The eCos Configuration Tool" section in the
168 eCos User Guide, which refers to the original Windows version
169 of the configuration tool (as opposed to the new
170 cross-platform Linux and Windows version).
173 Frequently Asked Questions
174 ==========================
176 Q: On Linux, invoking HTML documentation for a configuration item
177 doesn't seem to work.
179 A: You need to have a .mailcap entry similar to the following:
181 text/html; netscape -no-about-splash %s
186 desc="HTML document" \
189 Also, be aware that the browser can sometimes end up behind the
190 configuration tool so it may have run even if you think it didn't.
193 Q: On Linux, right-clicking in the configuration pane and choosing
194 'What's This?' causes an information window to pop up and
195 then quickly disappear.
197 A: If the window manager options are set to raise a window when it gains
198 the focus, the information window can get sent behind the
199 application window when the popup menu loses focus. Either
200 adjust your window manager settings, or use an alternate way
201 of invoking help for the item: click on the arrow/question
202 mark toolbar button, then on the item you are interested in.
205 Q: The internal HTML help viewer doesn't display HTML correctly.
207 A: The internal HTML help viewer cannot display some of the more complex
208 HTML correctly, such as the GNUPro reference. We hope to
209 provide the documentation in a suitable form in future, but
210 for now, please use an external browser to view this
211 documentation. You can use the Settings dialog, Viewers tab,
212 to choose to view using an external browser.
215 Q: Why does the Configuration Tool use wxWindows?
217 A: wxWindows is an open source, mature multi-platform GUI
218 toolkit for C++. It makes platform-independence relatively
219 easy to achieve, whilst remaining compatibility with the
220 look and feel of GTK+ and WIN32 on the respective platforms.
221 wxWindows was chosen on its own merits but, by sheer
222 coincidence, the author of the new Configuration Tool is
223 also the original author of wxWindows. Using a
224 platform-independent API will make it easier to port the
225 Configuration Tool to other platforms if needed.
228 Q: Where can I get more information about wxWindows?
230 A: The wxWindows web site is at http://www.wxwindows.org.
231 wxWindows distributions come with documentation in a
235 Q: Does the new Configuration Tool make the old one obsolete?
237 A: Not yet. The new tool doesn't yet support some features, such
238 as the Memory Layout Tool. When these have been implemented,
239 and the tool has been subject to the required quality assurance
240 procedure, then we can retire the old tool.
243 Q: How can I help improve the Configuration Tool?
245 A: All help is very welcome: please see
246 http://sources.redhat.com/ecos/faq.html for how to
250 Q: Who do I contact when things go wrong?
252 A: Please discuss problems on the ecos-discuss mailing list:
253 see http://sources.redhat.com/ecos/intouch.html.
256 Q: The compiler fails to compile dcclient.cpp. What do I do?
258 A: It may be that you have a non-standard GTK+ 1.2.6 which has changes
259 backported from 1.2.7. Use the makefile target 'wxgtkfix' to
260 fix this after the error has happened (i.e. after configure
261 has produced the setup.h and makefiles):
263 % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=release wxgtkfix
267 % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=debug wxgtkfix
269 Now use the 'wx ecc ct' targets (not 'full') to continue
273 Building the Configuration Tool under Linux
274 ===========================================
276 This build system is subject to change.
280 o gcc 2.95.2 or later
282 o GTK+ and glib 1.2.6 or above. Please remove any 1.3 development RPMs
283 from your setup, using for example:
285 rpm -e gtk+-gtkbeta-devel-1.3.1b-2
287 You can get GTK+ and glib for Red Hat 6.2 and above from:
289 ftp://ftp.gtk.org/pub/gtk/v1.2/binary/RPMS/RedHat-6.2/RPMS/i386/gtk+-1.2.8-1.i386.rpm
290 ftp://ftp.gtk.org/pub/gtk/v1.2/binary/RPMS/RedHat-6.2/RPMS/i386/glib-1.2.8-1.i386.rpm
292 o a suitable version of wxWindows for GTK+, available from
293 from ftp://sources.redhat.com/pub/ecos/ct2/.
295 Unarchive the file wxGTK-x.y.z.tgz into a suitable directory, e.g.
297 % mkdir /home/julians/wxWindows
298 % cd /home/julians/wxWindows
299 % tar xvfz /tmp/wxGTK-x.y.z.tgz
301 You may also wish to download and unarchive wxWindows
302 documentation, which is supplied in zip form. Unarchive
305 % cd /home/julians/wxWindows
306 % unzip -a wxWindows-x.y.z-HTML.zip
308 o an eCos source hierarchy. See http://sources.redhat.com/ecos/anoncvs.html
309 for how to download this from the CVS repository. For example:
311 cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos co ecos/host
315 - Tcl/Tk 8.2 or above. See http://www.tcl.tk/
319 There is no 'configure' step for the eCos Configuration Tool
320 as a whole, although the host tool libraries and wxWindows
321 have configure scripts which are invoked by the makefile.
323 You work in a build directory of your choosing, and the
324 makefile will create the following directories underneath it:
326 ct-build-debug/ ; Configtool debug build
327 ecc-build-debug/ ; eCos libraries debug build
328 wxwin-build-debug/ ; wxWindows debug build
330 ct-build-release/ ; Configtool release build
331 ecc-build-release/ ; eCos libraries release build
332 wxwin-build-release/ ; wxWindows release build
334 You need to pass the wxWindows source directory (WXDIR) and
335 eCos hierarchy directory (ECOSDIR) to the makefile, along with
336 the build LEVEL (debug or release). Please see makect.sh in
337 the source directory, which is a useful helper script for
338 making it easier to invoke the makefile.
340 You also supply a target to build, such as full (everything),
341 ct (just the Configuration Tool), wx (wxWindows only) or ecc
342 (eCos libraries only). It is important to supply the target as
343 the _last_ command(s) on the command line.
345 The makefile builds and uses wxWindows as a static library,
346 which minimizes problems with shared libraries and still
347 results in a reasonable size of executable (4.5 MB
348 uncompressed, or under 2 MB when compressed with UPX).
349 Switching off unnecessary wxWindows features may result in
352 IMPORTANT NOTE: currently, there are inadequate dependencies
353 in the makefiles, so please make sure you start with a clean
354 directory before building (use the cleanct target if
359 1. This builds the eCos libraries, wxWindows, and the Configuration Tool,
362 % export ECOSDIR=/home/julians/cvs/eCos # The dir above 'host'
363 % export CONFIGTOOLDIR=$ECOSDIR/host/tools/configtool/standalone/wxwin
364 % export WXDIR=/home/julians/wxWindows
366 % mkdir /tmp/ecos-build
368 % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=debug full
370 2. This builds just the Configuration Tool, say after a file was edited,
373 % export ECOSDIR=/home/julians/cvs/eCos
374 % export CONFIGTOOLDIR=$ECOSDIR/host/tools/configtool/standalone/wxwin
375 % export WXDIR=/home/julians/wxWindows
378 % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=release ct
382 Please see the FAQ for what to do if the wxWindows file
383 dcclient.cpp fails to compile.
385 For more recent versions of wxWindows, you have to pass --static to wx-config.
386 If you get a lot of GTK+-related link errors, check the beginning of the makefile
387 and make sure WXCONFIGFLAGS=--static.
390 Building the Configuration Tool under Windows
391 =============================================
395 o Microsoft Visual C++ 6.0 or later
397 o a suitable version of wxWindows for MS Windows, available
398 from ftp://sources.redhat.com/pub/ecos/ct2/. To install the
399 sources in 'setup' form, just run the executable and follow
400 the instructions. If you have downloaded the sources in zip
401 format, you will need to unarchive the file wxMSW-x.y.z.zip
402 into a suitable directory, e.g.
407 > unzip c:\temp\wxMSW-x.y.z.zip
409 Alternatively, you can use WinZip or similar utility to
412 Documentation in Windows HTML Help format is supplied in
413 the setup or zipped distribution and does not have to be
414 downloaded separately.
416 o an eCos source hierarchy. See http://sources.redhat.com/ecos/anoncvs.html
417 for how to download this from the CVS repository. For example:
419 cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos co ecos/host
423 - Cygwin (sometimes called GNUPro). See http://sources.redhat.com/cygwin/
424 - Tcl/Tk 8.2 or above. See http://www.tcl.tk/
428 There are two main steps: building wxWindows, and building the Configuration Tool.
429 The Configuration Tool project file also builds the required eCos libraries.
430 Note that unlike compilation under Linux, the wxWindows objects and libraries end up in
431 the wxWindows source tree.
433 Before routinely building the Configuration Tool, you will need to set up
434 Visual C++ with the correct paths (see below).
438 1. Execute in a DOS box:
442 where d:\tmp is a suitable temporary directory where the Configuration Tool
443 binaries and objects will end up.
445 2. Set the TCLHOME environment variable to where Tcl is installed. On Windows 9x,
446 edit autoexec.bat. On Windows NT or W2K, use the System control panel applet.
448 3. Build wxWindows. To do this, run VC++ and open src/msvc.dsw in the wxWindows
449 project hierarchy. Select Build | Batch Build and check
450 wxvc - WIN32 Debug and wxvc - WIN32 Release. Click on Build.
452 4. Open the eCos/ecc/host/tools/configtool/standalone/wxwin/ConfigtoolVC.dsw
453 workspace. Choose Tools | Options and click on the Directories tab.
454 Select Show directories for: Include files.
456 You need to add paths such as these:
458 c:\Program Files\Tcl\include
459 d:\wxWindows-010212\include
461 Select Show directories for: Library files. Add these paths, changing
464 c:\Program Files\Tcl\lib
465 d:\wxWindows-010212\lib
467 5. Click on Select Active Configuration... and select the one you wish to
468 build, such as WIN32 Ansi Debug (note that Unicode configurations are
469 not yet available). Choose Build | Rebuild All to build the project.
470 The configtool.exe executable should end up in v:\Configtool\AnsiDebug.
472 When compiled, configtool.exe depends on the following DLLs found
473 in your system32 directory that should be supplied with the executable:
475 TCL82.DLL (or other name if you used a different version of TCL)