TIP #414 Version 1.17: Add (back) Tcl_InitSubsystems as Public API

This is not necessarily the current version of this TIP.

Abstract

The ability to initialize just the lower level Tcl subsystems used to be part of the public API, now it is no longer exposed. This TIP proposes that it be re-exposed.

Rationale

Some parts of Tcl's API are useful in portable applications even without creating a Tcl interpreter; examples of this include Tcl_Alloc and (most of) the Tcl_DString-related functions. In order to use these functions correctly, the Tcl library must be initialized, yet the function for doing so - Tcl_InitSubsystems (currently TclInitSubsystems) - was removed from Tcl's API; using Tcl_FindExecutable instead feels incorrect as we're not seeking to make the name of the executable available to Tcl scripts.

However, exposing the current TclInitSubsystems has the limitation that this function cannot be used in a stubbed environment without createing an interpreter, and there is no way to define a panic proc in a stubbed environment before calling Tcl_InitSubsystems, as Tcl_InitSubsystems must be the first function called. Therefore, the function will get a panicProc parameter, and it will be turned into a macro - which does stubs initialization as well - when USE_TCL_STUBS is set.

Proposed Change

A new function Tcl_InitSubsystems, similar to the internal TclInitSubsystems, should be exposed as alternative to Tcl_FindExecutable in Tcl's C API. This will not be a part of the Stub API; it is not intended to ever be used from an initialized stubbed environment, as it is meant to be used prior to the stub table being available. It has a single argument, panicProc. When NULL, the default panic function is used. The full signature is:

EXTERN const char * Tcl_InitSubsystems( Tcl_PanicProc *panicProc);

The return value of Tcl_InitSubsystems is the Tcl version.

Further on, the Tcl_MainEx* functions will be added an initial TclpSetInitialEncodings() and TclpFindExecutable(argvTIP #0) call, while in the Tcl_Main() macro, the Tcl_FindExecutable(argvTIP #0) call will be replaced by a call to the new function. This is fully upwards compatible: in any application compiled against Tcl 8.6.0 headers but later upgraded to Tcl 8.6.1 or later, those two calls will be done twice, but this turns the second call in nothing more than a nop.

Using Tcl_InitSubsystems, it now becomes possible to install a VFS or modify the encoding path between the TclInitSubsystems and the TclpSetInitialEncodings() call. This was not possible without creating an interpreter first, because those calls were united in a single function Tcl_FindExecutable(): |const char *version = Tcl_InitSubSystems(NULL); |Tcl_Interp *interp = Tcl_CreateInterp(); |/* Optional: Set VFS or additional encoding paths here. */ |Tcl_MainEx(argc, argv, appInitProc, interp);

Reference Implementation

A reference implementation is available in the initsubsystems branch. [1]

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.