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_Objs 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.