tools/src/tools/configtool/standalone/wxwin/README.txt

   1 eCos Cross-platform Configuration Tool
   2 Copyright (c) Red Hat Inc., 2001-2002
   3 ======================================
   4
   5 Version 2
   6 =========
   7
   8 Contents
   9
  10   * Introduction
  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
  17
  18
  19 Introduction
  20 ============
  21
  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.
  25
  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.
  32
  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.
  36
  37   These are the instructions for running and building the eCos
  38   Configuration Tool for Linux and Windows.
  39
  40
  41 What's in this release?
  42 =======================
  43
  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
  47   original tool:
  48
  49   - Memory Layout Tool
  50   - Administration functionality (initial code present but untested)
  51   - Gauge indicating time left to build library and tests
  52
  53   The following features are present in the new tool but not in the
  54   original tool:
  55
  56   - Repository Information dialog (available from the Help menu)
  57   - Most dialogs are resizeable
  58
  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).
  67
  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".
  73
  74 Known bugs:
  75
  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
  79     Configuration Tool).
  80
  81 Version History
  82 ---------------
  83
  84 See CHANGES.txt.
  85
  86 Installing the Configuration Tool
  87 =================================
  88
  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/.
  92
  93   See also mirror sites at:
  94
  95         http://sources.redhat.com/ecos/mirror.html
  96         http://sources.redhat.com/mirrors.html
  97
  98   Please try to use a mirror site close to you, as it will be
  99   faster.
 100
 101   *** Under Linux:
 102
 103   Download:
 104   ftp://sources.redhat.com/pub/ecos/ct2/configtool-2.0-i386.tar.gz
 105   (or similar name).
 106
 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.
 109   For example:
 110
 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
 115
 116   The following files will be extracted to the installation directory:
 117
 118   configtool
 119   configtool.bin
 120   README.txt
 121   license.txt
 122   ecosplatforms.tar.gz
 123   manual/
 124
 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.
 130
 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
 133   to be installed.
 134
 135   *** Under Windows:
 136
 137   Download configtool-2.0-setup.exe (or similar name).
 138
 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.
 145
 146
 147 Running the Configuration Tool
 148 ==============================
 149
 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
 153   instructions above.
 154
 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.
 162
 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).
 171
 172
 173 Frequently Asked Questions
 174 ==========================
 175
 176 Q:  On Linux, invoking HTML documentation for a configuration item
 177     doesn't seem to work.
 178
 179 A:  You need to have a .mailcap entry similar to the following:
 180
 181     text/html; netscape -no-about-splash %s
 182
 183     and in .mime.types:
 184
 185     type=text/html \
 186     desc="HTML document" \
 187     exts="htm,html"
 188
 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.
 191
 192
 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.
 196
 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.
 203
 204
 205 Q:  The internal HTML help viewer doesn't display HTML correctly.
 206
 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.
 213
 214
 215 Q:  Why does the Configuration Tool use wxWindows?
 216
 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.
 226
 227
 228 Q:  Where can I get more information about wxWindows?
 229
 230 A:  The wxWindows web site is at http://www.wxwindows.org.
 231     wxWindows distributions come with documentation in a
 232     variety of formats.
 233
 234
 235 Q:  Does the new Configuration Tool make the old one obsolete?
 236
 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.
 241
 242
 243 Q:  How can I help improve the Configuration Tool?
 244
 245 A:  All help is very welcome: please see
 246     http://sources.redhat.com/ecos/faq.html for how to
 247     contribute.
 248
 249
 250 Q:  Who do I contact when things go wrong?
 251
 252 A:  Please discuss problems on the ecos-discuss mailing list:
 253     see http://sources.redhat.com/ecos/intouch.html.
 254
 255
 256 Q:  The compiler fails to compile dcclient.cpp. What do I do?
 257
 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):
 262
 263     % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=release wxgtkfix
 264
 265     or
 266
 267     % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=debug wxgtkfix
 268
 269     Now use the 'wx ecc ct' targets (not 'full') to continue
 270     building.
 271
 272
 273 Building the Configuration Tool under Linux
 274 ===========================================
 275
 276 This build system is subject to change.
 277
 278 You will need:
 279
 280   o gcc 2.95.2 or later
 281
 282   o GTK+ and glib 1.2.6 or above. Please remove any 1.3 development RPMs
 283     from your setup, using for example:
 284
 285     rpm -e gtk+-gtkbeta-devel-1.3.1b-2
 286
 287     You can get GTK+ and glib for Red Hat 6.2 and above from:
 288
 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
 291
 292   o a suitable version of wxWindows for GTK+, available from
 293     from ftp://sources.redhat.com/pub/ecos/ct2/.
 294
 295     Unarchive the file wxGTK-x.y.z.tgz into a suitable directory, e.g.
 296
 297     % mkdir /home/julians/wxWindows
 298     % cd /home/julians/wxWindows
 299     % tar xvfz /tmp/wxGTK-x.y.z.tgz
 300
 301     You may also wish to download and unarchive wxWindows
 302     documentation, which is supplied in zip form. Unarchive
 303     using e.g.:
 304
 305     % cd /home/julians/wxWindows
 306     % unzip -a wxWindows-x.y.z-HTML.zip
 307
 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:
 310
 311     cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos co ecos/host
 312
 313   o other tools:
 314
 315     - Tcl/Tk 8.2 or above. See http://www.tcl.tk/
 316
 317 Summary:
 318
 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.
 322
 323   You work in a build directory of your choosing, and the
 324   makefile will create the following directories underneath it:
 325
 326   ct-build-debug/               ; Configtool debug build
 327   ecc-build-debug/              ; eCos libraries debug build
 328   wxwin-build-debug/            ; wxWindows debug build
 329
 330   ct-build-release/             ; Configtool release build
 331   ecc-build-release/            ; eCos libraries release build
 332   wxwin-build-release/          ; wxWindows release build
 333
 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.
 339
 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.
 344
 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
 350   smaller executables.
 351
 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
 355   necessary).
 356
 357 Examples:
 358
 359   1. This builds the eCos libraries, wxWindows, and the Configuration Tool,
 360      in debug mode.
 361
 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
 365      %
 366      % mkdir /tmp/ecos-build
 367      % cd /tmp/ecos-build
 368      % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=debug full
 369
 370   2. This builds just the Configuration Tool, say after a file was edited,
 371      in release mode.
 372
 373      % export ECOSDIR=/home/julians/cvs/eCos
 374      % export CONFIGTOOLDIR=$ECOSDIR/host/tools/configtool/standalone/wxwin
 375      % export WXDIR=/home/julians/wxWindows
 376      %
 377      % cd /tmp/ecos-build
 378      % make -f $CONFIGTOOLDIR/Makefile WXDIR=$WXDIR ECOSDIR=$ECOSDIR LEVEL=release ct
 379
 380   *** Troubleshooting
 381
 382   Please see the FAQ for what to do if the wxWindows file
 383   dcclient.cpp fails to compile.
 384
 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.
 388
 389
 390 Building the Configuration Tool under Windows
 391 =============================================
 392
 393 You will need:
 394
 395   o Microsoft Visual C++ 6.0 or later
 396
 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.
 403
 404     > mkdir c:\wxWindows
 405     > c:
 406     > cd \wxWindows
 407     > unzip c:\temp\wxMSW-x.y.z.zip
 408
 409     Alternatively, you can use WinZip or similar utility to
 410     unarchive the files.
 411
 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.
 415
 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:
 418
 419     cvs -d :pserver:anoncvs@sources.redhat.com:/cvs/ecos co ecos/host
 420
 421   o other tools:
 422
 423     - Cygwin (sometimes called GNUPro). See http://sources.redhat.com/cygwin/
 424     - Tcl/Tk 8.2 or above. See http://www.tcl.tk/
 425
 426 Summary:
 427
 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.
 432
 433   Before routinely building the Configuration Tool, you will need to set up
 434   Visual C++ with the correct paths (see below).
 435
 436 Steps:
 437
 438   1. Execute in a DOS box:
 439
 440      subst v: d:\tmp
 441
 442      where d:\tmp is a suitable temporary directory where the Configuration Tool
 443      binaries and objects will end up.
 444
 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.
 447
 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.
 451
 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.
 455
 456      You need to add paths such as these:
 457
 458      c:\Program Files\Tcl\include
 459      d:\wxWindows-010212\include
 460
 461      Select Show directories for: Library files. Add these paths, changing
 462      as necessary:
 463
 464      c:\Program Files\Tcl\lib
 465      d:\wxWindows-010212\lib
 466
 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.
 471
 472 When compiled, configtool.exe depends on the following DLLs found
 473 in your system32 directory that should be supplied with the executable:
 474
 475   TCL82.DLL (or other name if you used a different version of TCL)
 476   MSVCIRT.DLL
 477   MSVCP60.DLL
 478   MSVCRT.DLL
 479