Tcl 7.6 and Tk 4.2 for Windows, Binary Distribution

@(#) README.binary 1.1 97/01/28 17:36:08

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

This directory contains the binary distribution of Tcl 7.6 and Tk 4.2
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 7.6 and 4.2.

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/tk4.2/demos" directory contains a number of pre-canned
scripts that demonstrate various features of Tk.  The file
"lib/tk4.2/demos" 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 udpates, reports on bug fixes and
porting issues, 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
win76.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.25 release of Win32s is available along with the binary and
source distributions.  Look for a file called w32s125.exe.  Win32s is
not needed to run under Windows '95 or Windows NT.

4. Summary of changes in Tcl 7.6 and Tk 4.2
-------------------------------------------

Here are the most significant changes in Tcl 7.6.  In addition to these
changes, there are numerous small bug fixes.  See the "changes" file
in the source release for a complete list of all changes.

    1. New file manipulation commands.  There are new options to the
    "file" command for copying files ("file copy"), deleting files and
    directories ("file delete"), creating directories ("file mkdir"),
    and renaming files ("file rename").

    2. The implementation of "exec" has been improved greatly for Windows
    95 and Windows NT.

    3. There is a new C library procedure Tcl_Ungets for pushing bytes back
    into the input buffer of an I/O channel.

    4. There is a new memory allocator for the Macintosh version, which
    should be more efficient than the old one.

Tcl 7.6 contains two incompatible changes:
    1. The C interfaces to channel drivers have been revised to eliminate
    the use of Tcl_File handles in the interfaces.  Instead, there are
    new interface procedures channelReadyProc, watchChannelProc, and
    getFileProc.  This change does not affect Tcl scripts; it will only
    affect you if you have written a custom channel driver.

    2. Under Windows, tclsh now looks for the start-up file "tclshrc.tcl"
    instead of "tclsh.rc".  This is more consistent with wish and uses
    the right extension.

Here are the new features in Tk 4.2.  The release also includes several
bug fixes.  See the "changes" file for a complete list of all changes.

    1. The grid geometry manager has been completely rewritten:
        - The layout algorithm produces much better layouts than before,
	  particularly where rows or columns were stretchable.
	- There is a new -pad option for rows and columns.
	- The command "grid forget" has been renamed "grid remove",
	  and "grid forget" now has semantics like "pack forget".
	- The "grid" command no longer accepts floating-point values
	  for row or column weights: integers must be used.

    2. There are new commands for creating common dialog boxes:
    tk_chooseColor, tk_getOpenFile, tk_getSaveFile and tk_messageBox.
    These use native dialog boxes if they are available.  Examples of
    the dialogs are available in the widget demo.

    3. There is a new virtual event mechanism for handling events in a
    more portable way.  See the new command "event".  It also allows
    events (both physical and virtual) to be generated dynamically.
    The Macintosh now generates <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>>
    events from the edit menu.

The only incompatible changes in this release are the last two for the
gridder ("grid forget" and integer row/column weights).  Most scripts
that ran under Tk 4.1 should also work under Tk 4.2 with no changes.

5. Summary of changes in Tcl 7.5 and Tk 4.1
-------------------------------------------

The most important change for Tcl 7.5 is that Tcl now runs on Macintosh
and PC platforms as well as UNIX.  The PC port runs under Windows 3.1
(with Win32s), Windows 95, and Windows NT.  This required a lot of
reorganization of the sources but it didn't require any changes to
Tcl's externally visible interfaces.

In addition to the ports, Tcl 7.5 also has many other new features.
The following feature changes have occurred since Tcl 7.4:

    1. Dynamic loading.  There is a new "load" command for loading binary
    extensions into Tcl on the fly.  This works now on most of the major
    UNIX platforms as well as PCs and Macintoshes.  Three new "info"
    commands, "info loaded", "info sharedlibextension", and
    "info nameofexecutable", were also added as part of the dynamic loading
    implementation.  You can also create Tcl and Tk themselves as shared
    libraries with the --enable-shared switch to the configure script.

    2. Packages and versions.  There is a new "package" command for
    package and version management.  See the manual entries for "package"
    and "pkg_mkIndex" for details on how to use it.  There are also
    C APIs to the package mechanism.  See PkgRequire.3.
    
    3. Multiple interpreters and Safe-Tcl.  There is a new "interp" command
    that allows you to create multiple interpreters within a single application
    and set up communication between them with "aliases".  The mechanism also
    supports "safe" interpreters, which provide a generalized version of the
    security mechanisms in Borenstein and Rose's Safe-Tcl.  There are still
    a few missing security features, such as resource control.  You can use
    "load" to add extensions (including Tk) into slave interpreters.

    4. The event loop from Tk has been moved to Tcl.  Tcl now has commands
    "after", "fileevent", "update", and "vwait" (which replaces tkwait).
    The "tkerror" command has been renamed to "bgerror".  "Tkerror" is
    still supported for backwards compatibility, but you should switch ASAP
    to using "bgerror" instead.  Many C procedures that used to be in Tk
    have been moved to Tcl and renamed, such as Tcl_DoOneEvent, Tcl_DoWhenIdle,
    Tcl_CreateFileHandler, and Tcl_CreateTimerHandler.

    5. Tcl has a whole new I/O system.  All of the Tcl commands like
    "open" and "puts" should continue to operate as before, but there
    is a totally new implementation that doesn't use the C stdio library:
	- The new I/O system is more portable, and it can be extended
	  with new kinds of I/O channels;  see CrtChannel.3 for details.
	- Nonblocking I/O is supported on all platforms and there is a
	  new command "fconfigure" to enable it and other channel options;
	  see fconfigure.n for details.  There is also a new "fblocked"
	  command.
	- The I/O system automatically translates between different
	  end-of-line representations (such as CR on Macs and CRLF on
	  PC's) to the newline form used in UNIX and in all Tcl scripts;
	  the "fconfigure" command can be used to control this feature.
	- There is a set of C APIs for manipulating Tcl_Channel's, which
	  are analogous to UNIX FILE's.  The C procedures have roughly the
	  same functionality as the stdio procedures.  See OpenFileChnl.3,
	  CrtCloseHdlr.3, and CrtChnlHdlr.3 for details.
	- There is a new structure Tcl_File that provides platform-
	  independent access to file handles such as UNIX fd's.  See
	  GetFile.3 for details.
	- There are new procedures Tcl_GetErrno and Tcl_SetErrno for
	  accessing the "errno" variable in a safe and portable fashion.
	  See SetErrno.3.

    6. There are new commands "file split", "file join", and "file pathtype",
    which make it possible to handle file names in a way that will work on
    all platforms.  See the manual entries file.n and filename.n for
    details.

    7. There is a new "socket" command for network communication via
    TCP sockets.  It works for both the client and server sides.  There
    is also C-level support for sockets;  see OpenTcp.3.

    8. There is a new "clock" command, which contains the functionality
    of the TclX clock-handling commands.

    9. The "foreach" command has been generalized significantly to support
    multiple lists and multiple variables iterating over each list.

    10. There is a new "notifier" mechanism, which was added as part of
    the ports.  This allows the basic mechanisms for reporting events
    to be implemented in different ways on different platforms.  It
    may also be useful for other purposes, such as merging the Tk and
    Xt event loops so that Tk and Xt widgets can coexist in a single
    application.  See the manual entry Notifier.3 for more information.

    11. There is an "AssocData" mechanism that allows extensions to store
    their own data in an interpreter and get called back when the interpreter
    is deleted.  This is visible at C level via the procedures Tcl_SetAssocData
    and Tcl_GetAssocData.

    12. When manual pages are installed, additional links are created for
    each of the procedures described in the manual page, so that it's
    easier to invoke the "man" command.

    13. There is a new variable "tcl_platform" with platform information.
    This is an associative array with elements like "os" and "machine"
    that contain various pieces of information about the platform.

    14. There is a new procedure Tcl_CreateExitHandler that you can use to
    make sure a C procedure is called before the Tcl application exits.

    15. There is a new procedure Tcl_UpdateLinkedVar to force the Tcl-level
    variable to be updated after you've changed the corresponding C-level
    variable.

    16. The procedures Tk_Preserve, Tk_Release, and Tk_EventuallyFree
    have been moved from Tk to Tcl and given names like Tcl_Preserve.

Three incompatibilities were introduced by the changes.  All of these
are at C-level, and only the first one should have much impact.  Existing
scripts for Tcl 7.4 should run unchanged  under Tcl 7.5.

    1. The procedure Tcl_EnterFile no longer exists.  However, a new
    procedure Tcl_MakeFileChannel provides similar functionality.
    Tcl_GetOpenFile still exists but only works under UNIX.
    Tcl_CreatePipeline also remains, but it too works only under UNIX
    now;  use Tcl_OpenCommandChannel for better portability.

    2. Tcl doesn't export any global C variables anymore, because this doesn't
    work with Windows DLLs.  The C variables tcl_AsyncReady and
    tcl_FileCloseProc have been replaced with procedures Tcl_AsyncReady()
    and Tcl_SetFileCloseProc().  The C variable tcl_RcFileName has been
    replaced with a Tcl variable tcl_rcFileName.
    
    3. Files are no longer shared between interpreters by default:  if a
    file is opened in one interpreter, it cannot normally be used in other
    interpreters.  However, the new procedure Tcl_ShareHandle allows files
    to be shared between interpreters if requested explicitly.

Besides the ports and numerous bug fixes, Tk 4.1 contains the following
new features.  Existing scripts for Tk 4.0 should run unchanged under
Tk 4.1.

    1. There is a new command "grid" that implements a table style of
       geometry management.   This will be used by future releases of
       the SpecTcl GUI builder.

    2. The wish main program now supports -visual and -colormap command-
       line arguments.

    3. Text widgets have been improved in several ways:
	- Performance when there are many tags should be much better now;
	  tags should only be slow if there are a very large number of tags
	  on an individual character.
	- There are new "dump", "mark next", "mark prev" and "tag prevrange"
	  widget commands for extracting information out of a text widget.

    4. Tk is now a first-class Tcl package (in the sense of the new
       Tcl "package" command).  You can load Tk into a slave interpreter
       "foo" with the command "load {} Tk foo" if Tk is statically
       linked.  Tk can also be compiled as a shared library using the
       --enable-shared switch for "configure".

    5. The event loop has moved to Tcl.  Many procedures and #defines
       have been renamed, such as the "tkerror" command (now "bgerror"),
       TK_READABLE (now TCL_READABLE), and Tk_DoOneEvent (now
       Tcl_DoOneEvent).  All of the old Tk names are still supported
       for backwards compatibility but you should switch over ASAP to
       the new ones.

    6. Tk_Preserve, Tk_Release, and Tk_Eventually have been moved to Tcl.
       There are #defines in tk.h for backward compatibility, but you
       should switch ASAP to the new Tcl APIs.

    7. There is a new command "after info" that allows you to find out about
       pending "after" handlers that haven't yet fired.

    8. Scrollbars and scales now have proper button 2 support as required
       by Motif.

    9. Menus have two new options, -transient and -tearoffcommand.

    10. Entries have a new "bbox" widget command.

    11. When manual pages are installed, additional links are created for
       each of the procedures described in the manual page, so that it's
       easier to invoke the "man" command.

    12. Wish supports a new "--" option:  it will only process options
       up through the --;  anything after that will be passed through
       to the application in the argc and argv variables.

Although Tk 4.1 is compatible with Tk 4.0 scripts at the Tcl level,
there are a few incompatible changes in Tk's C APIs.  These will
only affect C code, not Tcl/Tk scripts, and they are obscure enough that
they probably won't affect many existing extensions.  If there are any
potential problems, they will be detected by an ANSI-compliant C compiler
such as gcc.

    1. The procedure Tk_CreateMainWindow no longer exists.  Instead,
       Tk_Init does everything that Tk_CreateMainWindow used to do.

    2. The procedures Tk_EventInit and Tk_CreateFileHandler2 have been
       eliminated.  Tk_EventInit is no longer needed since the event loop
       is always available.  Tk_CreateFileHandler doesn't make sense with
       the new notifier in Tcl, but you can get the same effect with the
       new "event source" mechanism (see the Notifier.3 manual entry in
       Tcl).

    3. Tk doesn't export any global C variables anymore, because this
       doesn't work with Windows DLLs.  The C variable tk_NumMainWindows
       has been replaced with the procedures Tk_GetNumMainWindows(), and
       the variable tk_CanvasTagsOption has been replaced with the
       procedures Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc.

    4. The interface to Tk_RestrictProc has changed so that the restrict
       procedure can ask for an event to be discarded, as well as processed
       or deferred.

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.
- There is no support for the option database yet.
- Some video devices are incorrectly reported as monochrome.
- Some video configurations cause resource leakage under Win32s.
- "send" and "winfo interps" don't do anything yet.

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. Release organization
------------------------

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.

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 tcl76.lib <path to tcl76.dll>
	implib tk42.lib <path to tk42.dll>

This will leave the tcl76.lib and tk42.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/vclibs76.zip

This file is a compressed archive containing tcl76.lib and tk42.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.
