As approved in TIP 27 [http://purl.org/tcl/tip/27.html], several
of the public C functions provided by the Tcl and Tk libraries
have had their declarations augmented with the addition of
CONST modifiers on pointers.  If you have C code, either an
application or a package, that makes calls into the Tcl or Tk
libraries, you may find that this code that compiled against
the public header files (''tcl.h'' and ''tk.h'') of releases
8.3.* of Tcl and Tk will no longer compile against the public
header files of releases 8.4*.  This page is meant to guide
you through making the required changes to your code to 
restore the ability to compile with the new headers.

There are two classes of people who will confront this
problem.  First are those who have written their own programs
or libraries that link the Tcl/Tk libraries.  Second are
those who have acquired such source code from somebody else,
and just need to get it to compile.  The latter group is not
likely interested in the finer points of programming, or
arguments for/against these source incompatibilties.  They
just want to get a working compile.  So I address that
community first:

-----
'''Step by step: getting your code to compile against Tcl/Tk 8.4'''
''...while being as lazy as possible...''

'''Step 1: Upgrade to Tcl/Tk 8.4b2.'''

The whole task is much easier with the very latest Tcl/Tk.

'''Step 2: Get updated code.'''

OK, so you have code that doesn't compile with 8.4 headers.
Check back where you got it and see if an updated release is
available that ''will'' compile.  Better to get the fixes
from the author/vendor than have to improvise some yourself.

'''Step 3: Define USE_NON_CONST'''

OK, so there are no updates available.  The incompatibilities
between 8.3 and 8.4 headers are completely removed if the
symbol '''USE_NON_CONST''' is defined when the header files are
included.  If you have code that compiled with 8.3 headers,
defining that symbol will make the same code compile with the
8.4 headers.

The ''simplest'' way to do this is to add '''-DUSE_NON_CONST'''
to the '''CFLAGS''' definition during the compile, but that
assumes a conventional Makefile.  The ''surest'' way to do
this is to find all the instances of

   #include <tcl.h>

in the source code and insert

   #define USE_NON_CONST

before them.

----
'''CONST migration for package authors'''

----
Most stuff can be fixed by putting CONST (or, if you're unlucky, CONST84) in your types.  Sometimes you might need to add a cast.  Anything that traditionally worked, will continue to work.

[[How does one decide when to use CONST and when to use CONST84?]]

----
See also Tcl Bug 580433 [http://sf.net/tracker/?func=detail&aid=580433&group_id=10894&atid=110894]
which requests a simpler migration tool for making this conversion.
----
See also [Changes in Tcl/Tk 8.4]
----
See also [http://sourceforge.net/mailarchive/message.php?msg_id=1235712]
and [http://sourceforge.net/mailarchive/message.php?msg_id=1236136]
(and subsequent messages in the thread)
for a fairly detailed report of the TIP 27 impact on two extensions.

Summary: In one case, adding CONST84 in a few places did 90% of the job, a few minor changes to the code fixed the rest.  In another case, -DUSE_NON_CONST was necessary, since the extension receives data from parts of the Core that were ''not'' CONSTified and passes it on to other parts that were.
----
[Category Porting]