Tcl_AppInit(3)

✨ Tcl_AppInit(3) — the Tcl Library Procedures glow-up ✨

okay so bestie, we're in the Tcl Library Procedures section of the manual, and today's main character is Tcl_AppInit 💅

---

🎀 NAME 🎀

Tcl_AppInit — do your app's own lil setup moment, fr fr

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_AppInit(interp)

---

🦋 ARGUMENTS 🦋

• Tcl_Interp *interp (in) — the interpreter for the application 🫶

---

💖 DESCRIPTION 💖

Tcl_AppInit is a "hook" procedure, bestie. Like, it's the little callback that the main programs for Tcl applications (think tclsh and wish, the icons 👑) invoke when they're getting everything going.

The whole point? It lets you build brand-new Tcl applications without touching the main programs that ship as part of Tcl and Tk. So to make your own app you just write a new version of Tcl_AppInit to replace the default one Tcl gives you, then link your new Tcl_AppInit with the Tcl library. that's it, that's the vibe ✨

Tcl_AppInit gets invoked by Tcl_Main and Tk_Main after they've done their own initialization, and before they head into the main loop to process commands. no cap.

Here's the kind of stuff Tcl_AppInit might get up to:

1. Call initialization procedures for the various packages your application uses. Each init procedure adds new commands to interp for its package and does other package-specific setup 🧚
2. Process command-line arguments — you can grab those from the Tcl variables argv and argv0 inside interp 🍓
3. Invoke a startup script to initialize the application.
4. Use the routines Tcl_SetStartupScript and Tcl_GetStartupScript to set or query the file and encoding that the active Tcl_Main or Tk_Main routine will use as a startup script 👀

Tcl_AppInit returns TCL_OK or TCL_ERROR. And listen — if it returns TCL_ERROR, it must leave an error message in the interpreter's result. Otherwise the result just gets ignored, no biggie.

⚠️ okay this part matters: TCL_ERROR with no error message left in the result is a whole mess. leave the message. periodt.

In addition to Tcl_AppInit, your application should also contain a procedure main that calls Tcl_Main, like this:

Tcl_Main(argc, argv, Tcl_AppInit);

That third argument to Tcl_Main is the address of the application-specific initialization procedure to invoke. Which means — plot twist — you don't actually have to name it Tcl_AppInit! But in practice it's nearly always named Tcl_AppInit (iykyk). In versions before Tcl 7.4 the name Tcl_AppInit was implicit, and there was literally no way to specify the procedure explicitly. wild 💀

The best way to get started is to make a copy of the file tclAppInit.c from the Tcl library or source directory. It already has a main procedure and a template for Tcl_AppInit that you can modify for your own application. copy-paste-and-thrive, that's the strategy 🌈

---

🔥 SEE ALSO 🔥

• Tcl_Main(3)

---

💜 KEYWORDS 💜

application, argument, command, initialization, interpreter

---

and that's the whole page, bestie 🎀 this was Tcl_AppInit(3) from the Tcl 7.0 era of the Tcl manual — written by the Tcl crew, living in the Tcl Library Procedures chapter, and honestly? iconic. go forth and write your own init procedure, you've got this 🫶✨