summaryrefslogtreecommitdiffstats
path: root/win/README
blob: 162a9f0d1a6a51c1be0b8999471cf8e3897fd8fa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
Tcl 8.0p2 for Windows

by Scott Stanton
Sun Microsystems Laboratories
scott.stanton@eng.sun.com

SCCS: @(#) README 1.25 97/11/21 15:15:40

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

This is the directory where you configure and compile the Windows
version of Tcl.  This directory also contains source files for Tcl
that are specific to Microsoft Windows.  The rest of this file
contains information specific to the Windows version of Tcl.

2. Distribution notes
---------------------

Tcl 8.0 for Windows is distributed in binary form in addition to the
common source release.  The binary distribution is a self-extracting
archive with a built-in installation script.

Look for the binary release in the same location as the source release
(ftp.scriptics.com:/pub/tcl or any of the mirror sites).  For most users,
the binary release will be much easier to install and use.  You only
need the source release if you plan to modify the core of Tcl, or if
you need to compile with a different compiler.  With the addition of
the dynamic loading interface, it is no longer necessary to have the
source distribution in order to build and use extensions.

3. Compiling Tcl
----------------

In order to compile Tcl for Windows, you need the following items:

	Tcl 8.0 Source Distribution (plus any patches)

	Borland C++ 4.52 (both 16-bit and 32-bit compilers)
	  or
	Visual C++ 2.x/4.x/5.x
	Visual C++ 1.5 (to build tcl1680.dll for Win32s support of exec)

In practice, the 8.0.3 release is built with Visual C++ 5.0

In the "win" subdirectory of the source release, you will find two
files called "makefile.bc" and "makefile.vc".  These are the makefiles
for the Borland and Visual C++ compilers respectively.  You should
copy the appropriate one to "makefile" and update the paths at the
top of the file to reflect your system configuration.  Now you can use
"make" (or "nmake" for VC++) to build the tcl libraries and the tclsh
executable.

In order to use the binaries generated by these makefiles, you will
need to place the Tcl script library files someplace where Tcl can
find them.  Tcl looks in one of three places for the library files:

	1) The path specified in the environment variable "TCL_LIBRARY".

	2) In the lib\tcl8.0 directory under the installation directory
	   as specified in the registry:

		For Windows NT & 95:
		    HKEY_LOCAL_MACHINE\SOFTWARE\Scriptics\Tcl\8.0

		For Win32s:
		    HKEY_CLASSES_ROOT\SOFTWARE\Scriptics\Tcl\8.0\

	3) Relative to the directory containing the current .exe.
	    Tcl will look for a directory "..\lib\tcl8.0" relative to the
	    directory containing the currently running .exe.

Note that in order to run tclsh80.exe, you must ensure that tcl80.dll
and tclpip80.dll (plus tcl1680.dll under Win32s) are on your path, in
the system directory, or in the directory containing tclsh80.exe.

4. Building Extensions
----------------------

With the Windows compilers you have to worry about how you export symbols
from DLLs.  tcl.h defines a few macros to help solve this problem:
EXTERN - all Tcl_ function prototypes use this macro, which implies
	they are exported.  You'll see this used in tcl.h and tk.h.
	You should use this in your exported procedures.
	However, this is not the whole story.
EXPORT - this is really an import/export flag, depending on if you are
	importing symbols from a DLL (i.e., a user of the DLL), or if
	you are exporting symbols from the DLL (i.e., you are building it.)
	The EXTERN macro includes EXPORT.
	EXPORT is defined to be either DLLIMPORT or DLLEXPORT as
	described below.
STATIC_BUILD - define this if you are *not* building a DLL
	(e.g., a main program)
DLL_BUILD - define this if you *are* building a DLL
DLLIMPORT - If STATIC_BUILD is defined, this becomes nothing.
	(On UNIX, DLLIMPORT is defined to be empty)
	Otherwise, this this expands to __declspec(dllimport)
DLLEXPORT - If STATIC_BUILD is defined, this becomes nothing.
	(On UNIX, DLLEXPORT is defined to be empty)
	Otherwise, this this expands to __declspec(dllexport)

How to use these:

Assume your extension is named Foo.  In its Makefile, define
BUILD_Foo so that you know you are building Foo and not using it.
Then, in your main header file, foo.h, conditionally define
EXPORT to be either DLLIMPORT or DLLEXPORT based on the
presense of BUILD_Foo, like this:

#ifndef _FOO
#define _FOO
#include "tcl.h"
/* Additional includes go here */
/*
 * if the BUILD_foo macro is defined, the assumption is that we are
 * building the dynamic library.
 */
#ifdef BUILD_Foo
#  undef EXPORT
#  define EXPORT DLLEXPORT
#endif
/*
 * Function prototypes for this module.
 */
EXTERN int Foo_Init _ANSI_ARGS_((Tcl_Interp *interp));
EXTERN int Foo_SafeInit _ANSI_ARGS_((Tcl_Interp *interp));
/* Additional prototypes go here */
/*
 * end of foo.h
 * reset EXPORT to DLLIMPORT.
 */
# undef EXPORT
# define EXPORT DLLIMPORT
#endif /* _FOO */

5. Test suite
-------------

This distribution contains an extensive test suite for Tcl.  Some of
the tests are timing dependent and will fail from time to time.  If a
test is failing consistently, please send us a bug report with as much
detail as you can manage.

In order to run the test suite, you build the "test" target using the
appropriate makefile for your compiler.


6. Known Bugs
-------------

Here is the current list of known bugs/missing features for the
Windows version of Tcl:

- Blocking "after" commands (e.g. "after 3000") don't work on Win32s.
- Clock command fails to handle daylight savings time boundaries for
  things like "last week".
- Background processes aren't properly detached on NT.
- File events only work on sockets.
- Pipes/files/console/serial ports don't support nonblocking I/O.
- The library cannot be used by two processes at the same time under
  Win32s.

If you have comments or bug reports for the Windows version of Tcl,
please direct them to:

<bugs@scriptics.com>

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