First understand the difference between
[embedding vs. extending].  If you decide
that embedding is the approach you want,
this page is meant to record advice about
best practices.

In this example we will create a
shell program that embeds Tcl and
an extension by the name ''foo''.
This type of program is sometimes
known as a [big wish].

A Tcl interpreter (literally, a ''Tcl_Interp*'')
gets extended by a Tcl extension by being
passed to one of two initialization routines provided
by the extension library.  For the ''foo'' extension,
the names of these initialization routines are
''Foo_Init'' and ''Foo_SafeInit''.  Normal, or ''trusted''
interpreters are passed to the ''Foo_Init'' routine,
while safe interpreters are passed to the ''Foo_SafeInit''
routine.

Since we have chosen embedding in this example, we
will directly call the ''Foo_Init'' routine on the
master interpreter of our [big wish] (foosh?) that
contains foo.

Here is a sketch of what the C code for
our [big wish] program should look like:

  #include <tcl.h>
  #include "foo.h"

  static int
  Foosh_AppInit(Tcl_Interp *interp) {
      if (Tcl_Init(interp) == TCL_ERROR) {
          return TCL_ERROR;
      }
      if (Foo_Init(interp) == TCL_ERROR) {
          return TCL_ERROR;
      }
      Tcl_StaticPackage(interp, "Foo", Foo_Init, Foo_SafeInit);
      Tcl_SetVar(interp, "tcl_rcFileName", "~/.fooshrc", TCL_GLOBAL_ONLY);
      return TCL_OK;
  }

  int
  main(int argc, char **argv) {
      Tcl_Main(argc, argv, Foosh_AppInit);
  }

''more to come...''

''17 days later, more hasn't come yet'' :-(

''See also [9836]''  :-(