Tcl Extension Architecture (TEA) Sample Extension

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>sampleextension</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
	</buildSpec>
	<natures>
	</natures>
</projectDescription>

INCLUDES	= @[email protected] @[email protected]
#INCLUDES	= @[email protected] @[email protected] @[email protected] @[email protected]

PKG_CFLAGS	= @[email protected]

# TCL_DEFS is not strictly need here, but if you remove it, then you
# must make sure that configure.in checks for the necessary components
# that your library may use.  TCL_DEFS can actually be a problem if
# you do not compile with a similar machine setup as the Tcl core was
# compiled with.
#DEFS		= $(TCL_DEFS) @[email protected] $(PKG_CFLAGS)
DEFS		= @[email protected] $(PKG_CFLAGS)

# Move pkgIndex.tcl to 'BINARIES' var if it is generated in the Makefile
................................................................................

dist: dist-clean
	$(INSTALL_DATA_DIR) $(DIST_DIR)
	cp -p $(srcdir)/ChangeLog $(srcdir)/README* $(srcdir)/license* \
		$(srcdir)/aclocal.m4 $(srcdir)/configure $(srcdir)/*.in \
		$(DIST_DIR)/
	chmod 664 $(DIST_DIR)/Makefile.in $(DIST_DIR)/aclocal.m4
	chmod 775 $(DIST_DIR)/configure $(DIST_DIR)/configure.in

	for i in $(srcdir)/*.[ch]; do \
	    if [ -f $$i ]; then \
		cp -p $$i $(DIST_DIR)/ ; \
	    fi; \
	done;

................................................................................

#========================================================================
# End of user-definable section
#========================================================================

#========================================================================
# Don't modify the file to clean here.  Instead, set the "CLEANFILES"
# variable in configure.in
#========================================================================

clean:
	-test -z "$(BINARIES)" || rm -f $(BINARIES)
	-rm -f *.$(OBJEXT) core *.core
	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)

INCLUDES	= @[email protected] @[email protected]
#INCLUDES	= @P[email protected] @[email protected] @[email protected] @[email protected]

PKG_CFLAGS	= @[email protected]

# TCL_DEFS is not strictly need here, but if you remove it, then you
# must make sure that configure.ac checks for the necessary components
# that your library may use.  TCL_DEFS can actually be a problem if
# you do not compile with a similar machine setup as the Tcl core was
# compiled with.
#DEFS		= $(TCL_DEFS) @[email protected] $(PKG_CFLAGS)
DEFS		= @[email protected] $(PKG_CFLAGS)

# Move pkgIndex.tcl to 'BINARIES' var if it is generated in the Makefile
................................................................................

dist: dist-clean
	$(INSTALL_DATA_DIR) $(DIST_DIR)
	cp -p $(srcdir)/ChangeLog $(srcdir)/README* $(srcdir)/license* \
		$(srcdir)/aclocal.m4 $(srcdir)/configure $(srcdir)/*.in \
		$(DIST_DIR)/
	chmod 664 $(DIST_DIR)/Makefile.in $(DIST_DIR)/aclocal.m4
	chmod 775 $(DIST_DIR)/configure $(DIST_DIR)/configure.ac

	for i in $(srcdir)/*.[ch]; do \
	    if [ -f $$i ]; then \
		cp -p $$i $(DIST_DIR)/ ; \
	    fi; \
	done;

................................................................................

#========================================================================
# End of user-definable section
#========================================================================

#========================================================================
# Don't modify the file to clean here.  Instead, set the "CLEANFILES"
# variable in configure.ac
#========================================================================

clean:
	-test -z "$(BINARIES)" || rm -f $(BINARIES)
	-rm -f *.$(OBJEXT) core *.core
	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)

README.sha	A description of the extension itself.

aclocal.m4	Generated file.  Do not edit.  Autoconf uses this as input
		when generating the final configure script.  See "tcl.m4"
		below.

configure	Generated file.  Do not edit.  This must be regenerated
		anytime configure.in or tclconfig/tcl.m4 changes.

configure.in	Configure script template.  Autoconf uses this file as input
		to produce the final configure script.

pkgIndex.tcl.in Package index template.  The configure script will use
		this file as input to create pkgIndex.tcl.

sample.c	Core Secure Hash Algorithm code.

................................................................................
to create a Makefile. See the tcl/win/README file for the URL of
the Msys + Mingw download.

If you have VC++ then you may wish to use the files in the win
subdirectory and build the extension using just VC++. These files have
been designed to be as generic as possible but will require some
additional maintenance by the project developer to synchronise with
the TEA configure.in and Makefile.in files. Instructions for using the
VC++ makefile are written in the first part of the Makefile.vc
file.

INSTALLATION
============

The installation of a TEA package is structure like so:

README.sha	A description of the extension itself.

aclocal.m4	Generated file.  Do not edit.  Autoconf uses this as input
		when generating the final configure script.  See "tcl.m4"
		below.

configure	Generated file.  Do not edit.  This must be regenerated
		anytime configure.ac or tclconfig/tcl.m4 changes.

configure.ac	Configure script template.  Autoconf uses this file as input
		to produce the final configure script.

pkgIndex.tcl.in Package index template.  The configure script will use
		this file as input to create pkgIndex.tcl.

sample.c	Core Secure Hash Algorithm code.

................................................................................
to create a Makefile. See the tcl/win/README file for the URL of
the Msys + Mingw download.

If you have VC++ then you may wish to use the files in the win
subdirectory and build the extension using just VC++. These files have
been designed to be as generic as possible but will require some
additional maintenance by the project developer to synchronise with
the TEA configure.ac and Makefile.in files. Instructions for using the
VC++ makefile are written in the first part of the Makefile.vc
file.

INSTALLATION
============

The installation of a TEA package is structure like so:

#!/bin/bash -norc
dnl	This file is an input file used by the GNU "autoconf" program to
dnl	generate the file "configure", which is run during Tcl installation
dnl	to configure the system for the local environment.

#-----------------------------------------------------------------------
# Sample configure.in for Tcl Extensions.  The only places you should
# need to modify this file are marked by the string __CHANGE__
#-----------------------------------------------------------------------

#-----------------------------------------------------------------------
# __CHANGE__
# Set your package name and version numbers here.
#

#!/bin/bash -norc
dnl	This file is an input file used by the GNU "autoconf" program to
dnl	generate the file "configure", which is run during Tcl installation
dnl	to configure the system for the local environment.

#-----------------------------------------------------------------------
# Sample configure.ac for Tcl Extensions.  The only places you should
# need to modify this file are marked by the string __CHANGE__
#-----------------------------------------------------------------------

#-----------------------------------------------------------------------
# __CHANGE__
# Set your package name and version numbers here.
#

/*
 *----------------------------------------------------------------------
 *
 * 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.

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

      unix/                  unix-specific sources (here: nothing???)
      win/                   Windows-specific sources (here: the
                             project-file for building on Windows)
      ChangeLog              description of changes
      Makefile.in            TEA-template for the makefile
      aclocal.m4             "include" file required by Autoconf
      configure              configure script generated by Autoconf
      configure.in           TEA-template for the configure script
      ...                    (others files, not related to the building
                             process itself)
}]

In this overview you will see some files related to the TEA, most
notably, [emph Makefile.in] and [emph configure.in]. These will be described in
great detail in Chapter 7 (fortunately the details have become less and
less painful with the further development of TEA).

[para]
The most important thing is that this extension uses the [emph same]
directory structure as Tcl/Tk itself. This may not always seem necessary
(for instance, a Windows-specific extension might do without the unix
................................................................................
like strtod() are notorious in this respect)

[list_end]

The directory structure described in the previous section is
quite useable in this case too. The platform-dependencies are expressed
in the mac, unix and win directories containing one or more source files
(not just project or make files), but also in the configure.in and
Makefile.in files containing extra code to find the relevant
OS libraries or checks for deficiencies.

[section {Extensions exporting their own functions}]

Complications arise when extensions need to export their own
(compiled) functions, to provide their functionality. Again, this is not

      unix/                  unix-specific sources (here: nothing???)
      win/                   Windows-specific sources (here: the
                             project-file for building on Windows)
      ChangeLog              description of changes
      Makefile.in            TEA-template for the makefile
      aclocal.m4             "include" file required by Autoconf
      configure              configure script generated by Autoconf
      configure.ac           TEA-template for the configure script
      ...                    (others files, not related to the building
                             process itself)
}]

In this overview you will see some files related to the TEA, most
notably, [emph Makefile.in] and [emph configure.ac]. These will be described in
great detail in Chapter 7 (fortunately the details have become less and
less painful with the further development of TEA).

[para]
The most important thing is that this extension uses the [emph same]
directory structure as Tcl/Tk itself. This may not always seem necessary
(for instance, a Windows-specific extension might do without the unix
................................................................................
like strtod() are notorious in this respect)

[list_end]

The directory structure described in the previous section is
quite useable in this case too. The platform-dependencies are expressed
in the mac, unix and win directories containing one or more source files
(not just project or make files), but also in the configure.ac and
Makefile.in files containing extra code to find the relevant
OS libraries or checks for deficiencies.

[section {Extensions exporting their own functions}]

Complications arise when extensions need to export their own
(compiled) functions, to provide their functionality. Again, this is not

again TEA has the task to make the preparation of the build process for
your specific extension as smooth and painless as possible.
Nevertheless, you will have to do something:

[list_begin bullet]

[bullet]
Prepare at least two template files, configure.in and Makefile.in,
that contain information about what sources your extension is made of,
under what name your extension will be known and so on.

[bullet]
Create a [emph {shell script}] (*), called [emph configure], via the Autoconf
program.

................................................................................
older versions) and processes the macros it finds in there. These
macros have been developed to take care of all the nasty little details
that can bother a programmer. (If you familiarise yourself with the
Autoconf tool, you will be able to create new macros. This is actually
one of the great advantages of Autoconf.)

[para]
While Autoconf takes a template file "configure.ac" or "configure.in",
TEA provides you with a template for this template. All you need to do is:

[list_begin bullet]

[bullet]
replace the name of the sample extension (exampleA) by the name
of your extension

................................................................................
[example {
  CFLAGS_DEBUG = @[email protected]
}]
The first is a variable in the make file that is used to set the flags
for a debug version of your extension. The configure script
replaces the string "@[email protected]" by whatever is appropriate for that
platform, often "-g -c". This is accomplished by a command
AC_SUBST([lb]CFLAGS_DEBUG[rb]) somewhere in the configure.in file (or
the macros it uses).


[section {The macros used by TEA}]

The template files that come with TEA are very well documented,
but still some explanation is required, if you are not familiar with
................................................................................

[bullet]
The last line, AC_OUTPUT(), lists all the files that need to be
created by the configure script.

[list_end]

You can use a number of other macros in your configure.in file:

[list_begin bullet]

[bullet]
AC_DEFINE(variable,value,?description?):
[nl]
Add a C compiler macro "variable" with the given value to the list of
................................................................................
[list_begin bullet]

[bullet]
Define a file INSTALL.in which has a line "@[email protected]"
in it.

[bullet]
Define a variable MY_EXTENSION_TEXT in the configure.in file:
[example {
     AC_DEFINE([MY_EXTENSION_TEXT])
     MY_EXTENSION_TEXT="Whatever text you want inserted"
     AC_SUBST([MY_EXTENSION_TEXT])
}]

[bullet]

again TEA has the task to make the preparation of the build process for
your specific extension as smooth and painless as possible.
Nevertheless, you will have to do something:

[list_begin bullet]

[bullet]
Prepare at least two template files, configure.ac and Makefile.in,
that contain information about what sources your extension is made of,
under what name your extension will be known and so on.

[bullet]
Create a [emph {shell script}] (*), called [emph configure], via the Autoconf
program.

................................................................................
older versions) and processes the macros it finds in there. These
macros have been developed to take care of all the nasty little details
that can bother a programmer. (If you familiarise yourself with the
Autoconf tool, you will be able to create new macros. This is actually
one of the great advantages of Autoconf.)

[para]
While Autoconf takes a template file "configure.ac", TEA provides you
with a template for this template. All you need to do is:

[list_begin bullet]

[bullet]
replace the name of the sample extension (exampleA) by the name
of your extension

................................................................................
[example {
  CFLAGS_DEBUG = @[email protected]
}]
The first is a variable in the make file that is used to set the flags
for a debug version of your extension. The configure script
replaces the string "@[email protected]" by whatever is appropriate for that
platform, often "-g -c". This is accomplished by a command
AC_SUBST([lb]CFLAGS_DEBUG[rb]) somewhere in the configure.ac file (or
the macros it uses).


[section {The macros used by TEA}]

The template files that come with TEA are very well documented,
but still some explanation is required, if you are not familiar with
................................................................................

[bullet]
The last line, AC_OUTPUT(), lists all the files that need to be
created by the configure script.

[list_end]

You can use a number of other macros in your configure.ac file:

[list_begin bullet]

[bullet]
AC_DEFINE(variable,value,?description?):
[nl]
Add a C compiler macro "variable" with the given value to the list of
................................................................................
[list_begin bullet]

[bullet]
Define a file INSTALL.in which has a line "@[email protected]"
in it.

[bullet]
Define a variable MY_EXTENSION_TEXT in the configure.ac file:
[example {
     AC_DEFINE([MY_EXTENSION_TEXT])
     MY_EXTENSION_TEXT="Whatever text you want inserted"
     AC_SUBST([MY_EXTENSION_TEXT])
}]

[bullet]

/*
 *----------------------------------------------------------------------
 *
 * 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.
................................................................................

[list_end]

For this reason, the TEA defines a C macro, VERSION, that holds the
version string (you can see how it is used in the code for the sample
extension). This string is built up of the major version and a
combination of the minor version and the patchlevel. From the file
"configure.in" (see Chapter 6) we have:
[example {
   #--------------------------------------------------------------------
   # __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.

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

[list_end]

For this reason, the TEA defines a C macro, VERSION, that holds the
version string (you can see how it is used in the code for the sample
extension). This string is built up of the major version and a
combination of the minor version and the patchlevel. From the file
"configure.ac" (see Chapter 6) we have:
[example {
   #--------------------------------------------------------------------
   # __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.

#	number and returns all character until a character not in [0-9.ab]
#	is read.

!if [echo REM = This file is generated from Makefile.vc > versions.vc]
!endif
# get project version from row "AC_INIT([project], [????])"
!if [echo DOTVERSION = \>> versions.vc] \
   && [nmakehlp -V ..\configure.in sample >> versions.vc]
!endif
!include "versions.vc"

VERSION         = $(DOTVERSION:.=)
STUBPREFIX      = $(PROJECT)stub

DLLOBJS = \

#	number and returns all character until a character not in [0-9.ab]
#	is read.

!if [echo REM = This file is generated from Makefile.vc > versions.vc]
!endif
# get project version from row "AC_INIT([project], [????])"
!if [echo DOTVERSION = \>> versions.vc] \
   && [nmakehlp -V ..\configure.ac sample >> versions.vc]
!endif
!include "versions.vc"

VERSION         = $(DOTVERSION:.=)
STUBPREFIX      = $(PROJECT)stub

DLLOBJS = \