Tcl Extension Architecture (TEA) Sample Extension

autom4te.cache
Makefile
pkgIndex.tcl
*.dll
*.so
config.status

2010-04-23  Jan Nijtmans <[email protected]>

	* configure: Regenerated to use latest TEA tcl.m4.
	* [Bug 2782806] sample package's test cases fail

2010-02-19  Stuart Cassoff  <[email protected]>

	* tcl.m4: Correct compiler/linker flags
	for threaded builds on OpenBSD.
	* configure: Regenerated to use latest TEA tcl.m4.

 *	function name must match the PACKAGE declaration at the top of
 *	configure.in.
 *
 * Results:
 *	A standard Tcl result
 *
 * Side effects:
 *	The Sample package is created.
 *	One new command "sha1" is added to the Tcl interpreter.
 *
 *----------------------------------------------------------------------
 */

int
Sample_Init(Tcl_Interp *interp)
{
    /*
     * This may work with 8.0, but we are using strictly stubs here,
     * which requires 8.1.
     */
    if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
	return TCL_ERROR;
    }
    if (Tcl_PkgRequire(interp, "Tcl", "8.1", 0) == NULL) {
	return TCL_ERROR;
    }
    if (Tcl_PkgProvide(interp, PACKAGE_NAME, PACKAGE_VERSION) != TCL_OK) {
	return TCL_ERROR;
    }
    Tcl_CreateObjCommand(interp, "sha1", (Tcl_ObjCmdProc *) Sha1_Cmd,
	    (ClientData)NULL, (Tcl_CmdDeleteProc *)NULL);

    numcontexts = 1;
    sha1Contexts = (SHA1_CTX *) malloc(sizeof(SHA1_CTX));
    ctxtotalRead = (int *) malloc(sizeof(int));
    ctxtotalRead[0] = 0;

    return TCL_OK;
}

   #
   # Copyright (c) 1998-2000 by Ajuba Solutions.
   # Copyright (c) 1998 by Mark Harrison.
   #
   # See the file "license.terms" for information on usage and redistribution
   # of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   #
   # RCS: @(#) $Id: packages.txt,v 1.2 2010/04/23 11:51:53 nijtmans Exp $

   package require Tcl 8.2
   # When the version number changes, be sure to update the pkgIndex.tcl file,
   # and the installation directory in the Makefiles.
   package provide msgcat 1.3

   namespace eval msgcat {

   package ifneeded msgcat 1.3 [list source [file join $dir msgcat.tcl]]
}]

Note the variable "$dir" in the second statement: this variable is set
by the package mechanism when it is looking for the required package.

[para]
From the example extension (Sample):
[example {
/*
 *----------------------------------------------------------------------
 *
 * Sample_Init --
 *
 *      Initialize the new package.  The string "Sample" in the
 *      function name must match the PACKAGE declaration at the top of
 *      configure.in.
 *
 * Results:
 *      A standard Tcl result
 *
 * Side effects:
 *      The Sample package is created.
 *      One new command "sha1" is added to the Tcl interpreter.
 *
 *----------------------------------------------------------------------
 */

int
Sample_Init(Tcl_Interp *interp)
{
    if (Tcl_InitStubs(interp, "8.0", 0) == NULL) {
        return TCL_ERROR;
    }
    if (Tcl_PkgRequire(interp, "Tcl", TCL_VERSION, 0) == NULL) {
        if (TCL_VERSION[0] == '7') {
            if (Tcl_PkgRequire(interp, "Tcl", "8.0", 0) == NULL) {
                return TCL_ERROR;
            }
        }
    }
    if (Tcl_PkgProvide(interp, "sample", VERSION) != TCL_OK) {
        return TCL_ERROR;
    }
    Tcl_CreateCommand(interp, "sha1", Sha1,
            (ClientData)NULL, (Tcl_CmdDeleteProc *)NULL);

    ...
}
}]
As this extension is built via the TEA facilities, a pkgIndex.tcl
file is provided for automatically. Instead of simply sourcing a
Tcl script, it will load the shared object or DLL that was built from
the C sources, roughly like:
[example {
   package ifneeded sample 1.0 [list load [file join $dir libsample.so]]
}]
or:
[example {
   package ifneeded sample 1.0 [list load [file join $dir sample.dll]]
}]
The TEA will create the pkgIndex.tcl file automatically via the
pkg_mkIndex command.


[section {Details on version numbers}]

   # __CHANGE__
   # Set your package name and version numbers here.  The NODOT_VERSION is
   # required for constructing the library name on systems that don't like
   # dots in library names (Windows).  The VERSION variable is used on the
   # other systems.
   #--------------------------------------------------------------------

   PACKAGE=sample

   MAJOR_VERSION=0
   MINOR_VERSION=5
   PATCHLEVEL=

   VERSION=${MAJOR_VERSION}.${MINOR_VERSION}${PATCHLEVEL}
   NODOT_VERSION=${MAJOR_VERSION}${MINOR_VERSION}
}]

So, the above would result in a macro VERSION with the value 0.5
[para]
The version number is also used to construct a distinguishing name for
the library, like: libsample0.5.so or sample05.dll.
This way there is much less chance of a conflict between versions.


[section {Subtleties with package names}]

