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: Just try it.'''

Some programs may compile fine with 8.4 headers, so try it
first and make sure there's a problem.

'''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 reduced if the symbol
'''USE_NON_CONST''' is defined when the header files are
included.  That may be enough to restore compilability.

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.

'''Step 4: Confirm CONST-ification is the problem'''

OK, so '''USE_NON_CONST''' didn't completely solve the problem.
It probably helped, though, so the remaining steps are in addition
to '''USE_NON_CONST'''.

At this point, the laziness factor will drop significantly, so
it's worth verifying the CONST issues are really your problem.
Confirm that your code does compile with 8.3 headers.  If not,
then you have other problems.  Also, check that the compiler
error messages indicate const problems.  If not, turn back
to the author/vendor to get the other problems resolved.

'''Step 5:'''
----
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 [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.
----