Tcl_StaticLibrary(3)

💖 Tcl_StaticLibrary — bestie edition 💖

okay so this is a page from the Tcl Library Procedures manual (that's the manual name, mwah, love that for us) and it's all about Tcl_StaticLibrary and Tcl_StaticPackage 💅

✨ NAME ✨

Tcl_StaticLibrary, Tcl_StaticPackage — the way these two make a statically linked library available via the load command 🎀

🌸 SYNOPSIS 🌸

#include <tcl.h>

Tcl_StaticLibrary(interp, prefix, initProc, safeInitProc)

Tcl_StaticPackage(interp, prefix, initProc, safeInitProc)

🦋 ARGUMENTS 🦋

• Tcl_Interp *interp (in) — if it's not NULL, it points at an interpreter that the library has already been incorporated into (like, the caller already ran the right initialization procedure, no notes 💅). NULL means the library hasn't been incorporated into any interpreter yet.
• const char *prefix (in) — the prefix for the library's initialization function. Normally it's in titlecase (first letter uppercase, all the others lowercase), but bestie, that's no longer required ✨
• Tcl_LibraryInitProc *initProc (in) — the procedure you invoke to incorporate this library into a trusted interpreter 🫶
• Tcl_LibraryInitProc *safeInitProc (in) — the procedure you call to incorporate this library into a safe interpreter (aka one that's gonna execute untrusted scripts 😭). NULL means the library cannot be used in safe interpreters. periodt.

👑 DESCRIPTION 👑

So you invoke this procedure to announce that a library has been linked statically with a Tcl application, and optionally that it's already been incorporated into an interpreter. Once Tcl_StaticLibrary has been invoked for a library, that library can then be incorporated into interpreters using the load command. 🎀

Tcl_StaticLibrary is normally invoked only by the Tcl_AppInit procedure for the application — not by libraries for themselves. Like, Tcl_StaticLibrary should only be invoked for statically linked libraries, and code in the library itself should not need to know whether the library is dynamically loaded or statically linked. iykyk 💅

When the load command is used later to incorporate the library into an interpreter, one of initProc and safeInitProc will be invoked, depending on whether the target interpreter is safe or not. And initProc and safeInitProc must both match this prototype, no exceptions:

typedef int Tcl_LibraryInitProc(
        Tcl_Interp *interp);

The interp argument identifies the interpreter in which the library is to be incorporated. The initialization procedure must return TCL_OK or TCL_ERROR to indicate whether or not it completed successfully; if there's an error it should set the interpreter's result to point to an error message. The result or error from the initialization procedure will be returned as the result of the load command that caused the initialization procedure to be invoked. slay ✨

ngl, Tcl_StaticLibrary was named Tcl_StaticPackage back in Tcl 8.6 and earlier — but the old name is deprecated now, so don't come for me, use the new one 🙈

🚨 ALSO IMPORTANT: Tcl_StaticLibrary can not be used in stub-enabled extensions. fr fr, not a vibe.

🔥 KEYWORDS 🔥

initialization procedure, package, static linking

💜 SEE ALSO 💜

• load(n)
• package(n)
• Tcl_PkgRequire(3)

and that's the whole page bestie 🫶 this one came from Tcl version 7.5 (yes the footer said Tcl 7.5 Tcl_StaticLibrary(3)) — go forth and statically link responsibly 💖✨🎀🦋🌸💅