Building Tcl Extensions

Tycho optionally includes Tcl extensions that consist of C code that is compiled and loaded into a vanilla itkwish:
  1. Tycho's tytest package for testing other Tycho C packages
  2. Tycho's timer package
This page discusses the mechanism behind building and installing Tcl extensions.
  • Overall Tcl Extension Build Procedure
  • Autoconf
  • Tcl Extensions Overview
  • Files used to build Tcl extensions
  • Adding a Tcl extension

  • Overall Tcl Extension Build Procedure

    To build and install all the Tcl extensions, set the PTARCH environment variable. This variable is used to differentiate between different architectures. To set the PTARCH variable, under /bin/csh, do:

    setenv PTARCH `$TYCHO/bin/ptarch`
    
    To do the build:
    cd $TYCHO
    make tclexts
    

    Tycho uses GNU autoconf to configure the Tcl extensions. $TYCHO/makefile has a rule that calls configure and builds the proper directories.

    configure has a number of options, type $TYCHO/src/configure -help to see them. To pass options to configure, set the CONFIGURE_ARGS option.

    $TYCHO/makefile Tcl Extension Rules

    The tclexts makefile rule configures, builds and installs all the tcl extensions. Below we discuss each step in turn:

    config_tclexts
    This rule creates $TYCHO/obj.$PTARCH and then runs configure, which creates the makefiles below $TYCHO/obj.$PTARCH.
    all_tclexts
    The rule changes directories to $TYCHO/obj.$PTARCH and builds all the binaries.
    install_tclexts
    This rule changes directories to $TYCHO/obj.$PTARCH and installs the shared libraries into $TYCHO/lib.$PTARCH

    Running configure in $TYCHO/src

    $TYCHO/makefile is setup to support multiple architectures by creating separate lib.$PTARCH and obj.$PTARCH directories. It is possible to call configure directly and create binaries in $TYCHO/src, but there are the following problems:
    1. The $TYCHO/lib.$PTARCH directory is not built automatically, you would need to do something like:
      cd $TYCHO/src
      configure
      mkdir ../lib.$PTARCH
      make install
      
    2. $TYCHO/src/tcl.mk was configured for our local installation and are unlikely to work for you. To rebuild these files, run configure.
    3. Some parts of Tycho expect $TYCHO/obj.$PTARCH/tcl.mk to be present.

    Autoconf

    Autoconf is a package from the Free Software Foundation that is used to configure software. Although Autoconf has extensive documentation, the basic idea is that the software author writes a configure.in which autoconf converts to a configure script.

    The user runs configure which examines the operating systems for idiosyncrasies and then reads in the makefile.in template file and produces a makefile. The user can then run make and compile and install the package.

    The user need not have autoconf installed to run configure. The autoconf package need only be present if the user wishes to modify configure.in and produce a new configure file. If autoconf is not available, then it is possible to edit the configure file directly; it is merely a /bin/sh script.

    Tcl Extensions Overview

    (The information below is primarily useful for adding your own Tcl package).

    In Tcl7.5 and later it is fairly easy to load shared objects that add new Tcl commands. The Tcl load and package command man pages cover the details.

    The general overview is that C code is compiled with special flags to build a shared object. The special flags are compiler and architecture dependent, configure determines these flags by reading the tclConfig.sh file located in the architecture dependent Tcl library directory.

    The shared object has an architecture-dependent file extension, such as .so under Solaris 2, and .sl under HPUX. To see what the extension is on your system, start up tclsh or itkwish and run info sharedlibextension.

    When the file is loaded by Tcl, a C initialization procedure is called by Tcl. The name of the procedure depends on the name of the package or file that is being loaded, see the Tcl load command documentation. Usually, this procedure is used to create new Tcl commands that call user-supplied C procedures.

    If you use Tycho to open a file with the sharedlibextension then Tycho passes that file to the Tcl load command.

    Files used to build Tcl extensions

    Below we describe individual files that are used to create Tcl extensions.
    $TYCHO/makefile
    This file contains the tclexts rule which configures, builds and installs the extensions. This file is described above in more detail.
    $TYCHO/src
    This directory contains the Tcl extension sources. Note that this directory need not be present once the extensions have been built. Tcl extension authors should not rely on this directory being present at runtime.
    $TYCHO/obj.$PTARCH
    This directory contains the architecture dependent files created by configure, compiling and installing the extensions. This directory can be removed after installation.
    $TYCHO/lib.$PTARCH
    This directory contains the Tcl extension shared objects. Tcl loads packages from this directory.
    src/configure.in
    The autoconf template file that autoconf uses to create src/configure.
    src/configure
    Users execute this file to configure the makefiles
    src/makefile.in
    The makefile template file from which the makefile is generated.
    mk/tcl.mk.in
    Tcl template makefile used by configure to create obj.$PTARCH/tcl.mk.

    Adding a Tcl extension

    1. Create a directory in $TYCHO/src for your extension.
    2. Edit $TYCHO/src/configure.in and add the makefile to the AC_OUTPUT() macro.
      The $TYCHO/makefile rules should automatically run autoconf and update src/configure.
    3. Edit $TYCHO/src/makefile.in and add your extension directory to the DIRS macro.
    4. Copy a makefile.in from another directory, such as src/tytimer/makefile.in to the directory for your extension.
    5. Edit the makefile.in appropriately.
    6. Substitute with the name of your .c file.
    7. Modify the name of the library to be produced. It is best if the shared object that is produced starts with lib. The Tycho Loader searches for shared objects that begin with lib.
    8. Add the makefile.in of your extension to $TYCHO/makefile so that when others run make sources, your makefile will be retrieved from version control.
    9. Configure, build and install your extension with
      cd $TYCHO
      make tclexts
      

    Tycho Home Page


    Copyright © 1997-1998 The Regents of the University of California. All rights reserved.
    Last updated: 06/07/98 comments to: tycho@eecs.berkeley.edu