Tcl/Tk 8.0 for Windows, Binary Distribution

@(#) README 1.16 96/12/18 17:49:45

1. Introduction
--------------- 

This directory contains the binary distribution of Tcl/Tk 8.0 for
Windows.  It was compiled with Borland C++ 4.52 using Win32 API, so
that it will run under Windows NT, Windows 95, and Windows 3.1 (with
Win32s).  The information here corresponds to release 8.0a1, the first
alpha release for Tcl 8.0. This is a major new release that replaces
the core of the interpreter with an on-the-fly bytecode compiler to
improve execution speed.  It also includes several other new features
and many bug fixes.  The compiler introduces several incompatibilities
that may affect existing Tcl scripts; the incompatibilities are
relatively obscure but may require modifications to some old scripts
before they can run with this version.  The compiler introduces many
new C-level APIs, but the old APIs are still supported. See below for
more details.

This release also corresponds to Tk 8.0a1, the first alpha release of
Tk 8.0.  This is a major release with significant new features such as
native look and feel on Macintoshes and PCs, a new font mechanism,
application embedding, and proper support for Safe-Tcl.  See below for
details.  There should be no backward incompatibilities in Tk 8.0 that
affect scripts.

Note: with this release the Tk version number skips from 4.2 to 8.0.
The jump was made in order to synchronize the Tcl and Tk version
numbers.

Alpha 1 release note: Win32s support is currently broken by the new
font mechanism.  This means that Tk applications will not work under
Win32s.  Tcl-only applications should work, however.  We are working
to fix this for the alpha 2 release.

2. Documentation
----------------

The best way to get started with Tcl is to read one of the introductory
books on Tcl:

    Tcl and the Tk Toolkit, by John Ousterhout,
    Addison-Wesley, 1994, ISBN 0-201-63337-X

    Practical Programming in Tcl and Tk, by Brent Welch,
    Prentice-Hall, 1995, ISBN 0-13-182007-9

    Exploring Expect, by Don Libes,
    O'Reilly and Associates, 1995, ISBN 1-56592-090-2

The "doc" subdirectory in this release contains a complete set of
reference manual entries in Windows help format. 

The "lib/tk8.0/demos" directory contains a number of pre-canned
scripts that demonstrate various features of Tk.  The file
"lib/tk8.0/demos/widget.tcl" is a script that you can use to invoke
many individual demonstrations of Tk's facilities.

Additional information is available in the source release or from the
Tcl/Tk home page on the Web:

	http://www.sunlabs.com/research/tcl

These Web pages include release updates, reports on bug fixes and porting
issues, HTML versions of the manual pages, and pointers to many other
Tcl/Tk Web pages at other sites.  Check them out!

3. Installation
---------------

The binary release is distributed as a self-extracting archive called
tcl80.exe.  The setup program which will prompt you for an
installation directory.  It will create the installation heirarchy
under the specified directory, and install a wish application icon
under the program manager group of your choice.

In order to run Tcl/Tk under Windows 3.1, you will need to install the
latest release of Win32s first.  The Win32s distribution can be found
in the same location as the Tcl/Tk binary and source distributions.
The 1.30 release of Win32s is available along with the binary and
source distributions.  Look for a file called w32s130.exe.  Note that
the 1.25 version used in previous releases will not work with the
current version of Tk.  You must upgrade to Win32s 1.30.  Win32s is
not needed to run under Windows '95 or Windows NT.

4. Summary of changes in Tcl 8.0
--------------------------------

Here are the most significant changes in Tcl 8.0.  In addition to these
changes, there are several smaller changes and bug fixes.  See the file
"changes" for a complete list of all changes.

    1. Bytecode compiler.  The core of the Tcl interpreter has been
    replaced with an on-the-fly compiler that translates Tcl scripts to
    byte codes; a new interpreter then executes the byte codes. In
    earlier versions of Tcl, strings were used as a universal
    representation;  in Tcl 8.0 strings are replaced with Tcl_Obj
    structures ("objects") that can hold both a string value and an
    internal form such as a binary integer or compiled bytecodes.  The
    new objects make it possible to store information in efficient
    internal forms and avoid the constant translations to and from
    strings that occurred with the old interpreter.  We have not yet
    converted all of Tcl to take full advantage of the compiler and
    objects and have not converted any of Tk yet, but even so you
    should see speedups of 2-3x on many programs and you may see
    speedups as much as 10-20x in some cases (such as code that
    manipulates long lists).  Future releases should achieve even
    greater speedups.  The compiler introduces only a few minor changes
    at the level of Tcl scripts, but it introduces many new C APIs for
    managing objects.  See, for example, the manual entries doc/*Obj*.3.

    2. Safe-Tcl enhancements.  There is a new "hidden command"
    mechanism, implemented with the Tcl commands "interp hide", "interp
    expose", "interp invokehidden", and "interp hidden" and the C APIs
    Tcl_HideCommand and Tcl_ExposeCommand.  There is now support for
    loadable security policies, including new library procedures such as
    tcl_safeCreateInterp.

    3. There are new library procedures for doing GET, POST, and HEAD
    requests via the HTTP/1.0 protocol.  See the manual entry http.n
    for details.

    4. There are new library procedures for finding word breaks in
    strings.  See the manual entry library.n for details.

    5. There are new C APIs Tcl_Finalize (for cleaning up before
    unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
    channel's input buffer.

Tcl 8.0 introduces the following incompatibilities that may affect Tcl
scripts that worked under Tcl 7.6 and earlier releases:

    1. The semantics of some Tcl commands have been changed slightly to
    maximize performance under the compiler.  These incompatibilities
    are documented on the Web so that we can keep the list up-to-date.
    See the URL http://www.sunlabs.com/research/tcl/compiler.html.

    2. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
    are no longer supported; all of these features are now available on
    all platforms via the "file" command.

5. Summary of changes in Tk 8.0
-------------------------------

Here is a list of the most important new features in Tk 8.0.  The
release also includes several smaller feature changes and bug fixes. 
See the "changes" file for a complete list of all changes.

    1. Native look and feel.  The widgets have been rewritten to provide
    (nearly?) native look and feel on the Macintosh and PC.  Many
    widgets, including scrollbars, menus, and the button family, are
    implemented with native platform widgets.  Others, such as entries
    and texts, have been modified to emulate native look and feel. 
    These changes are backwards compatible except that (a) some
    configuration options are now ignored on some platforms and (b) you
    must use the new menu mechanism described below to native look and
    feel for menus.

    2. There is a new interface for creating menus, where a menubar is
    implemented as a menu widget instead of a frame containing menubuttons.
    The -menu option for a toplevel is used to specify the name of the
    menubar; the menu will be displayed *outside* the toplevel using
    different mechanisms on each platform (e.g. on the Macintosh the menu
    will appear at the top of the screen).  See the menu demos in the
    widget demo for examples.  The old style of menus still works, but
    does not provide native look and feel.

    3. The font mechanism in Tk has been completely reworked:
	- Font names need not be nasty X LFDs: more intuitive names
	  like {Times 12 Bold} can also be used.  See the manual entry
	  font.n for details.
	- Font requests always succeed now.  If the requested font is
	  not available, Tk finds the closest available font and uses
	  that one.
	- Tk now supports named fonts whose precise attributes can be
	  changed dynamically.  If a named font is changed, any widget
	  using that font updates itself to reflect the change.
	- There is a new command "font" for creating named fonts and
	  querying various information about fonts.
	- There are now officially supported C APIs for measuring and
	  displaying text.  If you use these APIs now, your code will
	  automatically handle international text when internationalization
	  is added to Tk in a future release.  See the manual entries
	  MeasureChar.3, TextLayout.3, and FontId.3.
	- The old C procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
	  and Tk_FreeFontStruct have been replaced with more portable
	  procedures Tk_GetFont, Tk_NameOfFont, and Tk_FreeFont.

    4. Application embedding.  It is now possible to embedded one Tcl/Tk
    application inside another, using the -container option on frame
    widgets and the -use option for toplevel widgets or on the command
    line for wish.  Embedding should be fully functional under Unix,
    but the implementation is incomplete on the Macintosh and PC.

    5. Tk now works correctly with Safe-Tcl: it can be loaded into
    safe interpreters.

    6. Text widgets now allow images to be embedded directly in the
    text without using embedded windows.  This is more efficient and
    provides smoother scrolling.

    7. On Unix, default border widths have been changed from 2 to 1
    to provide a more CDE-like appearance.

    8. Buttons have a new -default option for drawing default rings in
    a platform-specific manner.

    9. The Macintosh now supports native bitmaps, including new builtin
    bitmaps "stop", "caution", and "note", plus the ability to use
    bitmaps in the application's resource fork.

    10. The "destroy" command now ignores windows that don't exist
    instead of generating an error.

The only incompatibility introduced by this release of Tk is the
removal of the procedures Tk_GetFontStruct, Tk_NameOfFontStruct,
and Tk_FreeFontStruct, which only affects C code.  However, the
new compiler in Tcl 8.0 may affect Tcl/Tk scripts; check the Tcl
documentation for information on incompatibilities introduced by
Tcl 8.0.

6. Known Bugs/Missing Features
------------------------------

- Non-blocking connect for sockets does not work yet.
- file events only work on sockets
- The library cannot be used by two processes at the same time under
  Win32s.  This is probably fixable, but may take a while.
- There is no support for custom cursors/application icons.  The core
  set of X cursors is supported, although you cannot change their color.
- Stippling of arcs isn't implemented yet.
- Some "wm" functions don't map to Windows and aren't implemented.
- Some video devices are incorrectly reported as monochrome.
- "send" and "winfo interps" don't do anything yet.
- Tk doesn't work under Win32s right now.
- The console window pops up even for non-interactive apps.
- Printing does not work for images on a canvas.
- Button 2 events are generated with the shift bit set even when not shifted.

There may be more that we don't know about, so be sure to submit bug
reports when you run into problems.  If you have comments or bug
reports for the Windows version of Tcl, please direct them to:

Scott Stanton
scott.stanton@eng.sun.com

or post them to the newsgroup comp.lang.tcl.

7. Tcl newsgroup
-----------------

There is a network news group "comp.lang.tcl" intended for the exchange
of information about Tcl, Tk, and related applications.  Feel free to use
the newsgroup both for general information questions and for bug reports.
We read the newsgroup and will attempt to fix bugs and problems reported
to it.

When using comp.lang.tcl, please be sure that your e-mail return address
is correctly set in your postings.  This allows people to respond directly
to you, rather than the entire newsgroup, for answers that are not of
general interest.  A bad e-mail return address may prevent you from
getting answers to your questions.  You may have to reconfigure your news
reading software to ensure that it is supplying valid e-mail addresses.

8. Tcl contributed archive
--------------------------

Many people have created exciting packages and applications based on Tcl
and/or Tk and made them freely available to the Tcl community.  An archive
of these contributions is kept on the machine ftp.neosoft.com.  You
can access the archive using anonymous FTP;  the Tcl contributed archive is
in the directory "/pub/tcl".  The archive also contains several FAQ
("frequently asked questions") documents that provide solutions to problems
that are commonly encountered by TCL newcomers.

9. Support and bug fixes
------------------------

We're very interested in receiving bug reports and suggestions for
improvements.  We prefer that you send this information to the
comp.lang.tcl newsgroup rather than to any of us at Sun.  We'll see
anything on comp.lang.tcl, and in addition someone else who reads 
omp.lang.tcl may be able to offer a solution.  The normal turn-around
time for bugs is 2-4 weeks.  Enhancements may take longer and may not
happen at all unless there is widespread support for them (we're
trying to slow the rate at which Tcl turns into a kitchen sink).  It's
very difficult to make incompatible changes to Tcl at this point, due
to the size of the installed base.

When reporting bugs, please provide a short tclsh script that we can
use to reproduce the bug.  Make sure that the script runs with a
bare-bones tclsh and doesn't depend on any extensions or other
programs, particularly those that exist only at your site.  Also,
please include three additional pieces of information with the
script:
    (a) how do we use the script to make the problem happen (e.g.
	what things do we click on, in what order)?
    (b) what happens when you do these things (presumably this is
        undesirable)?
    (c) what did you expect to happen instead?

The Tcl community is too large for us to provide much individual
support for users.  If you need help we suggest that you post questions
to comp.lang.tcl.  We read the newsgroup and will attempt to answer
esoteric questions for which no-one else is likely to know the answer.
In addition, Tcl support and training are available commercially from
NeoSoft (info@neosoft.com), Computerized Processes Unlimited
(gwl@cpu.com), and Data Kinetics (education@dkl.com).

10. Tcl version numbers
----------------------

Each Tcl release is identified by two numbers separated by a dot, e.g.
6.7 or 7.0.  If a new release contains changes that are likely to break
existing C code or Tcl scripts then the major release number increments
and the minor number resets to zero: 6.0, 7.0, etc.  If a new release
contains only bug fixes and compatible changes, then the minor number
increments without changing the major number, e.g. 7.1, 7.2, etc.  If
you have C code or Tcl scripts that work with release X.Y, then they
should also work with any release X.Z as long as Z > Y.

Alpha and beta releases have an additional suffix of the form a2 or b1.
For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0,
Tcl 7.0b2 is the second beta release, and so on.  A beta release is an
initial version of a new release, used to fix bugs and bad features before
declaring the release stable.  An alpha release is like a beta release,
except it's likely to need even more work before it's "ready for prime
time".  New releases are normally preceded by one or more alpha and beta
releases.  We hope that lots of people will try out the alpha and beta
releases and report problems.  We'll make new alpha/beta releases to fix
the problems, until eventually there is a beta release that appears to
be stable.  Once this occurs we'll make the final release.

We can't promise to maintain compatibility among alpha and beta releases.
For example, release 7.1b2 may not be backward compatible with 7.1b1, even
though the final 7.1 release will be backward compatible with 7.0.  This
allows us to change new features as we find problems during beta testing.
We'll try to minimize incompatibilities between beta releases, but if
a major problem turns up then we'll fix it even if it introduces an
incompatibility.  Once the official release is made then there won't
be any more incompatibilities until the next release with a new major
version number.

Patch releases have a suffix such as p1 or p2.  These releases contain
bug fixes only.  A patch release (e.g Tcl 7.6p2) should be completely
compatible with the base release from which it is derived (e.g. Tcl
7.6), and you should normally use the highest available patch release.

11. Using the binary release with Borland compilers
---------------------------------------------------

Before you can link your applications against the .dll files shipped
with this release, you will need to generate the appropriate .lib
files using the following commands:

	implib tcl80.lib <path to tcl80.dll>
	implib tk80.lib <path to tk80.dll>

This will leave the tcl80.lib and tk80.lib files sitting in the
current directory.  You may then use these libraries when linking your
applications.

12. Using the binary release with Visual C++
--------------------------------------------

Before you can link your applications against the .dll files shipped
with this release, you will need to obtain the .lib files from the
official Tcl ftp site:

	ftp://ftp.sunlabs.com/pub/tcl/vclibs80.zip

This file is a compressed archive containing tcl80.lib and tk80.lib in
the appropriate format for Visual C++.  You may then use these
libraries when linking your applications.

13. Building dynamically loadable extensions
--------------------------------------------

Please refer to the example dynamically loadable extension provided on
our ftp site:

	ftp://ftp.sunlabs.com/pub/tcl/example.zip

This archive contains a template that you can use for building
extensions that will be loadable on Unix, Windows, and Macintosh
systems.
