RCS: @(#) $Id: README.developer,v 1.5 2007/08/30 17:24:13 andreas_kupries Exp $

Welcome to the tcllib, the Tcl Standard Library.
================================================

Introduction
------------

This README is intended to be a guide to the tools available to a

	Developer

working on Tcllib to help him with his tasks, i.e. making the tasks easier
to perform. It is our hope that this will improve the quality of even
non-released revisions of Tcllib, and make the work of the release
manager easier as well.

Audience
--------

The intended audience, are first and foremost, developers beginning to
work on Tcllib. To an experienced developer this document will be less
of a guide and more of a reference. Anybody else interested in working
on Tcllib is invited as well.

Basics
------

< Flesh this out >

	sak.tcl

< Tasks, and how to perform them >


Adding a new module
-------------------

Assuming that FOO is the name of the new module, and T is the toplevel
directory of the Tcllib sources

(1)	Create the directory T/modules/FOO and put all the files of
	the module into it. Note:

	* The file 'pkgIndex.tcl' is required.

	* Implementation files should have the extension '.tcl',
	  naturally.

	* If available, documentation should be in doctools format,
          and the files should have the extension '.man' for SAK to
          recognize them.

	* If available the testsuite(s) should use 'tcltest' and the
	  general format as used by the other modules in Tcllib
	  (declaration of minimally needed Tcl, tcltest, supporting
	  packages, etc.). The file(s) should have the extension
	  '.test' for SAK to recognize them.

	  Note that an empty testsuite, or a testsuite which does not
	  perform any tests is less than useful and will not be
	  accepted.

	* If available the benchmark(s) should use 'bench' and the
          general format as used by the other modules in Tcllib. The
          file(s) should have the extension '.bench' for SAK to
          recognize them.

	* Other files can be named and placed as the module sees fit.

(2)	If the new module has an example application A which is
	polished enough for general use, put this application into the
	file "T/apps/A.tcl", and its documentation into the file
	"T/apps/A.man". While documentation for the application is
	optional, it is preferred.

	For examples which are not full-fledged applications, a
	skeleton, or not really polished for use, etc., create the
	directory T/examples/FOO/ and put them there.

	A key difference is what happens to them on installation, and
	what the target audience is.

	The examples are for developers using packages in Tcllib,
	whereas the applications are also for users of Tcllib which do
	not have an interest in developing for and with it. As such,
	they are installed as regular commands, accessible through the
	PATH, and example files are not installed.

(3)	To make Tcllib's installer aware of FOO, edit the file

		T/support/installation/modules.tcl

	Add a line 'Module FOO $impaction $docaction $exaction'. The
	various actions describe to the installer how to install the
	implementation files, the documentation, and the examples.

	Add a line 'Application A' for any application A which was
	added to T/apps for FOO.

	The following actions are available:

	Implementation

		_tcl - Copy all .tcl files in T/modules/FOO into the installation.
		_tcr - See above, does it for .tcl files in subdirectories as well.
		_tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'.
		_msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'.
		_doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'.
		_tex - _tcl + Copying of .tex files - special to module 'textutil'.

		The _null action, see below, is available in principle
		too, but a module without implementation does not make
		sense.

	Documentation

		_null - Module has no documentation, do nothing.
		_man  - Process the .man files in T/modules/FOO and
			install the results (nroff and/or HTML) in the
			proper location, as given to the installer.

	Examples

		_null - Module has no examples, do nothing
		_exa  - Copy the directory T/examples/FOO
			(recursively) to the install location for
			examples.


Testing modules
---------------

To run the testsuite of a module FOO in tcllib use the 'test run'
argument of sak.tcl, like so:

	% pwd
	/the/tcllib/toplevel/directory

	% ./sak.tcl test run FOO
or	% ./sak.tcl test run modules/FOO

To run the testsuites of all modules either invoke 'test run' without a
module name, or use 'make test'. The latter assumes that configure was
run for Tcllib before, i.e.:

	% ./sak.tcl test run FOO
or	% ./sak.tcl test run modules/FOO
	% make test

In all of the above cases the result will be a combination of progress
display and testsuite log, showing for each module the tests that pass
or failed and how many of each in a summary at the end.

To get a detailed log, it is necessary to invoke 'test run' with
additional options.

First example:
	% ./sak.tcl test run -l LOG FOO

This shows the same short log on the terminal, and writes a detailed
log to the file LOG.log, and excerpts to other files (LOG.summary,
LOG.failures, etc.).

Second example:
	% ./sak.tcl test run -v FOO
	% make test > LOG

This writes the detailed log to stdout, or to the file LOG, instead of
the short log. In all cases, the detailed log contains a list of all
test cases executed, which failed, and how they failed (expected
versus actual results).

Note:
The commands
	% make test
and	% make test > LOG

are able to generate different output (short vs long log) because the
Makefile target contains code which detects that stdout has been
redirected to a file and acts accordingly.

Non-developers should reports problems in Tcllib's bug tracker.
Information about its location and the relevant category can be found
in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module
and/or package.