There are a few things you must be aware of when choosing a name for
the extension:

initialisation routine. The precise rules are explained in the manual
page for the load command, but here are a few examples:
[example {
   Filename        Package name    Initial procedure
   foo.dll         foo             Foo_Init
   FOO.DLL         fOO             Foo_Init
   libFOO.so       fOO             Foo_Init
   libfoo1.2.so    fOo             Foo_Init
}]
So, in the index file you might see:
[example {
   package ifneeded fOo 1.2 [list load [file join $dir libfoo1.2.so]]
}]
A second issue is that for the extension to useful in a [emph safe]
interpreter, you need to define an initialisation routine with a name
like "Foo_SafeInit" (and possibly define the commands in another, safer,
way).

[para]
The third issue that we would like to bring under your attention is the
fact that under Windows you must explicitly indicate that a function in
a DLL is to made visible (exported) to the outside world. Without this
instruction the initialisation routine can not be loaded and therefore
loading the extension fails.

[para]
The sample extension contains this fragment of code (sample.h) to take
care of this (in general, the initialisation routine is the only one
that needs to be exported - all others should be defined as [emph static] to
reduce the chance of naming conflicts):
[example {
   /*
    * Windows needs to know which symbols to export.  Unix does not.
    * BUILD_exampleA should be undefined for Unix.
    */

   #ifdef BUILD_sample
   #undef TCL_STORAGE_CLASS
   #define TCL_STORAGE_CLASS DLLEXPORT
   #endif /* BUILD_sample */

   ...

   /*
    * Only the _Init function is exported.
    */

   EXTERN int      Sample_Init _ANSI_ARGS_((Tcl_Interp * interp));
}]

# Commands covered:  sha1
#
# This file contains a collection of tests for one or more of the Tcl
# built-in commands.  Sourcing this file into Tcl runs the tests and
# generates output for errors.  No output means no errors were found.
#
# Copyright (c) 2000 by Scriptics Corporation.
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
# RCS: @(#) $Id: sample.test,v 1.2 2010/04/23 11:51:53 nijtmans Exp $

if {[lsearch [namespace children] ::tcltest] == -1} {
    package require tcltest
    namespace import ::tcltest::*
}

package require sample

test sha-1.1 {Use of -string operand} {
    set result [sha1 -string foo]
} {0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33}

test sha-1.2 {Use of -init operand} {
    set result [catch {sha1 -init}]

# Commands covered:  sha1
#
# This file contains a collection of tests for one or more of the Tcl
# built-in commands.  Sourcing this file into Tcl runs the tests and
# generates output for errors.  No output means no errors were found.
#
# Copyright (c) 2000 by Scriptics Corporation.
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
# RCS: @(#) $Id: tclsample.test,v 1.3 2010/04/23 11:51:53 nijtmans Exp $

if {[lsearch [namespace children] ::tcltest] == -1} {
    package require tcltest
    namespace import ::tcltest::*
}

package require sample

test sha-1.1 {incorrect command usage} {
    list [catch {sha1} errMsg] $errMsg
} {1 {wrong # args: should be either:
  sha1 ?-log2base log2base? -string string
 or
  sha1 ?-log2base log2base? ?-copychan chanID? -chan chanID

# Copyright (c) 1995-1996 Sun Microsystems, Inc.
# Copyright (c) 1998-2000 Ajuba Solutions.
# Copyright (c) 2001 ActiveState Corporation.
# Copyright (c) 2001-2002 David Gravereaux.
# Copyright (c) 2003-2006 Pat Thoyts
#
#-------------------------------------------------------------------------
# RCS: @(#)$Id: makefile.vc,v 1.12 2010/04/23 11:51:53 nijtmans Exp $
#-------------------------------------------------------------------------

# Check to see we are configured to build with MSVC (MSDEVDIR or MSVCDIR)
# or with the MS Platform SDK (MSSDK). Visual Studio .NET 2003 and 2005 define
# VCINSTALLDIR instead. The MSVC Toolkit release defines yet another.
!if !defined(MSDEVDIR) && !defined(MSVCDIR) && !defined(MSSDK) && !defined(VCINSTALLDIR) && !defined(VCToolkitInstallDir)
MSG = ^

#-------------------------------------------------------------------------
# Project specific information (EDIT)
#
# You should edit this with the name and version of your project. This
# information is used to generate the name of the package library and
# it's install location.
#
# For example, the sample extension is  going to build sample05.dll and
# would install it into $(INSTALLDIR)\lib\sample05
#
# You need to specify the object files that need to be linked into your
# binary here.
#
#-------------------------------------------------------------------------

PROJECT = sample

$(OUT_DIR)\pkgIndex.tcl: $(ROOT)\pkgIndex.tcl.in
	@nmakehlp -s << $** > $@
@PACKAGE_VERSION@    $(DOTVERSION)
@PACKAGE_NAME@       $(PROJECT)
@PKG_LIB_FILE@       $(PRJLIBNAME)
<<
	@echo package ifneeded sample $(DOTVERSION) \
	    [list load [file join $$dir $(PRJLIBNAME)] Sample] >> $@

#---------------------------------------------------------------------
# Installation. (EDIT)
#
# You may need to modify this section to reflect the final distribution
# of your files and possibly to generate documentation.