Tcl_StaticLibrary(3tcl)

💖 Tcl_StaticLibrary 💖

okay bestie, sit down, hydrate, because we're talking about the Tcl Library Procedures manual and specifically about Tcl_StaticLibrary and Tcl_StaticPackage — the two functions that make a statically linked library show up for the load command. yes, that's the whole vibe. let's go ✨

---

🌸 NAME 🌸

Tcl_StaticLibrary, Tcl_StaticPackage — 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 this is not NULL, it points to an interpreter that the library has already been incorporated into (meaning the caller already went ahead and invoked the right initialization procedure, no take-backs). If it's NULL, that means the library has not yet been incorporated into any interpreter. lowkey important distinction, don't sleep on it 🫶
• const char *prefix (in) — the prefix for the library initialization function. normally it's in titlecase (first letter uppercase, all the others lowercase), but bestie, that's no longer required. the rules relaxed, periodt 💅
• Tcl_LibraryInitProc *initProc (in) — the procedure you invoke to incorporate this library into a trusted interpreter. good vibes only 🔥
• Tcl_LibraryInitProc *safeInitProc (in) — the procedure to call to incorporate this library into a safe interpreter (aka one that's gonna execute untrusted scripts, eek). NULL here means the library cannot be used in safe interpreters. not negotiable, she said no 🙈

---

🌈 DESCRIPTION 🌈

so this procedure gets invoked 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. iconic behavior honestly.

ngl, 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 the code inside the library itself shouldn't even need to know whether it's dynamically loaded or statically linked. minding her own business, as she should 💅

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 both initProc and safeInitProc must match the following prototype, no exceptions bestie:

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 — and 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. so like, cause and effect, she's connected like that ✨

🚨 lore drop: Tcl_StaticLibrary was named Tcl_StaticPackage in Tcl 8.6 and earlier, but the old name is deprecated now. she goes by her new name, respect it 👑

💀 real talk: Tcl_StaticLibrary can not be used in stub-enabled extensions. that's just the rules, no cap.

---

🔑 KEYWORDS 🔑

initialization procedure, package, static linking

---

👀 SEE ALSO 👀

load(3tcl), package(3tcl), Tcl_PkgRequire(3tcl)

---

okay that's the whole page, you ate that 🍓 this was the Tcl_StaticLibrary(3tcl) page, version 7.5, from the Tcl Library Procedures manual — mwah, love u, go write some statically linked libraries 💖✨🎀🦋