Author: Rolf Ade <[email protected]>
State: Draft
Type: Project
Created: 25-04-2023
Tcl-Version: 9.0
Tcl-Branch: disabletcl8api
Abstract
The TIPs 481 and 616 introduced macro constructs which hide the C API changes from Tcl 8.6 to Tcl 9. This tip proposes to disabling these macros by default.
Rationale
All the functions named in the TIPs
481 and
616 changed
their prototype from Tcl 8.6 to Tcl 9. This includes often used
functions like Tcl_GetStringFromObj
. Typically a pointer changed
from int
to Tcl_Size
(which is a ptrdiff_t
).
Because of the Tcl 8 API compatibility macros on trunk, a lot of extension code will compile cleanly, leading the programmer to believe the extension is ready for 9.0.
However, that is not the case. With Tcl 9 it is possible to have
Tcl_Obj
s with a string representation greater 2 GByte and lists with
more than 2^31 elements. If an unchanged extension call one of these
functions with such a Tcl_Obj
, the application will abort. The price
for the current clean build is having run time errors in the field.
There is no other way than to adapt or migrate (most) Tcl extensions
to Tcl 9. This is what an API change means - code which uses this API
has to adapt. For the most part, this is a semi-mechanically change
from int
to Tcl_Size
parameters.
The goal should not be to build easily with minimal changes. The goal should be to execute correctly, and the macros get in the way of that. Having the compiler generate errors or warnings makes it much easier for extension writers to make the necessary fixes for correct operation.
The branch
disabletcl8api
disables these compatibility macros by default. They can be enabled
with the new configure switch --enable-tcl8api, which builds the core
with the macros in place. If that is done then any TEA based extension
will pick this up if build with that Tcl. Other build environments
will have to add -DTCL_8_API
to the compiler options.
Typically a Tcl extension must be at least shortly inspected for migration to Tcl 9. With the default proposed by this TIP the developer gets actively informed by the compiler about potential spots. The current default "actively" hides this spots.
Implementation
Implementation is in Tcl branch "disabletcl8api".
Further readings
The discussion about this topic prior to this TIP on tcl-core includes the reactions of some extension writes.
Caveat
With the macros disabled by default if a Tcl 8.6 extension builds with Tcl 9 and the compiler warnings are ignored by the developer the application may in the field not abort in case but return a wrong result.
Copyright
This document has been placed in the public domain.