TIP #414 Version 1.14: 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 there is no way to control exactly what is initialized: What will be the system encoding, what will be the registered name of the executable. Therefore, the function will get a flags parameter which controls in finer detail how the initialization is done. The default, 0, means that the initialization is done exactly the same as Tcl_FindExecutable(NULL). But other flags can be set to modify the initialization, and more flag values can be defined in the future. This TIP proposes 4 values for the flags value.

The need for the TCL_INIT_CREATE_??? flags is inspired by the current complication of the Tk_Main and Tcl_Main macros, and the internal functions Tcl_MainEx, Tcl_MainExW, Tk_MainEx and Tk_MainExW which have a lot of code in common. With help of the Tcl_InitSubsystems, those macros could be simplified, or replaced with a totally different approach in Tcl 9. How that is done, is out of scope for this TIP.

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 variable number of arguments, the first of which is flags which controls the interpretation of the additional arguments. If flags is 0, then this function does exactly the same as Tcl_FindExecutable(NULL). The full signature is:

EXTERN Tcl_Interp * Tcl_InitSubsystems( int flags, ...);

If you supply one of the flags TCL_INIT_CREATE, TCL_INIT_CREATE_UTF8 or TCL_INIT_CREATE_UNICODE to Tcl_InitSubsystems, the function gets two additional parameters, argc and argv. Then a new Tcl interpreter will be created. If argc > 0 then the variables argc and argv will be set in this interpreter. If argv is specified, irrespective of the value of argc, the variable argv0 will be set in the interpreter, and this value will be used to determine the value returned by info executable. The 3 flag variants assume a different encoding for the arguments, except for argv0 which is always assumed to be in the system encoding.

If you supply the flag TCL_INIT_CUSTOM to Tcl_InitSubsystems, the function expects two additional arguments following the previously mentioned ones: ClientData and a custom proc. The proc will be executed just before the encodings are initialized, and it will be given two arguments: the Tcl interpreter and ClientData. Remember that encodings other than UTF-8, unicode and iso8859-1 are not yet available when the customProc is run, the system encoding is not determined, and no variables are set in the interpreter yet. This means that no libaries/packages can be found yet, it is typically only used for calling functions like Tcl_SetEncodingSearchPath and Tcl_FSRegister.

The return value of Tcl_InitSubsystems is, if one of the TCL_INIT_CREATE_?? flag values is used, the newly created interpreter, NULL otherwise.

Reference Implementation

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

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.