Tcl Library Source Code

Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

Hello. __Attention please__

You are currently using the github __mirror__ of the Tcllib sources.

This is __not__ the location where Tcllib development takes place.

We are __not tracking issues entered here__. With the exception of the
maintainer of the mirroring setup nobody will even see such issues.

Please go to the
[official location of the sources](https://core.tcl-lang.org/tcllib)
and enter your ticket into the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

Thank you for your consideration.

# Attention




:warning: 

This repository is mirrored to [github](https://github.com/tcltk/tcllib).



We are __not tracking issues at github__.  With the exeception of the
maintainer of the mirroring setup nobody will even see issues created
at github.

Please use the
[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist)
instead.

# Welcome

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) Tcl packages
that provide utility functions useful to a large collection of Tcl
programmers.

At our [home site](http://core.tcl-lang.org/tcllib) you will find the
official fossil repository used to manage our sources, together with
the bug tracker. This is also the main location for releases to
download from.

We have a
[secondary download location](https://sourceforge.net/projects/tcllib/files)
where the Tcllib sources were hosted in the past. SourceForge is also
where our [mailing lists](https://sourceforge.net/p/tcllib/mailman)
are (still) hosted.

Another location to find these sources at is the
[github mirror](https://github.com/tcltk/tcllib).

Please note the :warning: at the top.

# Guides To Tcllib

   * [Tcl Community - Kind Communication](embedded/www/tcllib/files/devdoc/tcl_community_communication.html)
   * [License](embedded/www/tcllib/files/devdoc/tcllib_license.html)
   * [How To Get The Sources](embedded/www/tcllib/files/devdoc/tcllib_sources.html)
   * [How To Build And Install Tcllib](embedded/www/tcllib/files/devdoc/tcllib_installer.html)
   * [The Developer's Guide](embedded/www/tcllib/files/devdoc/tcllib_devguide.html)
   * [The Release Manager's Guide](embedded/www/tcllib/files/devdoc/tcllib_releasemgr.html)

They are left in place, i.e. not deleted, to serve as demonstrations
of doctoc and docidx markup.

[list_end]

[vset CATEGORY doctools]
[include ../modules/common-text/feedback.inc]
[manpage_end]

If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the server has to listen on for requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

If this option is not specified it defaults to [const 38573]. It
specifies the TCP port the name service to talk to is listening on for
requests.

[list_end]

[vset CATEGORY nameserv]
[include ../modules/common-text/feedback.inc]
[manpage_end]

[para]

The contents of both environment variables and registry entries are
interpreted as a list of paths, with the elements separated by either
colon (Unix), or semicolon (Windows).

[vset CATEGORY page]
[include ../modules/common-text/feedback.inc]
[manpage_end]

Preambles, when active, are written before the actual content of a
generated file. In the same manner postambles are, when active,
written after the actual content of a generated file.

[list_end]

[vset CATEGORY docstrip]
[include ../modules/common-text/feedback.inc]
[manpage_end]

RCS: @(#) $Id: README.developer,v 1.6 2009/06/02 22:49:55 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.


Directory hierarchy and file basics
------------------------------------

The main directories under the tcllib top directory are

	modules/
	examples/
and	apps/

Each directory FOO under modules/ represents one package, sometimes
more. In the case of the latter the packages are usually related in
some way. Examples are the base64, math, and struct modules, with
loose (base64) to strong (math) relations between the packages.

Examples associated with a module FOO, if there are any, are placed
into the directory

	examples/FOO

Any type of distributable application can be found under apps/,
together with their documentation, if any. Note that the apps/
directory is currently not split into sub-directories.

Regarding the files in Tcllib, the most common types found are

	.tcl	Tcl code for a package.

	.man	Documentation for a package, in doctools format.

	.test	Test suite for a package, or part of. Based on tcltest.

	.bench	Performance benchmarks for a package, or part of.
		Based on modules/bench

	.pcx	Syntax rules for TclDevKit's tclchecker. Using these
		rules allows tclchecker to check the use of commands
		of a Tcllib package X without having to scan the
		implementation of X, i.e. its .tcl files.


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
or	% ./sak.tcl test run
	% 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.

Module documentation
--------------------

The main format used for the documentation of packages in Tcllib is
'doctools', the support packages of which are part of Tcllib, see the
module 'doctools'.

To convert this documentation to HTML or nroff manpages, or some other
format use the 'doc' argument of sak.tcl, like so:

	% pwd
	/the/tcllib/toplevel/directory

	% ./sak.tcl doc html FOO
or	% ./sak.tcl doc html modules/FOO

The result of the conversion can be found in the newly-created 'doc'
directory in the current working directory.

The set of formats the documentation can be converted into can be
queried via

	% ./sak.tcl help doc


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

	% ./sak.tcl doc html
	% make html-doc

Note the special format 'validate'. Using this format does not convert
the documentation to anything (and the sub-directory 'doc' will not be
created), it just checks that the documentation is syntactically
correct. I.e.

	% ./sak.tcldoc validate modules/FOO
	% ./sak.tcldoc validate


Validating modules
------------------

Running the testsuite of a module, or checking the syntax of its
documentation (see the previous sections) are two forms of validation.

The 'validate' command of sak.tcl provides a few more. The online
documentation of this command is available via

	% ./sak.tcl help validate

The validated parts are man pages, testsuites, version information,
and syntax. The latter only if various static syntax checkers are
available on the PATH, like TclDevKit's tclchecker.

Note that testsuite validation is not the execution of the testsuites,
only if a package has a testsuite or not.

It is strongly recommended to validate a module before committing any
type of change made to it.

It is recommended to validate all modules before committing any type
of change made to one of them. We have package inter-dependencies
between packages in Tcllib, thus changing one package may break
others, and just validating the changed package will not catch such
problems.


Writing Tests
-------------

While a previous section talked about running the testsuite for a
module and the packages therein this has no meaning if the module in
question has no testsuites at all.

This section gives a very basic overview on methodologies for writing
tests and testsuites.

First there are "drudgery" tests. Written to check absolutely basic
assumptions which should never fail.

Example:

	For a command FOO taking two arguments, three tests calling it
	with zero, one, and three arguments. The basic checks that the
	command fails if it has not enough arguments, or too many.

After that come the tests checking things based on our knowledge of
the command, about its properties and assumptions. Some examples based
on the graph operations added during Google's Summer of Code 2009.

**	The BellmanFord command in struct::graph::ops takes a
	_startnode_ as argument, and this node should be a node of the
	graph. equals one test case checking the behavior when the
	specified node is not a node a graph.

	This often gives rise to code in the implementation which
	explicitly checks the assumption and throws a nice error.
	Instead of letting the algorithm fails later in some weird
	non-deterministic way.

	Such checks cannot be done always. The graph argument for
	example is just a command in itself, and while we expect it to
	exhibit a certain interface, i.e. set of sub-commands aka
	methods, we cannot check that it has them, except by actually
	trying to use them. That is done by the algorithm anyway, so
	an explicit check is just overhead we can get by without.

**	IIRC one of the distinguishing characteristic of either
	BellmanFord and/or Johnson is that they are able to handle
	negative weights. Whereas Dijkstra requires positive weights.

	This induces (at least) three testcases ... Graph with all
	positive weights, all negative, and a mix of positive and
	negative weights.

	Thinking further does the algorithm handle the weight '0' as
	well ? Another test case, or several, if we mix zero with
	positive and negative weights.

**	The two algorithms we are currently thinking about are about
	distances between nodes, and distance can be 'Inf'inity,
	i.e. nodes may not be connected. This means that good test
	cases are

	(1)	Strongly connected graph
	(2)	Connected graph
	(3)	Disconnected graph.

	At the extremes of (1) and (3) we have the fully connected
	graphs and graphs without edges, only nodes, i.e. completely
	disconnected.

**	IIRC both of the algorithms take weighted arcs, and fill in a
	default if arcs are left unweighted in the input graph.

	This also induces three test cases:

	(1)	Graph will all arcs with explicit weights.
	(2)	Graph without weights at all.
	(3)	Graph with mixture of weighted and unweighted graphs.


What was described above via examples is called 'black-box' testing.
Test cases are designed and written based on our knowledge of the
properties of the algorithm and its inputs, without referencing a
particular implementation.

Going further, a complement to 'black-box' testing is 'white-box'. For
this we know the implementation of the algorithm, we look at it and
design our tests cases so that they force the code through all
possible paths in the implementation. Wherever a decision is made we
have a test cases forcing a specific direction of the decision, for
all possible directions.

In practice I often hope that the black-box tests I have made are
enough to cover all the paths, obviating the need for white-box tests.

So, if you, dear reader, now believe that writing tests for an
algorithm takes at least as much time as coding the algorithm, and
often more time, then you are completely right. It does. Much more
time. See for example also http://sqlite.org/testing.html, a writeup
on how the Sqlite database engine is tested.



An interesting connection is to documentation. In one direction, the
properties you are checking with black-box testing are properties
which should be documented in the algorithm man page. And conversely,
if you have documentation of properties of an algorithm then this is a
good reference to base black-box tests on.

In practice test cases and documentation often get written together,
cross-influencing each other. And the actual writing of test cases is
a mix of black and white box, possibly influencing the implementation
while writing the tests. Like writing test for 'startnode not in input
graph' serving as reminder to put in a check for this into the code.

While the majority of Tcllib consists of packages written in pure Tcl
a number of packages also have [term accelerators] associated with them.

These are [syscmd critcl]-based C packages whose use will boost the
performance of the packages using them.

These accelerators are optional, and they are not installed by
default.

[para] To build the accelerators the normally optional dependency on
       [syscmd critcl] becomes required.

[para] To build and install Tcllib with the accelerators in a
       Unix-like environment invoke:

[example {
  ./configure
  make critcl # This builds the shared library holding
              # the accelerators
  make install
}]

[para] The underlying tool is [file sak.tcl] in the toplevel directory
of Tcllib and the command [cmd {make critcl}] is just a wrapper around

[example {
  ./sak.tcl critcl
}]

[para] Therefore in a Windows environment instead invoke

[example {
  ./sak.tcl critcl
  ./installer.tcl
}]

from within a DOS window, i.e. [syscmd cmd.exe].

The core of Tcllib's build system is the script [file installer.tcl]
found in the toplevel directory of a checkout or release.

[para] The
       [example {
         configure ; make install
       }]
       setup available to
       developers on Unix-like systems is just a wrapper around it.

       To go beyond the standard embodied in the wrapper it is
       necessary to directly invoke this script.

[para] On Windows system using it directly is the only way to invoke
       it.

[para] For basic help invoke it as

       [example {
         ./installer.tcl -help
       }]

       This will print a short list of all the available options to
       the standard output channel.

[para] The commands associated with the various [term install] targets
       in the [term Makefile.in] for Unix can be used as additional
       examples on how to use this tool as well.

[para] The installer can operate in GUI and CLI modes.

       By default it chooses the mode automatically, based on if the
       Tcl package [package Tk] can be used or not.

       The option [option -no-gui] can be used to force CLI mode.

[para] Note that it is possible to specify options on the command line
       even if the installer ultimatively selects GUI mode. In that
       case the hardwired defaults and the options determine the data
       presented to the user for editing.

[para] The installer will select a number of defaults for the
       locations of packages, examples, and documentation, and also
       the format of the documentation. The user can overide these
       defaults in the GUI, or by specifying additional options.

       The defaults depend on the platform detected (Unix/Windows) and
       on the [syscmd tclsh] executable used to run the installer.

[para][emph Options]

[list_begin options]
[opt_def -help]

Show the list of options explained here on the standard output channel
and exit.

[opt_def +excluded]

Include deprecated packages in the installation.

[opt_def -no-gui]

Force command line operation of the installer

[opt_def -no-wait]

In CLI mode the installer will by default ask the user to confirm that
the chosen configuration (destination paths, things to install) is
correct before performing any action. Using this option causes the
installer to skip this query and immediately jump to installation.

[opt_def -app-path [arg path]]
[opt_def -example-path [arg path]]
[opt_def -html-path [arg path]]
[opt_def -nroff-path [arg path]]
[opt_def -pkg-path [arg path]]

Declare the destination paths for the applications, examples, html
documentation, nroff manpages, and packages. The defaults are derived
from the location of the [syscmd tclsh] used to run the installer.

[opt_def -dry-run]
[opt_def -simulate]

Run the installer without modifying the destination directories.

[opt_def -apps]
[opt_def -no-apps]
[opt_def -examples]
[opt_def -no-examples]
[opt_def -pkgs]
[opt_def -no-pkgs]
[opt_def -html]
[opt_def -no-html]
[opt_def -nroff]
[opt_def -no-nroff]

(De)activate the installation of applications, examples, packages,
html documentation, and nroff manpages.

[para] Applications, examples, and packages are installed by default.

[para] On Windows the html documentation is installed by default.

[para] On Unix the nroff manpages are installed by default.

[list_end]

For [term Unix]-like environments Tcllib comes with the standard set
of files to make

[example {
  ./configure
  make install
}]

a suitable way of installing it.

This is a standard non-interactive install automatically figuring out
where to place everything, i.e. packages, applications, and the
manpages.

[para] To get a graphical installer invoke

[example {
  ./installer.tcl
}]

instead.

In a Windows environment we have the [cmd installer.tcl] script to
perform installation.

[para] If the desired [syscmd tclsh] is associated [file .tcl] files
       then double-clicking / opening the [cmd installer.tcl] is
       enough to invoke it in graphical mode.

       This assumes that [term Tk] is installed and available as well.

[para] Without [term Tk] the only way to invoke the installer are to
       open a DOS window, i.e. [syscmd cmd.exe], and then to invoke
      
[example {
  ./installer.tcl
}]

inside it.

In the hope of engendering good work practices now a few example
operations which will come up with branches, and their associated
fossil command (sequences).

[list_begin definitions]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph Awareness]]
[include d_op_aware.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Clean checkouts}]]
[include d_op_clean.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Starting a new branch}]]
[include d_op_branch_open.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Merging a branch into trunk}]]
[include d_op_branch_close.inc]

[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~]
[def [emph {Merging from trunk}]]
[include d_op_branch_import.inc]

[list_end]

Given the constraints placed on the [term trunk] branch of the
repository it is (strongly) recommended to perform any development
going beyond trivial changes on a non-trunk branch.

[para] Outside of the trunk developers are allowed to commit
       intermediate broken states of their work.

       Only at the end of a development cycle, when the relevant
       branch is considered ready for merging, will it be necessary to
       perform full the set of validations ensuring that the merge to
       come will create a good commit on trunk.

[para] Note that while a review from a second developer is not a
       required condition for merging a branch it is recommended to
       seek out such an independent opinion as a means of
       cross-checking the work.

[para] It also recommended to give any new branch a name which aids in
       determining additional details about it. Examples of good
       things to stick into a branch name would be

[list_begin itemized]
[item]	Developer (nick)name
[item]	Ticket hash/reference
[item]	One or two keywords applicable to the work
[item]	...
[list_end]

[para] Further, while most development branches are likely quite
       short-lived, no prohibitions exist against making longer-lived
       branches.

       Creators should however be mindful that the longer such a
       branch exists without merges the more divergent they will tend
       to be, with an associated increase in the effort which will
       have to be spent on either merging from and merging to trunk.

Regarding packages and dependencies between them Tcllib occupies a
middle position between two extremes:

[list_begin enumerated]

[enum] On one side a strongly interdependent set of packages, usually
       by a single author, for a single project. Looking at my
       (Andreas Kupries) own work examples of such are
       [uri https://core.tcl.tk/akupries/marpa/index Marpa],
       [uri https://core.tcl.tk/akupries/crimp/index CRIMP],
       [uri https://core.tcl.tk/akupries/kinetcl/index Kinetcl], etc.

[para] For every change the author of the project handles all the
       modifications cascading from any incompatibilities it
       introduced to the system.

[enum] On the other side, the world of semi-independent projects by
       many different authors where authors know what packages their
       own creations depend on, yet usually do not know who else
       depends on them.

[para] The best thing an author making an (incompatible) change to
       their project can do is to for one announce such changes in
       some way, and for two use versioning to distinguish the code
       before and after the change.

[para] The world is then responsible for adapting, be it by updating
       their own projects to the new version, or by sticking to the
       old.

[list_end]

As mentioned already, Tcllib lives in the middle of that.

[para] While we as maintainers cannot be aware of all users of
       Tcllib's packages, and thus have to rely on the mechanisms
       touched on in point 2 above for that, the dependencies between
       the packages contained in Tcllib are a different matter.

[para] As we are collectively responsible for the usability of Tcllib
       in toto to the outside world, it behooves us to be individually
       mindful even of Tcllib packages we are not directly
       maintaining, when they depend on packages under our
       maintainership.

       This may be as simple as coordinating with the maintainers of
       the affected packages.

       It may also require us to choose how to adapt affected packages
       which do not have maintainers, i.e. modify them to use our
       changed package properly, or modify them to properly depend on
       the unchanged version of our package.

[para] Note that the above is not only a chore but an opportunity as
       well.

       Additional insight can be had by forcing ourselves to look at
       our package and the planned change(s) from an outside
       perspective, to consider the ramifications of our actions on
       others in general, and on dependent packages in particular.

The management and use of branches is an important part of working
with a [term {Distributed Version Control System}] ([term DVCS]) like
[uri https://www.fossil-scm.org/ fossil].

[para] For Tcllib the main branch of the collection is
       [term trunk]. In [term git] this branch would be called
       [term master], and this is exactly the case in the
       [uri https://github.com/tcltk/tcllib/ {github mirror}] of
       Tcllib.

[para] To properly support debugging [emph {each commit}] on this
       branch [emph {has to pass the entire testsuite}] of the
       collection. Using bisection to determine when an issue appeared
       is an example of an action made easier by this constraint.

[para] This is part of our collective responsibility for the usability
       of Tcllib in toto to the outside world.

       As [term fossil] has no mechanism to enforce this condition
       this is handled on the honor system for developers and maintainers.

[para] To make the task easier Tcllib comes with a tool
       ([file sak.tcl]) providing a number of commands in
       support. These commands are explained in the following sections
       of this guide.

[para] While it is possible and allowed to commit directly to trunk
       remember the above constraint regarding the testsuite, and the
       coming notes about other possible issues with a commit.

In Tcllib all changes to a package have to come with an increment of
its version number. What part is incremented (patchlevel, minor, major
version) depends on the kind of change made. With multiple changes in
a commit the highest "wins".

[para] When working in a development branch the version change can be
       deferred until it is time to merge, and then has to cover all
       the changes in the branch.

[para] Below a list of the kinds of changes and their associated
       version increments:

[list_begin definitions]
[def [term {D - documentation}]] No increment
[def [term {T - testsuite}]] No increment
[def [term {B - bugfix}]] Patchlevel
[def [term {I - implementation tweak}]] Patchlevel
[def [term {P - performance tweak}]] Patchlevel
[def [term {E - backward-compatible extension}]] Minor
[def [term {API - incompatible change}]] Major
[list_end]

[para] Note that a commit containing a version increment has to
       mention the new version number in its commit message, as well
       as the kind of change which caused it.

[para] Note further that the version number of a package currently
       exists in three places. An increment has to update all of them:

[list_begin enumerated]
[enum] The package implementation.
[enum] The package index ([file pkgIndex.tcl])
[enum] The package documentation.
[list_end]

[para] The [file sak.tcl] command [cmd {validate version}] helps
       finding discrepancies between the first two.

       All the other [cmd validate] methods are also of interest to
       any developer. Invoke it with

       [example { sak.tcl help validate }]

       to see their documentation.

[comment {===================================================================}]
[subsection {Package Dependencies}]
[include d_bf_dependencies.inc]

[comment {===================================================================}]
[subsection Trunk]
[include d_bf_trunk.inc]

[comment {===================================================================}]
[subsection Branches]
[include d_bf_branches.inc]

[comment {===================================================================}]
[subsection {Working with Branches}]
[include d_bf_branchcmds.inc]

[comment {===================================================================}]
[subsection {Version numbers}]
[include d_bf_versions.inc]

As a contributor to Tcllib you are committing yourself to:

[list_begin enumerated]

[enum] keep the guidelines written down in
       [term {Tcl Community - Kind Communication}] in your mind.
       The main point to take away from there is
       [emph {to be kind to each other}].

[enum] Your contributions getting distributed under a BSD/MIT license.
       For the details see [term {Tcllib - License}]

[list_end]

Contributions are made by entering tickets into our tracker, providing
patches, bundles or branches of code for inclusion, or posting to the
Tcllib related mailing lists.

[subsection {Main Directories}]

The main directories in the Tcllib toplevel directory and of interest
to a developer are:

[list_begin definitions]

[def [file modules]]

Each child directory represents one or more packages.

In the case of the latter the packages are usually related in some
way. Examples are [file base64], [file math], and [file struct], with
loose (base64) to strong (math) relations between the packages in the
directory.

[def [file apps]]

This directory contains all the installable applications, with their
documentation. Note that this directory is currently [emph not] split
into sub-directories.

[def [file examples]]

Each child directory [file foo] contains one or more example
application for the packages in [file modules/foo]. These examples are
generally not polished enough to be considered for installation.

[list_end]

[subsection {More Directories}]

[list_begin definitions]

[def [file config]]

This directory contains files supporting the Unix build system,
i.e. [file configure] and [file Makefile.in].

[def [file devdoc]]

This directories contains the doctools sources for the global
documentation, like this document and its sibling guides.

[def [file embedded]]

This directory contains the entire documentation formatted for
[term HTML] and styled to properly mix into the web site generated by
fossil for the repository.

[para] This is the documentation accessible from the Tcllib home
directory, represented in the repository as [file embedded/index.md].

[def [file idoc]]

This directory contains the entire documentation formatted for
[term nroff] and [term HTML], the latter without any styling.
This is the documentation which will be installed.

[def [file support]]

This directory contains the sources of internal packages and utilities
used in the implementation of the [file installer.tcl] and
[file sak.tcl] scripts/tools.

[list_end]

[subsection {Top Files}]

[list_begin definitions]
[def [file aclocal.m4]]
[def [file configure]]
[def [file configure.in]]
[def [file Makefile.in]]

These four files comprise the Unix build system layered on top of the
[file installer.tcl] script.

[def [file installer.tcl]]

The Tcl-based installation script/tool.

[def [file project.shed]]

Configuration file for [term {Sean Wood}]'s [syscmd PracTcl]
buildsystem.

[def [file sak.tcl]]
This is the main tool for developers and release managers, the
[term {Swiss Army Knife}] of management operations on the collection.

[def [file ChangeLog]]

The log of changes to the global support, when the sources were held
in [term CVS]. Not relevant any longer with the switch to the
[term fossil] SCM.

[def [file license.terms]]

The license in plain ASCII. See also [term {Tcllib - License}] for the
nicely formatted form. The text is identical.

[def [file README.md]]
[def [file .github/CONTRIBUTING.md]]
[def [file .github/ISSUE_TEMPLATE.md]]
[def [file .github/PULL_REQUEST_TEMPLATE.md]]

These markdown-formatted documents are used and shown by the github
mirror of these sources, pointing people back to the official location
and issue trackers.

[def [file DESCRIPTION.txt]]
[def [file STATUS]]
[def [file tcllib.spec]]
[def [file tcllib.tap]]
[def [file tcllib.yml]]

????

[list_end]

[subsection {File Types}]

The most common file types, by file extension, are:

[list_begin definitions]

[def [file .tcl]]
Tcl code for a package, application, or example.

[def [file .man]]
Doctools-formatted documentation, usually for a package.

[def [file .test]]
Test suite for a package, or part of.
Based on [package tcltest].

[def [file .bench]]
Performance benchmarks for a package, or part of.
Based on [file modules/bench].

[def [file .pcx]]
Syntax rules for [term TclDevKit]'s [syscmd tclchecker]. Using these
rules allows the checker to validate the use of commands of a Tcllib
package [package foo] without having to scan the [file .tcl] files
implementing it.

[list_end]

The standard format used for documentation of packages and other
things in Tcllib is [term doctools].

Its supporting packages are a part of Tcllib, see the directories
[file modules/doctools] and [file modules/dtplite]. The latter is
an application package, with the actual application
[file apps/dtplite] a light wrapper around it.

[para] Tcllib developers gain access to these through the [cmd doc]
method of the [file sak.tcl] tool, another (internal) wrapper around
the [file modules/dtplite] application package.

[comment {===================================================================}]
[subsection {Generate documentation for a specific module}]

Invoke either

[example {  ./sak.tcl doc html foo }]

or

[example {  ./sak.tcl doc html modules/foo }]

to generate HTML for the documentation found in the module [file foo].

Instead of [const html] any other supported format can be used here,
of course.

[para] The generated formatted documentation will be placed into a
directory [file doc] in the current working directory.

[comment {===================================================================}]
[subsection {Generate documentation for all modules}]

Invoke the tool without a module name, i.e.

[example {  ./sak.tcl doc html }]

to generate HTML for the documentation found in all modules.

Instead of [const html] any other supported format can be used here,
of course.

[para] The generated formatted documentation will be placed into a
directory [file doc] in the current working directory.

[comment {===================================================================}]
[subsection {Available output formats, help}]

Invoke the tool as

[example {  ./sak.tcl help doc }]

to see the entire set of supported output formats which can be
generated.

[comment {===================================================================}]
[subsection {Validation without output}]

Note the special format [const validate].

[para] Using this value as the name of the format to generate forces
the tool to simply check that the documentation is syntactically
correct, without generating actual output.

[para] Invoke it as either

[example {  ./sak.tcl doc validate (modules/)foo }]

or

[example {  ./sak.tcl doc validate }]

to either check the packages of a specific module or check all of
them.

A last thing to consider when adding a new package to the collection
is installation.

[para] How to [emph use] the [file installer.tcl] script is documented
in [term {Tcllib - The Installer's Guide}].

[para] Here we document how to extend said installer so that it may
install new package(s) and/or application(s).

[para] In most cases only a single file has to be modified, the
[file support/installation/modules.tcl] holding one command per module
and application to install.

[para] The relevant commands are:

[list_begin definitions]

[call [cmd Module] [arg name] \
      	   [arg code-action] \
      	   [arg doc-action] \
	   [arg example-action]]

Install the packages of module [arg name], found in
[file modules/[arg name]].

[para] The [arg code-action] is responsible for installing the
packages and their index. The system currently provides

[list_begin definitions]

[def [cmd _tcl]] Copy all [file .tcl] files found in
[file modules/[arg name]] into the installation.

[def [cmd _tcr]] As [cmd _tcl], copy the [file .tcl] files found in
the subdirectories of [file modules/[arg name]] as well.

[def [cmd _tci]] As [cmd _tcl], and copy the [file tclIndex.tcl] file
as well.

[def [cmd _msg]] As [cmd _tcl], and copy the subdirectory [file msgs]
as well.

[def [cmd _doc]] As [cmd _tcl], and copy the subdirectory
[file mpformats] as well.

[def [cmd _tex]] As [cmd _tcl], and copy [file .tex] files as well.

[list_end]

[para] The [arg doc-action] is responsible for installing the package
documentation. The system currently provides

[list_begin definitions]
[def [cmd _null]] No documentation available, do nothing.

[def [cmd _man]] Process the [file .man] files found in
[file modules/[arg name]] and install the results (nroff and/or HTML)
in the proper location, as given to the installer.

[para] This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under [file idoc].

[list_end]

[para] The [arg example-action] is responsible for installing the
examples. The system currently provides

[list_begin definitions]
[def [cmd _null]] No examples available, do nothing.

[def [cmd _exa]] Copy the the directory [file examples/[arg name]]
recursively to the install location for examples.

[list_end]

[call [cmd Application] [arg name]]

Install the application with [arg name], found in [file apps].


[call [cmd Exclude] [arg name]]

This command signals to the installer which of the listed modules to
[emph not] install. I.e. they name the deprecated modules of Tcllib.

[list_end]

[para] If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
[file support/installation/actions.tcl].

[para] This file contains the implementations of the available
actions, and is the place where any custom action needed to handle the
special circumstances of module has to be added.

When contributing one or more packages for full inclusion into Tcllib
you are committing yourself to

[list_begin enumerated]

[enum] Keep the guidelines written down in
       [term {Tcl Community - Kind Communication}]
       (as any contributor) in your mind. The main point to take away
       from there is [emph {to be kind to each other}].

[enum] Your packages getting distributed under a BSD/MIT license.  For
       the details see [term {Tcllib - License}]

[enum] Maintenance of the new packages for a period of two years under
       the following rules, and responsibilities:

       [list_begin enumerated]

       [enum] A maintainer may step down after the mandatory period as
       	      they see fit.

       [enum] A maintainer may step down before the end of the
      	      mandatory period, under the condition that a replacement
      	      maintainer is immediately available and has agreed to
      	      serve the remainder of the period, plus their own
      	      mandatory period (see below).

       [enum] When stepping down without a replacement maintainer
      	      taking over the relevant packages have to be flagged as
      	      [const unmaintained].

       [enum] When a replacement mantainer is brought in for a package
      	      it is (kept) marked as [const maintained] (again).

       [para] A replacement maintainer is bound by the same rules as
	      the original maintainer, except that the mandatory
	      period of maintenance is shortened to one year.

       [enum] For any [const unmaintained] package a contributor
       	      interested in becoming its maintainer can become so by
       	      flagging them as [const maintained] with their name and
       	      contact information, committing themselves to the rules
       	      of a replacement maintainer (see previous point).

       [enum] For any already [const maintained] package a contributor
       	      interested in becoming a co-maintainer can become so
       	      with the agreement of the existing maintainer(s),
       	      committing themselves to the rules of a replacement
       	      maintainer (see two points previous).

       [list_end]

       [para] The responsibilities as a maintainer include:

       [list_begin enumerated]

       [enum] Watching Tcllib's ticket tracker for bugs, bug fixes,
       	      and feature requests related to the new packages.

       [enum] Reviewing the aforementioned tickets, rejecting or
       	      applying them

       [enum] Coordination and discussion with ticket submitter during
       	      the development and/or application of bug fixes.

       [list_end]

[enum] Follow the [sectref {Branching and Workflow}] of this guide.

[list_end]

When developing we have to keep ourselves aware of the context of our
work. On what branch are we ? What files have we changed ? What new
files are not yet known to the repository ? What has happened remotely
since we used our checkout ?

The answers to these questions become especially important when using
a long-lived checkout and coming back to it after some time away.

[para] Commands to answer questions like the above are:

[list_begin definitions]

[def [cmd {fossil pull}]]

       Get all changes done on the remote since the last pull or sync
       from it. This has to be done first, before any of the commands
       below.

[para] Even if the commit in our checkout refers to the branch we want
       right now control operations committed to the remote may have
       changed that from underneath us.

[def [cmd {fossil info | grep tags}]]
[def [cmd {fossil branch list | grep '\*'}]]

       Two different ways of determining the branch our checkout is
       on.

[def [cmd {fossil timeline}]]

       What have we (and others) done recently ?

[para] [emph Attention], this information is very likely outdated, the
       more the longer we did not use this checkout.

       Run [cmd {fossil pull}] first to get latest information from
       the remote repository of the project.

[def [cmd {fossil timeline current}]]

       Place the commit our checkout is based on at the top of the
       timeline.

[def [cmd {fossil changes}]]

       Lists the files we have changed compared to the commit the
       checkout is based on.

[def [cmd {fossil extra}]]

       Lists the files we have in the checkout the repository does not
       know about. This may be leftover chaff from our work, or
       something we have forgotten to [cmd {fossil add}] to the
       repository yet.

[list_end]

Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).

       In the full-blown sequence (zig-zag) it is [emph required], due
       to the merging from trunk. In the shorter sequence it is only
       desired. That said, keeping the checkout clean before
       any major operations is a good habit to have, in my opinion.

[para] The full-blown sequencing with checks all the way is to

[list_begin enumerated]

[enum] Validate the checkout, i.e. last commit on your branch. Run the
       full test suite and other validations, fix all the issues which
       have cropped up.

[enum] Merge the latest state of the [term trunk] (see next definition).

[enum] Validate the checkout again. The incoming trunk changes may
       have broken something now. Do any required fixes.

[enum] Now merge to the trunk using

[example {
    fossil update trunk
    fossil merge --integrate YOUR_BRANCH
}]

[enum] At this point the checkout should be in the same state as at
       the end of point (3) above, because we resolved any issues with
       the trunk already. Thus a simple

[example {
    fossil commit ...
}]

       should be sufficient now to commit the merge back and close the
       branch (due to the [option --integrate] we used on the merge).

[para] The more paranoid may validate the checkout a third time before
       commiting.
[list_end]

[para] I call this a [term {zig-zag merge}] because of how the arrows
       look in the timeline, from trunk to feature branch for the
       first merge, and then back for the final merge.

[para] A less paranoid can do what I call a [term {simple merge}],
       which moves step (2) after step (4) and skips step (3)
       entirely. The resulting shorter sequence is

[list_begin enumerated]
[enum] Validate
[enum] Merge to trunk
[enum] Validate again
[enum] Commit to trunk
[list_end]

The last step after either zig-zag or plain merge is to

[example {
    fossil sync
}]

This saves our work to the remote side, and further gives us any other
work done while we were doing our merge. It especially allows us to
check if we raced somebody else, resulting in a split trunk.

[para] When that happens we should coordinate with the other developer
       on who fixes the split, to ensure that we do not race each
       other again.

Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).
       It is [emph required].
       
[para] In most situations you want to import the latest commit of
       branch [term trunk] (or other origin). To get it use

[example {
    fossil pull
}]

[para] With that done we can now import this commit into our current
       branch with

[example {
    fossil merge trunk
}]

[para] Even if [syscmd fossil] does not report any conflicts it is a
       good idea to check that the operation has not broken the new
       and/or changed functionality we are working on.

[para] With the establishment of a good merge we then save the state
       with

[example {
    fossil commit ...
}]

before continuing development.

Be aware of where you are (see first definition).

[para] Ensure that you have clean checkout (see second definition).
       It is [emph required].

[para] In most situations you want to be on branch [term trunk], and
       you want to be on the latest commit for it. To get there use

[example {
    fossil pull
    fossil update trunk
}]

If some other branch is desired as the starting point for the coming
work replace [term trunk] in the commands above with the name of that
branch.

[para] With the base line established we now have two ways of creating
       the new branch, with differing (dis)advantages.

       The simpler way is to

[example {
    fossil branch new NAME_OF_NEW_BRANCH
}]

and start developing. The advantage here is that you cannot forget to
create the branch. The disadvantages are that we have a branch commit
unchanged from where we branched from, and that we have to use
high-handed techniques like hiding or shunning to get rid of the
commit should we decide to abandon the work before the first actual
commit on the branch.

[para] The other way of creating the branch is to start developing,
and then on the first commit use the option [option --branch] to tell
[syscmd fossil] that we are starting a branch now. I.e. run

[example {
    fossil commit --branch NAME_OF_NEW_BRANCH ...
}]

where [term ...] are any other options used to supply the commit
message, files to commit, etc.

[para] The (dis)advantages are now reversed.

[para] We have no superflous commit, only what is actually
       developed. The work is hidden until we commit to make our first
       commit.

[para] We may forget to use [option {--branch NAME_OF_NEW_BRANCH}] and
       then have to correct that oversight via the fossil web
       interface (I am currently unaware of ways of doing such from
       the command line, although some magic incantantion of
       [cmd {fossil tag create}] may work).

[para] It helps to keep awareness, like checking before any commit
       that we are on the desired branch.

Be aware of where you are (see first definition).

[para] For pretty much all the operation recipes below a clean
       checkout is at least desired, often required.
       To check that a checkout is clean invoke

[example {
    fossil changes
    fossil extra
}]

How to clean up when uncommitted changes of all sorts are found is
context-specific and outside of the scope of this guide.

Testsuites in Tcllib are based on Tcl's standard test package
[package tcltest], plus utilities found in the directory
[file modules/devtools]

[para] Tcllib developers invoke the suites through the
[cmd {test run}] method of the [file sak.tcl] tool, with other methods
of [cmd test] providing management operations, for example setting a
list of standard Tcl shells to use.

[comment {===================================================================}]
[subsection {Invoke the testsuites of a specific module}]

Invoke either

[example {  ./sak.tcl test run foo }]

or

[example {  ./sak.tcl test run modules/foo }]

to invoke the testsuites found in a specific module [file foo].

[comment {===================================================================}]
[subsection {Invoke the testsuites of all modules}]

Invoke the tool without a module name, i.e.

[example {  ./sak.tcl test run }]

to invoke the testsuites of all modules.

[comment {===================================================================}]
[subsection {Detailed Test Logs}]

In all the previous examples the test runner will write a combination
of progress display and testsuite log to the standard output, showing
for each module only the tests that passed or failed and how many of
each in a summary at the end.

[para] To get a detailed log, it is necessary to invoke the test
runner with additional options.

[para] For one:

[example {
   ./sak.tcl test run --log LOG foo
}]

While this shows the same short log on the terminal as before, it also
writes a detailed log to the file [file LOG.log], and excerpts to
other files ([file LOG.summary], [file LOG.failures], etc.).

[para] For two:

[example {
  ./sak.tcl test run -v foo
}]

This writes the detailed log to the standard output, instead of the
short log.

[para] Regardless of form, the detailed log contains a list of all test
cases executed, which failed, and how they failed (expected versus
actual results).

[comment {===================================================================}]
[subsection {Shell Selection}]

By default the test runner will use all the Tcl shells specified via
[cmd {test add}] to invoke the specified testsuites, if any. If no
such are specified it will fall back to the Tcl shell used to run the
tool itself.

[para] Use option [option --shell] to explicitly specify the Tcl shell
to use, like

[example {
  ./sak.tcl test run --shell /path/to/tclsh ...
}]

[comment {===================================================================}]
[subsection Help]

Invoke the tool as

[example {  ./sak.tcl help test }]

to see the detailed help for all methods of [cmd test], and the
associated options.

While previous sections talked about running the testsuites for a
module and the packages therein, this has no meaning if the module in
question has no testsuites at all.

[para] This section gives a very basic overview on possible
methodologies for writing tests and testsuites.

[para] First there are "drudgery" tests. Written to check absolutely
basic assumptions which should never fail.

[para] For example for a command FOO taking two arguments, three tests
calling it with zero, one, and three arguments. The basic checks that
the command fails if it has not enough arguments, or too many.

[para] After that come the tests checking things based on our
knowledge of the command, about its properties and assumptions. Some
examples based on the graph operations added during Google's Summer of
Code 2009 are:

[list_begin itemized]

[item]	The BellmanFord command in struct::graph::ops takes a
	[arg startnode] as argument, and this node should be a node of
	the graph. This equals one test case checking the behavior when the
	specified node is not a node of the graph.

[para]  This often gives rise to code in the implementation which
	explicitly checks the assumption and throws an understandable error,
	instead of letting the algorithm fail later in some weird
	non-deterministic way.

[para]  It is not always possible to do such checks. The graph argument
	for example is just a command in itself, and while we expect
	it to exhibit a certain interface, i.e. a set of sub-commands
	aka methods, we cannot check that it has them, except by
	actually trying to use them. That is done by the algorithm
	anyway, so an explicit check is just overhead we can get by
	without.

[item]  IIRC one of the distinguishing characteristic of either
	BellmanFord and/or Johnson is that they are able to handle
	negative weights. Whereas Dijkstra requires positive weights.

[para]	This induces (at least) three testcases ... Graph with all
	positive weights, all negative, and a mix of positive and
	negative weights.

	Thinking further does the algorithm handle the weight
	[const 0] as well ? Another test case, or several, if we mix
	zero with positive and negative weights.

[item]	The two algorithms we are currently thinking about are about
	distances between nodes, and distance can be 'Inf'inity,
	i.e. nodes may not be connected. This means that good test
	cases are

	[list_begin enumerated]
	[enum]	Strongly connected graph
	[enum]	Connected graph
	[enum]	Disconnected graph.
	[list_end]

	[para] At the extremes of strongly connected and disconnected
	we have the fully connected graphs and graphs without edges,
	only nodes, i.e. completely disconnected.

[item]	IIRC both of the algorithms take weighted arcs, and fill in a
	default if arcs are left unweighted in the input graph.

	[para] This also induces three test cases:

	[list_begin enumerated]
	[enum]	Graph will all arcs with explicit weights.
	[enum]	Graph without weights at all.
	[enum]	Graph with mixture of weighted and unweighted graphs.
	[list_end]
[list_end]

[para] What was described above via examples is called
[term black-box] testing. Test cases are designed and written based on
the developer's knowledge of the properties of the algorithm and its
inputs, without referencing a particular implementation.

[para] Going further, a complement to [term black-box] testing is
[term white-box]. For this we know the implementation of the
algorithm, we look at it and design our tests cases so that they force
the code through all possible paths in the implementation. Wherever a
decision is made we have a test case forcing a specific direction of
the decision, for all possible combinations and directions. It is easy
to get a combinatorial explosion in the number of needed test-cases.

[para] In practice I often hope that the black-box tests I have made
are enough to cover all the paths, obviating the need for white-box
tests.

[para] The above should be enough to make it clear that writing tests
for an algorithm takes at least as much time as coding the algorithm,
and often more time. Much more time.

See for example also [uri http://sqlite.org/testing.html], a writeup
on how the Sqlite database engine is tested. Another article of
interest might be [uri https://www.researchgate.net/publication/298896236].
While geared to a particular numerical algorithm it still shows that
even a simple-looking algorithm can lead to an incredible number of
test cases.

[para] An interesting connection is to documentation. In one
direction, the properties checked with black-box testing are exactly
the properties which should be documented in the algorithm's man
page. And conversely, the documentation of the properties of an
algorithm makes a good reference to base the black-box tests on.

[para] In practice test cases and documentation often get written
together, cross-influencing each other. And the actual writing of test
cases is a mix of black and white box, possibly influencing the
implementation while writing the tests. Like writing a test for a
condition like [term {startnode not in input graph}] serving as
reminder to put a check for this condition into the code.

With the release made it has to be published and the world notified of
its existence.

[list_begin enumerated]

[enum]	    Create a proper fossil event for the release, via
	    [uri http://core.tcl-lang.org/tcllib/eventedit].

[para]	    An [uri http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 {existing event}] should be used as template.

[enum]	    Update a number of web locations:

[list_begin enumerated]
[enum]	    [uri http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md {Home page}]
[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Downloads     Downloads]
[enum]	    [uri http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases {Past Releases}]
[enum]	    [uri http://www.tcl-lang.org/home/release.txt     ]
[enum]	    [uri http://www.tcl-lang.org/software/tcllib/*.tml]
[enum]	    [uri http://wiki.tcl-lang.org/page/Tcllib]
[list_end]

The first location maps to the file [file embedded/index.md] in the
repository itself, as such it can edited as part of the release
process. This is where reference to the new fossil event is added, as
the new current release.

[para] The next two locations are in the fossil tcllib wiki and
require admin or wiki write permissions for
[uri http://core.tcl-lang.org/tcllib].

[para] The last two locations require ssh access to
[uri http://www.tcl-lang.org] and permission to edit
files in the web area.


[enum]	***TODO*** mailing lists and other places to send notes to.

[list_end]

todo: finalize release, make candidate official

todo: open a candidate for release

The [file sak.tcl] script in the toplevel directory of a Tcllib
checkout is the one tool used by the release manager to perform its
[sectref Tasks].

[para] The main commands to be used are

[example {
    sak.tcl validate
    sak.tcl test run
    sak.tcl review
    sak.tcl readme
    sak.tcl localdoc
    sak.tcl release
}]

More detail will be provided in the explanations of the various
[sectref Tasks].

todo: test, validate and check that the candidate is worthy of release
fix testsuites, possibly fix packages, documentation
regenerate docs
coordinate with package maintainers wrt fixes

big thing: going over the packages, classify changes since last
release to generate a nice readme.

[subsection Critcl]

The [syscmd critcl] tool is an [emph optional] dependency.

[para] It is only required when trying to build the C-based
[term accelerators] for a number of packages, as explained in
[sectref {Critcl & Accelerators}]

[para] Tcllib's build system looks for it in the [variable PATH],
using the name [syscmd critcl]. This is for Unix.

On Windows on the other hand the search is more complex. First we look
for a proper application [syscmd critcl.exe]. When that is not found
we look for a combination of interpreter ([syscmd tclkitsh.exe],
[syscmd tclsh.exe]) and starkit ([syscmd critcl.kit], [syscmd critcl])
instead. [emph Note] that the choice of starkit can be overriden via
the environment variable [variable CRITCL].

[para] Tcllib requires Critcl version 2 or higher.

[para] The github repository providing releases of version 2 and
higher, and the associated sources, can be found at
[uri http://andreas-kupries.github.com/critcl].

[para] Any branch of the repository can be used (if not using the
prebuild starkit or starpack), although the use of the stable branch
[emph master] is recommended.

[para] At the above url is also an explanation on how to build and
install Critcl, including a list of its dependencies.

[para] Its instructions will not be repeated here. If there are
problems with these directions please file a ticket against the
[term Critcl] project, and not Tcllib.

[subsection Tcl]

As we are installing a number of Tcl packages and applications it
should be pretty much obvious that a working installation of Tcl
itself is needed, and I will not belabor the point.

[para] Out of the many possibilities use whatever you are comfortable
with, as long as it provides at the very least Tcl 8.2, or higher.

This may be a Tcl installation provided by your operating system
distribution, from a distribution-independent vendor, or built by
yourself.

[para] [emph Note] that the packages in Tcllib have begun to require
8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use
such packages. Trying to use them will result in
[emph {package not found}] errors, as their package index files will
not register them in versions of the core unable to use them.

[para] Myself, I used (and still use)
[uri http://www.activestate.com ActiveState's]
ActiveTcl 8.5 distribution during development, as I am most familiar
with it.

[para] [emph {(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).}].
I am currently working for SUSE Software Canada ULC, although not in
Tcl-related areas.

[para] This distribution can be found at
[uri http://www.activestate.com/activetcl]. Retrieve the archive of
ActiveTcl 8.5 (or higher) for your platform and install it as directed
by ActiveState.

[para] For those wishing to build and install Tcl on their own, the
relevant sources can be found at

[list_begin definitions]
[def Tcl] [uri http://core.tcl-lang.org/tcl/]
[list_end]

together with the necessary instructions on how to build it.

[para] If there are problems with building, installing, or using Tcl,
please file a ticket against [term Tcl], or the vendor of your
distribution, and [emph not] [term Tcllib].

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) [term Tcl]
packages that provide utility functions useful to a large collection
of Tcl programmers.

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcl_community_communication n 1]
[titledesc {Tcl Community - Kind Communication}]
[description]

The Tcl Community encourages contributions from anyone who wishes to
advance the development of:

[list_begin itemized]
[item] The Tcl Language
[item] Tcl derived languages
[item] Tcl related libraries
[item] Tcl extensions
[item] External Projects that Integrate Tcl
[list_end]

[para] We welcome those contributions from anyone. We are blind to
gender, race, religion, cultural background, cybernetic nature, and
any other demographic characteristics, as well as personal political
views.

[para] A community lives and dies by communications. And occasionally
our communications are peppered with patterns that are harsh,
unfriendly, unwelcoming and/or otherwise unkind. As a volunteer
community, we need all of the help we can get. Therefore, we ask all
contributors to make a conscious effort, in Tcl Community discussions,
to communicate in ways that are welcoming. Ways that are
friendly. Ways that are, in a word: kind.

[para] These guidelines suggest specific ways to accomplish that goal.

[para] Please note: for the balance of this document any reference to
"People", "Persons", "anybody" or "somebody" can refer to any sentient
being, not merely corporeal members of the species Homo Sapien.

[list_begin definitions]

[def {We are a Sanctuary not a Clubhouse}]

The Tcl Community is a collective of amateurs and professionals who
code, test, and use tools. Our community is open to all. There is no
velvet rope. There is no bouncer at the door. There are no secret
handshakes. Any sentient being who enters our midst is welcome. If
someone is ever asked to leave, it is only because they are being
disruptive to the functioning of the community.

[def {We Merit Ideas, Not People}]

A good idea can come from anyone, regardless of how little time they
have been with us. A bad idea can come from anyone, regardless of how
much time or how little time they have been with us. We judge a
concept by how it stands up to scrutiny of logic, implementation, and
regression testing. We don’t judge ideas based on who had the idea
first, who agrees with the idea, or who disagrees with it.

[def {Treat Everyone with Respect}]

Everyone is deserving of respect and courtesy at all times.

[def {Refer to people by the names they use.}]

If grammar requires you to state a gender for a person, honor their
preferences about their gender identity. If you are unsure as to the
gender of an individual, ask. If someone had to guess about your
gender and got it wrong, please correct them and do not take it
personally.

[def {Do not take a harsh tone towards other participants.}]

Do not make personal attacks against anyone (participant or not.)

[para] Criticize statements and actions, never people.

[def {Don’t Take Things Personally}]

When in doubt, assume the best in people. A criticism of your
statements is not a personal attack on you.

[def {Persons, not People}]

Stereotypes are an unhelpful tool on many accounts. They are generally
oversimplified. They are usually flat out wrong. And even if "right"
they are of absolutely no utility in determining the capabilities,
motivations, or fitness of an individual.

[para] Don’t use them in Tcl Community communications.

[def {Mistakes Happen}]

The human condition is a series of trials and errors. Progress is when
we get one more trial than error. Being wrong or making a mistake is
the default state of humanity. Accept the errors of your fellow
sentient beings, and be aware that you are also fallible.

[def {Keep it Real}]

Please respond to what people actually say. We are all amazing
individuals, but none among us are mind readers. If you find yourself
responding to what you imagine someone is thinking, odds are you are
going to be wrong.

[para] If you must criticize someone, stick to things they have
actually done. Never criticize for something you speculate they have
done. Or imagine they have done. Or something someone who shares some
attribute with them has done in the past.

[para] Keep discussions about any non-Tcl subjects to what can be
stated factually and without emotion or judgement.

[def {When Trouble Arises, Don’t Escalate}]

If you feel you are being personally attacked or offended, take the
high road. Punching back in a public forum will only makes things
worse. Address the matter in a private correspondence. Be
polite. Express your feelings, but note that you are expressing your
feelings. When writing, look for a way to calm matters down. And when
in doubt, sleep on your letter before pressing send. And when not in
doubt, sleep on it for another day after that.

[para] If you are a spectator to a fight in progress, politely request
the two parties take the matter to a more private forum.

[def {Always get the Last Word: I’m Sorry}]

If an personal argument does arise, be the first to apologize. An
apology does not concede a logical point. It merely acknowledges that
at some point the discussion left either logic, community decency, or
both. Return to the topic when cooler heads can prevail.

[def {Nobody is Keeping Score}]

There is no prize for being right. There is no cost for being wrong. A
hard sell is not going to advance your idea along any more than a
logical argument. You aren’t running for office. This isn’t debate
club. If you find yourself continuing a discussion beyond where a
topic can be logically discussed, stop.

[def {No Evangelizing}]

The Tcl Community is not the place to promote your chosen operating
system, political outlook, religion, marketing scheme, or economic
model. Period.

[para] (And if you do bring it up, be prepared to have your chosen
topic discussed logically. And odds are, not favorably.)

[def {Respect the Community}]

If the Community has come to a decision on a course of action, please
stop arguing.

[para] If someone complains about how you are expressing your ideas,
listen.

[para] If your words are hurting people, stop. There is no amount of
being "right" that makes up for someone leaving our midst because they
felt insulted, threatened, or ignored.

[list_end]

By following these guidelines, we will build our community, encourage
more contribution to our projects, and our discussions will be
friendlier and reach conclusions more easily.

[para] Thank You.

[section Signatories]
[list_begin itemized]
[item] Sean "the Hypnotoad" Woods
[item] Andreas Kupries
[list_end]

[section Authors]
[list_begin definitions]
[def Primary] Sean "the Hypnotoad" Woods
[def {Light editing}] Andreas Kupries
[list_end]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_devguide n 1]
[titledesc {Tcllib - The Developer's Guide}]
[description]
[include parts/welcome.inc]

[para]

This document is a guide for developers working on Tcllib,
i.e. maintainers fixing bugs, extending the collection's
functionality, etc.

[para]

Please read

[list_begin enum]
[enum] [term {Tcllib - How To Get The Sources}] and
[enum] [term {Tcllib - The Installer's Guide}]
[list_end]

first, if that was not done already.

[para] Here we assume that the sources are already available in a
directory of your choice, and that you not only know how to build and
install them, but also have all the necessary requisites to actually
do so. The guide to the sources in particular also explains which
source code management system is used, where to find it, how to set it
up, etc.

[comment {===================================================================}]
[section Commitments]
[subsection Contributor][include parts/d_contrib.inc]
[subsection Maintainer][include parts/d_maintain.inc]

[comment {===================================================================}]
[section {Branching and Workflow}]
[include parts/d_branchflow.inc]

[comment {===================================================================}]
[section {Structural Overview}]
[include parts/d_dirlayout.inc]

[comment {===================================================================}]
[section {Testsuite Tooling}]
[include parts/d_testing.inc]

[comment {===================================================================}]
[section {Documentation Tooling}]
[include parts/d_documentation.inc]

[comment {===================================================================}]
[section {Notes On Writing A Testsuite}]
[include parts/d_testwrite.inc]

[comment {===================================================================}]
[section {Installation Tooling}]
[include parts/d_installation.inc]

[comment {===================================================================}]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_install_guide n 1]
[titledesc {Tcllib - The Installer's Guide}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is anyone wishing to build and install
the packages found in Tcllib, for either themselves, or others.

[para]

For developers intending to work on the packages themselves we
additionally provide

[list_begin enum]
[enum] [term {Tcllib - The Developer's Guide}].
[list_end]

[para]

Please read [term {Tcllib - How To Get The Sources}] first, if that
was not done already. Here we assume that the sources are already
available in a directory of your choice.

[para]

[comment {===================================================================}]
[section Requisites]

Before Tcllib can be build and used a number of requisites must be installed.

These are:

[list_begin enumerated]
[enum] The scripting language Tcl.
       For details see [sectref Tcl].
[enum] Optionally, the [package critcl] package (C embedding) for [syscmd Tcl].
       For details see [sectref CriTcl].
[list_end]

This list assumes that the machine where Tcllib is to be installed is
essentially clean. Of course, if parts of the dependencies listed
below are already installed the associated steps can be skipped. It is
still recommended to read their sections though, to validate that the
dependencies they talk about are indeed installed.

[include parts/rq_tcl.inc]
[include parts/rq_critcl.inc]

[comment {= build instructions ==============================================}]
[section {Build & Installation Instructions}]

As Tcllib is mainly a bundle of packages written in pure Tcl building
it is the same as installing it. The exceptions to this have their own
subsection, [sectref {Critcl & Accelerators}], later on.

[para] Before that however comes the standard case, differentiated by
       the platforms with material differences in the instruction, i.e.
       [term Unix]-like, versus [term Windows].

[para] Regarding the latter it should also be noted that it is
       possible set up an [term Unix]-like environment using projects
       like [term MSYS], [term Cygwin], and others. In that case the
       user has the choice of which instructions to follow.

[para] Regardless of environment or platform, a suitable [term Tcl]
       has to be installed, and its [syscmd tclsh] should be placed on
       the [variable PATH] ([term Unix]) or associated with
       [file .tcl] files ([term Windows]).

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Installing on Unix}]
[include parts/b_unix.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Installing on Windows}]
[include parts/b_windows.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection {Critcl & Accelerators}]
[include parts/b_critcl.inc]

[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%]
[subsection Tooling]
[include parts/b_tooling.inc]

[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_license n 1]
[titledesc {Tcllib - License}]
[description]
[include parts/welcome.inc]

[para] The collection is under the BSD license.

[section License]

[para]

This software is copyrighted by Ajuba Solutions and other parties.
The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.

[para]

The authors hereby grant permission to use, copy, modify, distribute,
and license this software and its documentation for any purpose,
provided that existing copyright notices are retained in all copies
and that this notice is included verbatim in any distributions. No
written agreement, license, or royalty fee is required for any of the
authorized uses.  Modifications to this software may be copyrighted by
their authors and need not follow the licensing terms described here,
provided that the new terms are clearly indicated on the first page of
each file where they apply.

[para]

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

[para]

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT.  THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

[para]

GOVERNMENT USE: If you are acquiring this software on behalf of the
U.S. government, the Government shall have only "Restricted Rights" in
the software and related documentation as defined in the Federal
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
are acquiring the software on behalf of the Department of Defense, the
software shall be classified as "Commercial Computer Software" and the
Government shall have only "Restricted Rights" as defined in Clause
252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
authors grant the U.S. Government and others acting in its behalf
permission to use and distribute the software in accordance with the
terms specified in this license.

[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_releasemgr n 1]
[titledesc {Tcllib - The Release Manager's Guide}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is the release manager for Tcllib, their
deputies, and anybody else interested in the task of creating
an official release of Tcllib for distribution.

[para]

Please read [term {Tcllib - How To Get The Sources}] first, if that
was not done already. Here we assume that the sources are already
available in a directory of your choice.

[para]

[comment {===================================================================}]
[section Tools]
[include parts/rm_tooling.inc]

[comment {===================================================================}]
[section Tasks]

[comment {===================================================================}]
[subsection {Start a release candidate}]
[include parts/rm_start.inc]

[comment {===================================================================}]
[subsection {Ready the candidate}]
[include parts/rm_work.inc]

[comment {===================================================================}]
[subsection {Make it official}]
[include parts/rm_final.inc]

[comment {===================================================================}]
[subsection {Distribute the release}]
[include parts/rm_distribute.inc]

[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[manpage_begin tcllib_sources n 1]
[titledesc {Tcllib - How To Get The Sources}]
[description]
[include parts/welcome.inc]

[para]

The audience of this document is anyone wishing to either have just a
look at Tcllib's source code, or build the packages, or to extend and
modify them.

[para] For builders and developers we additionally provide

[list_begin enum]
[enum] [term {Tcllib - The Installer's Guide}].
[enum] [term {Tcllib - The Developer's Guide}].
[list_end]

respectively.

[section {Source Location}]

The official repository for Tcllib can be found at
[uri http://core.tcl-lang.org/tcllib]

[section Retrieval]

Assuming that you simply wish to look at the sources, or build a
specific revision, the easiest way of retrieving it is to:

[list_begin enum]
[enum] Log into this site, as "anonymous", using the semi-random password in the captcha.
[enum] Go to the "Timeline".
[enum] Choose the revision you wish to have.
[enum] Follow its link to its detailed information page.
[enum] On that page, choose either the "ZIP" or "Tarball" link to get
a copy of this revision in the format of your choice.
[list_end]

[section {Source Code Management}]

For the curious (or a developer-to-be), the sources are managed by the
[uri http://www.fossil-scm.org {Fossil SCM}].

Binaries for popular platforms can be found directly at its
[uri http://www.fossil-scm.org/download.html {download page}].

[para]

With that tool available the full history can be retrieved via:

[example {
    fossil clone \
	http://core.tcl-lang.org/tcllib \
        tcllib.fossil
}]

followed by

[example {
    mkdir tcllib
    cd tcllib
    fossil open ../tcllib.fossil
}]

to get a checkout of the head of the trunk.

[manpage_end]

<div class='fossil-doc' data-title='Tcl Library Source Code'>

<h1 align="center">Tcl Library Source Code</h1>

<center>

Packages - [Table Of Contents](md/toc.md)
&nbsp;&nbsp;&nbsp;
[Keyword Index](md/index.md)
</center>

<center>
	<form action='../../../docsrch' method='GET'>
	<input type="text" name="s" size="40" autofocus>
	<input type="submit" value="Search Package Documentation">
	</form>
</center>

## Guides to Tcllib

   * [Tcl Community - Kind Communication](md/tcllib/files/devdoc/tcl_community_communication.md)
   * [License](md/tcllib/files/devdoc/tcllib_license.md)
   * [How To Get The Sources](md/tcllib/files/devdoc/tcllib_sources.md)
   * [How To Build And Install Tcllib](md/tcllib/files/devdoc/tcllib_installer.md)
   * [The Developer's Guide](md/tcllib/files/devdoc/tcllib_devguide.md)
   * [The Release Manager's Guide](md/tcllib/files/devdoc/tcllib_releasemgr.md)

## Discussion & Contact

Tcllib has two
[mailing lists](https://sourceforge.net/p/tcllib/mailman/).

One for notifications (commits, ticket changes), the other for general
discussion. These are managed at SourceForge, at the aforementioned

[//000000001]: # (tcl\_community\_communication \- )
[//000000002]: # (Generated from file 'tcl\_community\_communication\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcl\_community\_communication\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcl\_community\_communication \- Tcl Community \- Kind Communication

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Signatories](#section2)

  - [Authors](#section3)

# <a name='description'></a>DESCRIPTION

The Tcl Community encourages contributions from anyone who wishes to advance the
development of:

  - The Tcl Language

  - Tcl derived languages

  - Tcl related libraries

  - Tcl extensions

  - External Projects that Integrate Tcl

We welcome those contributions from anyone\. We are blind to gender, race,
religion, cultural background, cybernetic nature, and any other demographic
characteristics, as well as personal political views\.

A community lives and dies by communications\. And occasionally our
communications are peppered with patterns that are harsh, unfriendly,
unwelcoming and/or otherwise unkind\. As a volunteer community, we need all of
the help we can get\. Therefore, we ask all contributors to make a conscious
effort, in Tcl Community discussions, to communicate in ways that are welcoming\.
Ways that are friendly\. Ways that are, in a word: kind\.

These guidelines suggest specific ways to accomplish that goal\.

Please note: for the balance of this document any reference to "People",
"Persons", "anybody" or "somebody" can refer to any sentient being, not merely
corporeal members of the species Homo Sapien\.

  - We are a Sanctuary not a Clubhouse

    The Tcl Community is a collective of amateurs and professionals who code,
    test, and use tools\. Our community is open to all\. There is no velvet rope\.
    There is no bouncer at the door\. There are no secret handshakes\. Any
    sentient being who enters our midst is welcome\. If someone is ever asked to
    leave, it is only because they are being disruptive to the functioning of
    the community\.

  - We Merit Ideas, Not People

    A good idea can come from anyone, regardless of how little time they have
    been with us\. A bad idea can come from anyone, regardless of how much time
    or how little time they have been with us\. We judge a concept by how it
    stands up to scrutiny of logic, implementation, and regression testing\. We
    don’t judge ideas based on who had the idea first, who agrees with the idea,
    or who disagrees with it\.

  - Treat Everyone with Respect

    Everyone is deserving of respect and courtesy at all times\.

  - Refer to people by the names they use\.

    If grammar requires you to state a gender for a person, honor their
    preferences about their gender identity\. If you are unsure as to the gender
    of an individual, ask\. If someone had to guess about your gender and got it
    wrong, please correct them and do not take it personally\.

  - Do not take a harsh tone towards other participants\.

    Do not make personal attacks against anyone \(participant or not\.\)

    Criticize statements and actions, never people\.

  - Don’t Take Things Personally

    When in doubt, assume the best in people\. A criticism of your statements is
    not a personal attack on you\.

  - Persons, not People

    Stereotypes are an unhelpful tool on many accounts\. They are generally
    oversimplified\. They are usually flat out wrong\. And even if "right" they
    are of absolutely no utility in determining the capabilities, motivations,
    or fitness of an individual\.

    Don’t use them in Tcl Community communications\.

  - Mistakes Happen

    The human condition is a series of trials and errors\. Progress is when we
    get one more trial than error\. Being wrong or making a mistake is the
    default state of humanity\. Accept the errors of your fellow sentient beings,
    and be aware that you are also fallible\.

  - Keep it Real

    Please respond to what people actually say\. We are all amazing individuals,
    but none among us are mind readers\. If you find yourself responding to what
    you imagine someone is thinking, odds are you are going to be wrong\.

    If you must criticize someone, stick to things they have actually done\.
    Never criticize for something you speculate they have done\. Or imagine they
    have done\. Or something someone who shares some attribute with them has done
    in the past\.

    Keep discussions about any non\-Tcl subjects to what can be stated factually
    and without emotion or judgement\.

  - When Trouble Arises, Don’t Escalate

    If you feel you are being personally attacked or offended, take the high
    road\. Punching back in a public forum will only makes things worse\. Address
    the matter in a private correspondence\. Be polite\. Express your feelings,
    but note that you are expressing your feelings\. When writing, look for a way
    to calm matters down\. And when in doubt, sleep on your letter before
    pressing send\. And when not in doubt, sleep on it for another day after
    that\.

    If you are a spectator to a fight in progress, politely request the two
    parties take the matter to a more private forum\.

  - Always get the Last Word: I’m Sorry

    If an personal argument does arise, be the first to apologize\. An apology
    does not concede a logical point\. It merely acknowledges that at some point
    the discussion left either logic, community decency, or both\. Return to the
    topic when cooler heads can prevail\.

  - Nobody is Keeping Score

    There is no prize for being right\. There is no cost for being wrong\. A hard
    sell is not going to advance your idea along any more than a logical
    argument\. You aren’t running for office\. This isn’t debate club\. If you find
    yourself continuing a discussion beyond where a topic can be logically
    discussed, stop\.

  - No Evangelizing

    The Tcl Community is not the place to promote your chosen operating system,
    political outlook, religion, marketing scheme, or economic model\. Period\.

    \(And if you do bring it up, be prepared to have your chosen topic discussed
    logically\. And odds are, not favorably\.\)

  - Respect the Community

    If the Community has come to a decision on a course of action, please stop
    arguing\.

    If someone complains about how you are expressing your ideas, listen\.

    If your words are hurting people, stop\. There is no amount of being "right"
    that makes up for someone leaving our midst because they felt insulted,
    threatened, or ignored\.

By following these guidelines, we will build our community, encourage more
contribution to our projects, and our discussions will be friendlier and reach
conclusions more easily\.

Thank You\.

# <a name='section2'></a>Signatories

  - Sean "the Hypnotoad" Woods

  - Andreas Kupries

# <a name='section3'></a>Authors

  - Primary

    Sean "the Hypnotoad" Woods

  - Light editing

    Andreas Kupries

[//000000001]: # (tcllib\_devguide \- )
[//000000002]: # (Generated from file 'tcllib\_devguide\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_devguide\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_devguide \- Tcllib \- The Developer's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

  - [Commitments](#section2)

      - [Contributor](#subsection1)

      - [Maintainer](#subsection2)

  - [Branching and Workflow](#section3)

      - [Package Dependencies](#subsection3)

      - [Trunk](#subsection4)

      - [Branches](#subsection5)

      - [Working with Branches](#subsection6)

      - [Version numbers](#subsection7)

  - [Structural Overview](#section4)

      - [Main Directories](#subsection8)

      - [More Directories](#subsection9)

      - [Top Files](#subsection10)

      - [File Types](#subsection11)

  - [Testsuite Tooling](#section5)

      - [Invoke the testsuites of a specific module](#subsection12)

      - [Invoke the testsuites of all modules](#subsection13)

      - [Detailed Test Logs](#subsection14)

      - [Shell Selection](#subsection15)

      - [Help](#subsection16)

  - [Documentation Tooling](#section6)

      - [Generate documentation for a specific module](#subsection17)

      - [Generate documentation for all modules](#subsection18)

      - [Available output formats, help](#subsection19)

      - [Validation without output](#subsection20)

  - [Notes On Writing A Testsuite](#section7)

  - [Installation Tooling](#section8)

# <a name='synopsis'></a>SYNOPSIS

[__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*](#1)  
[__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*](#2)  
[__Exclude__ *name*](#3)  

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

This document is a guide for developers working on Tcllib, i\.e\. maintainers
fixing bugs, extending the collection's functionality, etc\.

Please read

  1. *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* and

  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*

first, if that was not done already\.

Here we assume that the sources are already available in a directory of your
choice, and that you not only know how to build and install them, but also have
all the necessary requisites to actually do so\. The guide to the sources in
particular also explains which source code management system is used, where to
find it, how to set it up, etc\.

# <a name='section2'></a>Commitments

## <a name='subsection1'></a>Contributor

As a contributor to Tcllib you are committing yourself to:

  1. keep the guidelines written down in *[Tcl Community \- Kind
     Communication](tcl\_community\_communication\.md)* in your mind\. The main
     point to take away from there is *to be kind to each other*\.

  1. Your contributions getting distributed under a BSD/MIT license\. For the
     details see *[Tcllib \- License](tcllib\_license\.md)*

Contributions are made by entering tickets into our tracker, providing patches,
bundles or branches of code for inclusion, or posting to the Tcllib related
mailing lists\.

## <a name='subsection2'></a>Maintainer

When contributing one or more packages for full inclusion into Tcllib you are
committing yourself to

  1. Keep the guidelines written down in *[Tcl Community \- Kind
     Communication](tcl\_community\_communication\.md)* \(as any contributor\) in
     your mind\. The main point to take away from there is *to be kind to each
     other*\.

  1. Your packages getting distributed under a BSD/MIT license\. For the details
     see *[Tcllib \- License](tcllib\_license\.md)*

  1. Maintenance of the new packages for a period of two years under the
     following rules, and responsibilities:

       1) A maintainer may step down after the mandatory period as they see fit\.

       1) A maintainer may step down before the end of the mandatory period,
          under the condition that a replacement maintainer is immediately
          available and has agreed to serve the remainder of the period, plus
          their own mandatory period \(see below\)\.

       1) When stepping down without a replacement maintainer taking over the
          relevant packages have to be flagged as __unmaintained__\.

       1) When a replacement mantainer is brought in for a package it is \(kept\)
          marked as __maintained__ \(again\)\.

          A replacement maintainer is bound by the same rules as the original
          maintainer, except that the mandatory period of maintenance is
          shortened to one year\.

       1) For any __unmaintained__ package a contributor interested in
          becoming its maintainer can become so by flagging them as
          __maintained__ with their name and contact information, committing
          themselves to the rules of a replacement maintainer \(see previous
          point\)\.

       1) For any already __maintained__ package a contributor interested in
          becoming a co\-maintainer can become so with the agreement of the
          existing maintainer\(s\), committing themselves to the rules of a
          replacement maintainer \(see two points previous\)\.

     The responsibilities as a maintainer include:

       1) Watching Tcllib's ticket tracker for bugs, bug fixes, and feature
          requests related to the new packages\.

       1) Reviewing the aforementioned tickets, rejecting or applying them

       1) Coordination and discussion with ticket submitter during the
          development and/or application of bug fixes\.

  1. Follow the [Branching and Workflow](#section3) of this guide\.

# <a name='section3'></a>Branching and Workflow

## <a name='subsection3'></a>Package Dependencies

Regarding packages and dependencies between them Tcllib occupies a middle
position between two extremes:

  1. On one side a strongly interdependent set of packages, usually by a single
     author, for a single project\. Looking at my \(Andreas Kupries\) own work
     examples of such are [Marpa](https://core\.tcl\.tk/akupries/marpa/index),
     [CRIMP](https://core\.tcl\.tk/akupries/crimp/index),
     [Kinetcl](https://core\.tcl\.tk/akupries/kinetcl/index), etc\.

     For every change the author of the project handles all the modifications
     cascading from any incompatibilities it introduced to the system\.

  1. On the other side, the world of semi\-independent projects by many different
     authors where authors know what packages their own creations depend on, yet
     usually do not know who else depends on them\.

     The best thing an author making an \(incompatible\) change to their project
     can do is to for one announce such changes in some way, and for two use
     versioning to distinguish the code before and after the change\.

     The world is then responsible for adapting, be it by updating their own
     projects to the new version, or by sticking to the old\.

As mentioned already, Tcllib lives in the middle of that\.

While we as maintainers cannot be aware of all users of Tcllib's packages, and
thus have to rely on the mechanisms touched on in point 2 above for that, the
dependencies between the packages contained in Tcllib are a different matter\.

As we are collectively responsible for the usability of Tcllib in toto to the
outside world, it behooves us to be individually mindful even of Tcllib packages
we are not directly maintaining, when they depend on packages under our
maintainership\. This may be as simple as coordinating with the maintainers of
the affected packages\. It may also require us to choose how to adapt affected
packages which do not have maintainers, i\.e\. modify them to use our changed
package properly, or modify them to properly depend on the unchanged version of
our package\.

Note that the above is not only a chore but an opportunity as well\. Additional
insight can be had by forcing ourselves to look at our package and the planned
change\(s\) from an outside perspective, to consider the ramifications of our
actions on others in general, and on dependent packages in particular\.

## <a name='subsection4'></a>Trunk

The management and use of branches is an important part of working with a
*Distributed Version Control System* \(*DVCS*\) like
[fossil](https://www\.fossil\-scm\.org/)\.

For Tcllib the main branch of the collection is *trunk*\. In *git* this
branch would be called *master*, and this is exactly the case in the [github
mirror](https://github\.com/tcltk/tcllib/) of Tcllib\.

To properly support debugging *each commit* on this branch *has to pass the
entire testsuite* of the collection\. Using bisection to determine when an issue
appeared is an example of an action made easier by this constraint\.

This is part of our collective responsibility for the usability of Tcllib in
toto to the outside world\. As *fossil* has no mechanism to enforce this
condition this is handled on the honor system for developers and maintainers\.

To make the task easier Tcllib comes with a tool \("sak\.tcl"\) providing a number
of commands in support\. These commands are explained in the following sections
of this guide\.

While it is possible and allowed to commit directly to trunk remember the above
constraint regarding the testsuite, and the coming notes about other possible
issues with a commit\.

## <a name='subsection5'></a>Branches

Given the constraints placed on the *trunk* branch of the repository it is
\(strongly\) recommended to perform any development going beyond trivial changes
on a non\-trunk branch\.

Outside of the trunk developers are allowed to commit intermediate broken states
of their work\. Only at the end of a development cycle, when the relevant branch
is considered ready for merging, will it be necessary to perform full the set of
validations ensuring that the merge to come will create a good commit on trunk\.

Note that while a review from a second developer is not a required condition for
merging a branch it is recommended to seek out such an independent opinion as a
means of cross\-checking the work\.

It also recommended to give any new branch a name which aids in determining
additional details about it\. Examples of good things to stick into a branch name
would be

  - Developer \(nick\)name

  - Ticket hash/reference

  - One or two keywords applicable to the work

  - \.\.\.

Further, while most development branches are likely quite short\-lived, no
prohibitions exist against making longer\-lived branches\. Creators should however
be mindful that the longer such a branch exists without merges the more
divergent they will tend to be, with an associated increase in the effort which
will have to be spent on either merging from and merging to trunk\.

## <a name='subsection6'></a>Working with Branches

In the hope of engendering good work practices now a few example operations
which will come up with branches, and their associated fossil command
\(sequences\)\.

  - *Awareness*

    When developing we have to keep ourselves aware of the context of our work\.
    On what branch are we ? What files have we changed ? What new files are not
    yet known to the repository ? What has happened remotely since we used our
    checkout ? The answers to these questions become especially important when
    using a long\-lived checkout and coming back to it after some time away\.

    Commands to answer questions like the above are:

      * __fossil pull__

        Get all changes done on the remote since the last pull or sync from it\.
        This has to be done first, before any of the commands below\.

        Even if the commit in our checkout refers to the branch we want right
        now control operations committed to the remote may have changed that
        from underneath us\.

      * __fossil info &#124; grep tags__

      * __fossil branch list &#124; grep '\\\*'__

        Two different ways of determining the branch our checkout is on\.

      * __fossil timeline__

        What have we \(and others\) done recently ?

        *Attention*, this information is very likely outdated, the more the
        longer we did not use this checkout\. Run __fossil pull__ first to
        get latest information from the remote repository of the project\.

      * __fossil timeline current__

        Place the commit our checkout is based on at the top of the timeline\.

      * __fossil changes__

        Lists the files we have changed compared to the commit the checkout is
        based on\.

      * __fossil extra__

        Lists the files we have in the checkout the repository does not know
        about\. This may be leftover chaff from our work, or something we have
        forgotten to __fossil add__ to the repository yet\.

  - *Clean checkouts*

    Be aware of where you are \(see first definition\)\.

    For pretty much all the operation recipes below a clean checkout is at least
    desired, often required\. To check that a checkout is clean invoke

        fossil changes
        fossil extra

    How to clean up when uncommitted changes of all sorts are found is
    context\-specific and outside of the scope of this guide\.

  - *Starting a new branch*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. It is
    *required*\.

    In most situations you want to be on branch *trunk*, and you want to be on
    the latest commit for it\. To get there use

        fossil pull
        fossil update trunk

    If some other branch is desired as the starting point for the coming work
    replace *trunk* in the commands above with the name of that branch\.

    With the base line established we now have two ways of creating the new
    branch, with differing \(dis\)advantages\. The simpler way is to

        fossil branch new NAME_OF_NEW_BRANCH

    and start developing\. The advantage here is that you cannot forget to create
    the branch\. The disadvantages are that we have a branch commit unchanged
    from where we branched from, and that we have to use high\-handed techniques
    like hiding or shunning to get rid of the commit should we decide to abandon
    the work before the first actual commit on the branch\.

    The other way of creating the branch is to start developing, and then on the
    first commit use the option __\-\-branch__ to tell __fossil__ that we
    are starting a branch now\. I\.e\. run

        fossil commit --branch NAME_OF_NEW_BRANCH ...

    where *\.\.\.* are any other options used to supply the commit message, files
    to commit, etc\.

    The \(dis\)advantages are now reversed\.

    We have no superflous commit, only what is actually developed\. The work is
    hidden until we commit to make our first commit\.

    We may forget to use __\-\-branch NAME\_OF\_NEW\_BRANCH__ and then have to
    correct that oversight via the fossil web interface \(I am currently unaware
    of ways of doing such from the command line, although some magic
    incantantion of __fossil tag create__ may work\)\.

    It helps to keep awareness, like checking before any commit that we are on
    the desired branch\.

  - *Merging a branch into trunk*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. In the
    full\-blown sequence \(zig\-zag\) it is *required*, due to the merging from
    trunk\. In the shorter sequence it is only desired\. That said, keeping the
    checkout clean before any major operations is a good habit to have, in my
    opinion\.

    The full\-blown sequencing with checks all the way is to

      1. Validate the checkout, i\.e\. last commit on your branch\. Run the full
         test suite and other validations, fix all the issues which have cropped
         up\.

      1. Merge the latest state of the *trunk* \(see next definition\)\.

      1. Validate the checkout again\. The incoming trunk changes may have broken
         something now\. Do any required fixes\.

      1. Now merge to the trunk using

             fossil update trunk
             fossil merge --integrate YOUR_BRANCH

      1. At this point the checkout should be in the same state as at the end of
         point \(3\) above, because we resolved any issues with the trunk already\.
         Thus a simple

             fossil commit ...

         should be sufficient now to commit the merge back and close the branch
         \(due to the __\-\-integrate__ we used on the merge\)\.

         The more paranoid may validate the checkout a third time before
         commiting\.

    I call this a *zig\-zag merge* because of how the arrows look in the
    timeline, from trunk to feature branch for the first merge, and then back
    for the final merge\.

    A less paranoid can do what I call a *simple merge*, which moves step \(2\)
    after step \(4\) and skips step \(3\) entirely\. The resulting shorter sequence
    is

      1. Validate

      1. Merge to trunk

      1. Validate again

      1. Commit to trunk

    The last step after either zig\-zag or plain merge is to

        fossil sync

    This saves our work to the remote side, and further gives us any other work
    done while we were doing our merge\. It especially allows us to check if we
    raced somebody else, resulting in a split trunk\.

    When that happens we should coordinate with the other developer on who fixes
    the split, to ensure that we do not race each other again\.

  - *Merging from trunk*

    Be aware of where you are \(see first definition\)\.

    Ensure that you have clean checkout \(see second definition\)\. It is
    *required*\.

    In most situations you want to import the latest commit of branch *trunk*
    \(or other origin\)\. To get it use

        fossil pull

    With that done we can now import this commit into our current branch with

        fossil merge trunk

    Even if __fossil__ does not report any conflicts it is a good idea to
    check that the operation has not broken the new and/or changed functionality
    we are working on\.

    With the establishment of a good merge we then save the state with

        fossil commit ...

    before continuing development\.

## <a name='subsection7'></a>Version numbers

In Tcllib all changes to a package have to come with an increment of its version
number\. What part is incremented \(patchlevel, minor, major version\) depends on
the kind of change made\. With multiple changes in a commit the highest "wins"\.

When working in a development branch the version change can be deferred until it
is time to merge, and then has to cover all the changes in the branch\.

Below a list of the kinds of changes and their associated version increments:

  - *D \- documentation*

    No increment

  - *T \- testsuite*

    No increment

  - *B \- bugfix*

    Patchlevel

  - *I \- implementation tweak*

    Patchlevel

  - *P \- performance tweak*

    Patchlevel

  - *E \- backward\-compatible extension*

    Minor

  - *API \- incompatible change*

    Major

Note that a commit containing a version increment has to mention the new version
number in its commit message, as well as the kind of change which caused it\.

Note further that the version number of a package currently exists in three
places\. An increment has to update all of them:

  1. The package implementation\.

  1. The package index \("pkgIndex\.tcl"\)

  1. The package documentation\.

The "sak\.tcl" command __validate version__ helps finding discrepancies
between the first two\. All the other __validate__ methods are also of
interest to any developer\. Invoke it with

    sak.tcl help validate

to see their documentation\.

# <a name='section4'></a>Structural Overview

## <a name='subsection8'></a>Main Directories

The main directories in the Tcllib toplevel directory and of interest to a
developer are:

  - "modules"

    Each child directory represents one or more packages\. In the case of the
    latter the packages are usually related in some way\. Examples are "base64",
    "math", and "struct", with loose \(base64\) to strong \(math\) relations between
    the packages in the directory\.

  - "apps"

    This directory contains all the installable applications, with their
    documentation\. Note that this directory is currently *not* split into
    sub\-directories\.

  - "examples"

    Each child directory "foo" contains one or more example application for the
    packages in "modules/foo"\. These examples are generally not polished enough
    to be considered for installation\.

## <a name='subsection9'></a>More Directories

  - "config"

    This directory contains files supporting the Unix build system, i\.e\.
    "configure" and "Makefile\.in"\.

  - "devdoc"

    This directories contains the doctools sources for the global documentation,
    like this document and its sibling guides\.

  - "embedded"

    This directory contains the entire documentation formatted for
    *[HTML](\.\./\.\./\.\./index\.md\#html)* and styled to properly mix into the
    web site generated by fossil for the repository\.

    This is the documentation accessible from the Tcllib home directory,
    represented in the repository as "embedded/index\.md"\.

  - "idoc"

    This directory contains the entire documentation formatted for
    *[nroff](\.\./\.\./\.\./index\.md\#nroff)* and
    *[HTML](\.\./\.\./\.\./index\.md\#html)*, the latter without any styling\. This
    is the documentation which will be installed\.

  - "support"

    This directory contains the sources of internal packages and utilities used
    in the implementation of the "installer\.tcl" and "sak\.tcl" scripts/tools\.

## <a name='subsection10'></a>Top Files

  - "aclocal\.m4"

  - "configure"

  - "configure\.in"

  - "Makefile\.in"

    These four files comprise the Unix build system layered on top of the
    "installer\.tcl" script\.

  - "installer\.tcl"

    The Tcl\-based installation script/tool\.

  - "project\.shed"

    Configuration file for *Sean Wood*'s
    __[PracTcl](\.\./modules/practcl/practcl\.md)__ buildsystem\.

  - "sak\.tcl"

    This is the main tool for developers and release managers, the *Swiss Army
    Knife* of management operations on the collection\.

  - "ChangeLog"

    The log of changes to the global support, when the sources were held in
    *[CVS](\.\./\.\./\.\./index\.md\#cvs)*\. Not relevant any longer with the
    switch to the *fossil* SCM\.

  - "license\.terms"

    The license in plain ASCII\. See also *[Tcllib \-
    License](tcllib\_license\.md)* for the nicely formatted form\. The text is
    identical\.

  - "README\.md"

  - "\.github/CONTRIBUTING\.md"

  - "\.github/ISSUE\_TEMPLATE\.md"

  - "\.github/PULL\_REQUEST\_TEMPLATE\.md"

    These markdown\-formatted documents are used and shown by the github mirror
    of these sources, pointing people back to the official location and issue
    trackers\.

  - "DESCRIPTION\.txt"

  - "STATUS"

  - "tcllib\.spec"

  - "tcllib\.tap"

  - "tcllib\.yml"

    ????

## <a name='subsection11'></a>File Types

The most common file types, by file extension, are:

  - "\.tcl"

    Tcl code for a package, application, or example\.

  - "\.man"

    Doctools\-formatted documentation, usually for a package\.

  - "\.test"

    Test suite for a package, or part of\. Based on __tcltest__\.

  - "\.bench"

    Performance benchmarks for a package, or part of\. Based on "modules/bench"\.

  - "\.pcx"

    Syntax rules for *TclDevKit*'s __tclchecker__\. Using these rules
    allows the checker to validate the use of commands of a Tcllib package
    __foo__ without having to scan the "\.tcl" files implementing it\.

# <a name='section5'></a>Testsuite Tooling

Testsuites in Tcllib are based on Tcl's standard test package __tcltest__,
plus utilities found in the directory "modules/devtools"

Tcllib developers invoke the suites through the __test run__ method of the
"sak\.tcl" tool, with other methods of __[test](\.\./\.\./\.\./index\.md\#test)__
providing management operations, for example setting a list of standard Tcl
shells to use\.

## <a name='subsection12'></a>Invoke the testsuites of a specific module

Invoke either

    ./sak.tcl test run foo

or

    ./sak.tcl test run modules/foo

to invoke the testsuites found in a specific module "foo"\.

## <a name='subsection13'></a>Invoke the testsuites of all modules

Invoke the tool without a module name, i\.e\.

    ./sak.tcl test run

to invoke the testsuites of all modules\.

## <a name='subsection14'></a>Detailed Test Logs

In all the previous examples the test runner will write a combination of
progress display and testsuite log to the standard output, showing for each
module only the tests that passed or failed and how many of each in a summary at
the end\.

To get a detailed log, it is necessary to invoke the test runner with additional
options\.

For one:

    ./sak.tcl test run --log LOG foo

While this shows the same short log on the terminal as before, it also writes a
detailed log to the file "LOG\.log", and excerpts to other files \("LOG\.summary",
"LOG\.failures", etc\.\)\.

For two:

    ./sak.tcl test run -v foo

This writes the detailed log to the standard output, instead of the short log\.

Regardless of form, the detailed log contains a list of all test cases executed,
which failed, and how they failed \(expected versus actual results\)\.

## <a name='subsection15'></a>Shell Selection

By default the test runner will use all the Tcl shells specified via __test
add__ to invoke the specified testsuites, if any\. If no such are specified it
will fall back to the Tcl shell used to run the tool itself\.

Use option __\-\-shell__ to explicitly specify the Tcl shell to use, like

    ./sak.tcl test run --shell /path/to/tclsh ...

## <a name='subsection16'></a>Help

Invoke the tool as

    ./sak.tcl help test

to see the detailed help for all methods of
__[test](\.\./\.\./\.\./index\.md\#test)__, and the associated options\.

# <a name='section6'></a>Documentation Tooling

The standard format used for documentation of packages and other things in
Tcllib is *[doctools](\.\./\.\./\.\./index\.md\#doctools)*\. Its supporting
packages are a part of Tcllib, see the directories "modules/doctools" and
"modules/dtplite"\. The latter is an application package, with the actual
application "apps/dtplite" a light wrapper around it\.

Tcllib developers gain access to these through the __doc__ method of the
"sak\.tcl" tool, another \(internal\) wrapper around the "modules/dtplite"
application package\.

## <a name='subsection17'></a>Generate documentation for a specific module

Invoke either

    ./sak.tcl doc html foo

or

    ./sak.tcl doc html modules/foo

to generate HTML for the documentation found in the module "foo"\. Instead of
__html__ any other supported format can be used here, of course\.

The generated formatted documentation will be placed into a directory "doc" in
the current working directory\.

## <a name='subsection18'></a>Generate documentation for all modules

Invoke the tool without a module name, i\.e\.

    ./sak.tcl doc html

to generate HTML for the documentation found in all modules\. Instead of
__html__ any other supported format can be used here, of course\.

The generated formatted documentation will be placed into a directory "doc" in
the current working directory\.

## <a name='subsection19'></a>Available output formats, help

Invoke the tool as

    ./sak.tcl help doc

to see the entire set of supported output formats which can be generated\.

## <a name='subsection20'></a>Validation without output

Note the special format __validate__\.

Using this value as the name of the format to generate forces the tool to simply
check that the documentation is syntactically correct, without generating actual
output\.

Invoke it as either

    ./sak.tcl doc validate (modules/)foo

or

    ./sak.tcl doc validate

to either check the packages of a specific module or check all of them\.

# <a name='section7'></a>Notes On Writing A Testsuite

While previous sections talked about running the testsuites for a module and the
packages therein, this has no meaning if the module in question has no
testsuites at all\.

This section gives a very basic overview on possible methodologies for writing
tests and testsuites\.

First there are "drudgery" tests\. Written to check absolutely basic assumptions
which should never fail\.

For example for a command FOO taking two arguments, three tests calling it with
zero, one, and three arguments\. The basic checks that the command fails if it
has not enough arguments, or too many\.

After that come the tests checking things based on our knowledge of the command,
about its properties and assumptions\. Some examples based on the graph
operations added during Google's Summer of Code 2009 are:

  - The BellmanFord command in struct::graph::ops takes a *startnode* as
    argument, and this node should be a node of the graph\. This equals one test
    case checking the behavior when the specified node is not a node of the
    graph\.

    This often gives rise to code in the implementation which explicitly checks
    the assumption and throws an understandable error, instead of letting the
    algorithm fail later in some weird non\-deterministic way\.

    It is not always possible to do such checks\. The graph argument for example
    is just a command in itself, and while we expect it to exhibit a certain
    interface, i\.e\. a set of sub\-commands aka methods, we cannot check that it
    has them, except by actually trying to use them\. That is done by the
    algorithm anyway, so an explicit check is just overhead we can get by
    without\.

  - IIRC one of the distinguishing characteristic of either BellmanFord and/or
    Johnson is that they are able to handle negative weights\. Whereas Dijkstra
    requires positive weights\.

    This induces \(at least\) three testcases \.\.\. Graph with all positive weights,
    all negative, and a mix of positive and negative weights\. Thinking further
    does the algorithm handle the weight __0__ as well ? Another test case,
    or several, if we mix zero with positive and negative weights\.

  - The two algorithms we are currently thinking about are about distances
    between nodes, and distance can be 'Inf'inity, i\.e\. nodes may not be
    connected\. This means that good test cases are

      1. Strongly connected graph

      1. Connected graph

      1. Disconnected graph\.

    At the extremes of strongly connected and disconnected we have the fully
    connected graphs and graphs without edges, only nodes, i\.e\. completely
    disconnected\.

  - IIRC both of the algorithms take weighted arcs, and fill in a default if
    arcs are left unweighted in the input graph\.

    This also induces three test cases:

      1. Graph will all arcs with explicit weights\.

      1. Graph without weights at all\.

      1. Graph with mixture of weighted and unweighted graphs\.

What was described above via examples is called *black\-box* testing\. Test
cases are designed and written based on the developer's knowledge of the
properties of the algorithm and its inputs, without referencing a particular
implementation\.

Going further, a complement to *black\-box* testing is *white\-box*\. For this
we know the implementation of the algorithm, we look at it and design our tests
cases so that they force the code through all possible paths in the
implementation\. Wherever a decision is made we have a test case forcing a
specific direction of the decision, for all possible combinations and
directions\. It is easy to get a combinatorial explosion in the number of needed
test\-cases\.

In practice I often hope that the black\-box tests I have made are enough to
cover all the paths, obviating the need for white\-box tests\.

The above should be enough to make it clear that writing tests for an algorithm
takes at least as much time as coding the algorithm, and often more time\. Much
more time\. See for example also
[http://sqlite\.org/testing\.html](http://sqlite\.org/testing\.html), a writeup
on how the Sqlite database engine is tested\. Another article of interest might
be
[https://www\.researchgate\.net/publication/298896236](https://www\.researchgate\.net/publication/298896236)\.
While geared to a particular numerical algorithm it still shows that even a
simple\-looking algorithm can lead to an incredible number of test cases\.

An interesting connection is to documentation\. In one direction, the properties
checked with black\-box testing are exactly the properties which should be
documented in the algorithm's man page\. And conversely, the documentation of the
properties of an algorithm makes a good reference to base the black\-box tests
on\.

In practice test cases and documentation often get written together,
cross\-influencing each other\. And the actual writing of test cases is a mix of
black and white box, possibly influencing the implementation while writing the
tests\. Like writing a test for a condition like *startnode not in input graph*
serving as reminder to put a check for this condition into the code\.

# <a name='section8'></a>Installation Tooling

A last thing to consider when adding a new package to the collection is
installation\.

How to *use* the "installer\.tcl" script is documented in *[Tcllib \- The
Installer's Guide](tcllib\_installer\.md)*\.

Here we document how to extend said installer so that it may install new
package\(s\) and/or application\(s\)\.

In most cases only a single file has to be modified, the
"support/installation/modules\.tcl" holding one command per module and
application to install\.

The relevant commands are:

  - <a name='1'></a>__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*

    Install the packages of module *name*, found in "modules/*name*"\.

    The *code\-action* is responsible for installing the packages and their
    index\. The system currently provides

      * __\_tcl__

        Copy all "\.tcl" files found in "modules/*name*" into the installation\.

      * __\_tcr__

        As __\_tcl__, copy the "\.tcl" files found in the subdirectories of
        "modules/*name*" as well\.

      * __\_tci__

        As __\_tcl__, and copy the "tclIndex\.tcl" file as well\.

      * __\_msg__

        As __\_tcl__, and copy the subdirectory "msgs" as well\.

      * __\_doc__

        As __\_tcl__, and copy the subdirectory "mpformats" as well\.

      * __\_tex__

        As __\_tcl__, and copy "\.tex" files as well\.

    The *doc\-action* is responsible for installing the package documentation\.
    The system currently provides

      * __\_null__

        No documentation available, do nothing\.

      * __\_man__

        Process the "\.man" files found in "modules/*name*" and install the
        results \(nroff and/or HTML\) in the proper location, as given to the
        installer\.

        This is actually a fallback, normally the installer uses the pre\-made
        formatted documentation found under "idoc"\.

    The *example\-action* is responsible for installing the examples\. The
    system currently provides

      * __\_null__

        No examples available, do nothing\.

      * __\_exa__

        Copy the the directory "examples/*name*" recursively to the install
        location for examples\.

  - <a name='2'></a>__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*

    Install the application with *name*, found in "apps"\.

  - <a name='3'></a>__Exclude__ *name*

    This command signals to the installer which of the listed modules to *not*
    install\. I\.e\. they name the deprecated modules of Tcllib\.

If, and only if the above actions are not suitable for the new module then a
second file has to be modified, "support/installation/actions\.tcl"\.

This file contains the implementations of the available actions, and is the
place where any custom action needed to handle the special circumstances of
module has to be added\.

[//000000001]: # (tcllib\_install\_guide \- )
[//000000002]: # (Generated from file 'tcllib\_installer\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_install\_guide\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_install\_guide \- Tcllib \- The Installer's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Requisites](#section2)

      - [Tcl](#subsection1)

      - [Critcl](#subsection2)

  - [Build & Installation Instructions](#section3)

      - [Installing on Unix](#subsection3)

      - [Installing on Windows](#subsection4)

      - [Critcl & Accelerators](#subsection5)

      - [Tooling](#subsection6)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is anyone wishing to build and install the
packages found in Tcllib, for either themselves, or others\.

For developers intending to work on the packages themselves we additionally
provide

  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.

Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
if that was not done already\. Here we assume that the sources are already
available in a directory of your choice\.

# <a name='section2'></a>Requisites

Before Tcllib can be build and used a number of requisites must be installed\.
These are:

  1. The scripting language Tcl\. For details see [Tcl](#subsection1)\.

  1. Optionally, the __critcl__ package \(C embedding\) for
     __[Tcl](\.\./\.\./\.\./index\.md\#tcl)__\. For details see __CriTcl__\.

This list assumes that the machine where Tcllib is to be installed is
essentially clean\. Of course, if parts of the dependencies listed below are
already installed the associated steps can be skipped\. It is still recommended
to read their sections though, to validate that the dependencies they talk about
are indeed installed\.

## <a name='subsection1'></a>Tcl

As we are installing a number of Tcl packages and applications it should be
pretty much obvious that a working installation of Tcl itself is needed, and I
will not belabor the point\.

Out of the many possibilities use whatever you are comfortable with, as long as
it provides at the very least Tcl 8\.2, or higher\. This may be a Tcl installation
provided by your operating system distribution, from a distribution\-independent
vendor, or built by yourself\.

*Note* that the packages in Tcllib have begun to require 8\.4, 8\.5, and even
8\.6\. Older versions of Tcl will not be able to use such packages\. Trying to use
them will result in *package not found* errors, as their package index files
will not register them in versions of the core unable to use them\.

Myself, I used \(and still use\) [ActiveState's](http://www\.activestate\.com)
ActiveTcl 8\.5 distribution during development, as I am most familiar with it\.

*\(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016,
maintaining ActiveTcl and TclDevKit for them\)\.*\. I am currently working for
SUSE Software Canada ULC, although not in Tcl\-related areas\.

This distribution can be found at
[http://www\.activestate\.com/activetcl](http://www\.activestate\.com/activetcl)\.
Retrieve the archive of ActiveTcl 8\.5 \(or higher\) for your platform and install
it as directed by ActiveState\.

For those wishing to build and install Tcl on their own, the relevant sources
can be found at

  - Tcl

    [http://core\.tcl\-lang\.org/tcl/](http://core\.tcl\-lang\.org/tcl/)

together with the necessary instructions on how to build it\.

If there are problems with building, installing, or using Tcl, please file a
ticket against *[Tcl](\.\./\.\./\.\./index\.md\#tcl)*, or the vendor of your
distribution, and *not* *[Tcllib](\.\./\.\./\.\./index\.md\#tcllib)*\.

## <a name='subsection2'></a>Critcl

The __critcl__ tool is an *optional* dependency\.

It is only required when trying to build the C\-based *accelerators* for a
number of packages, as explained in [Critcl & Accelerators](#subsection5)

Tcllib's build system looks for it in the , using the name __critcl__\. This
is for Unix\. On Windows on the other hand the search is more complex\. First we
look for a proper application __critcl\.exe__\. When that is not found we look
for a combination of interpreter \(__tclkitsh\.exe__, __tclsh\.exe__\) and
starkit \(__critcl\.kit__, __critcl__\) instead\. *Note* that the choice
of starkit can be overriden via the environment variable \.

Tcllib requires Critcl version 2 or higher\.

The github repository providing releases of version 2 and higher, and the
associated sources, can be found at
[http://andreas\-kupries\.github\.com/critcl](http://andreas\-kupries\.github\.com/critcl)\.

Any branch of the repository can be used \(if not using the prebuild starkit or
starpack\), although the use of the stable branch *master* is recommended\.

At the above url is also an explanation on how to build and install Critcl,
including a list of its dependencies\.

Its instructions will not be repeated here\. If there are problems with these
directions please file a ticket against the *Critcl* project, and not Tcllib\.

# <a name='section3'></a>Build & Installation Instructions

As Tcllib is mainly a bundle of packages written in pure Tcl building it is the
same as installing it\. The exceptions to this have their own subsection,
[Critcl & Accelerators](#subsection5), later on\.

Before that however comes the standard case, differentiated by the platforms
with material differences in the instruction, i\.e\. *Unix*\-like, versus
*Windows*\.

Regarding the latter it should also be noted that it is possible set up an
*Unix*\-like environment using projects like *MSYS*, *Cygwin*, and others\.
In that case the user has the choice of which instructions to follow\.

Regardless of environment or platform, a suitable
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* has to be installed, and its __tclsh__
should be placed on the \(*Unix*\) or associated with "\.tcl" files
\(*Windows*\)\.

## <a name='subsection3'></a>Installing on Unix

For *Unix*\-like environments Tcllib comes with the standard set of files to
make

    ./configure
    make install

a suitable way of installing it\. This is a standard non\-interactive install
automatically figuring out where to place everything, i\.e\. packages,
applications, and the manpages\.

To get a graphical installer invoke

    ./installer.tcl

instead\.

## <a name='subsection4'></a>Installing on Windows

In a Windows environment we have the __installer\.tcl__ script to perform
installation\.

If the desired __tclsh__ is associated "\.tcl" files then double\-clicking /
opening the __installer\.tcl__ is enough to invoke it in graphical mode\. This
assumes that *[Tk](\.\./\.\./\.\./index\.md\#tk)* is installed and available as
well\.

Without *[Tk](\.\./\.\./\.\./index\.md\#tk)* the only way to invoke the installer
are to open a DOS window, i\.e\. __cmd\.exe__, and then to invoke

    ./installer.tcl

inside it\.

## <a name='subsection5'></a>Critcl & Accelerators

While the majority of Tcllib consists of packages written in pure Tcl a number
of packages also have *accelerators* associated with them\. These are
__critcl__\-based C packages whose use will boost the performance of the
packages using them\. These accelerators are optional, and they are not installed
by default\.

To build the accelerators the normally optional dependency on __critcl__
becomes required\.

To build and install Tcllib with the accelerators in a Unix\-like environment
invoke:

    ./configure
    make critcl # This builds the shared library holding
                # the accelerators
    make install

The underlying tool is "sak\.tcl" in the toplevel directory of Tcllib and the
command __make critcl__ is just a wrapper around

    ./sak.tcl critcl

Therefore in a Windows environment instead invoke

    ./sak.tcl critcl
    ./installer.tcl

from within a DOS window, i\.e\. __cmd\.exe__\.

## <a name='subsection6'></a>Tooling

The core of Tcllib's build system is the script "installer\.tcl" found in the
toplevel directory of a checkout or release\.

The

    configure ; make install

setup available to developers on Unix\-like systems is just a wrapper around it\.
To go beyond the standard embodied in the wrapper it is necessary to directly
invoke this script\.

On Windows system using it directly is the only way to invoke it\.

For basic help invoke it as

    ./installer.tcl -help

This will print a short list of all the available options to the standard output
channel\.

The commands associated with the various *install* targets in the
*Makefile\.in* for Unix can be used as additional examples on how to use this
tool as well\.

The installer can operate in GUI and CLI modes\. By default it chooses the mode
automatically, based on if the Tcl package
__[Tk](\.\./\.\./\.\./index\.md\#tk)__ can be used or not\. The option
__\-no\-gui__ can be used to force CLI mode\.

Note that it is possible to specify options on the command line even if the
installer ultimatively selects GUI mode\. In that case the hardwired defaults and
the options determine the data presented to the user for editing\.

The installer will select a number of defaults for the locations of packages,
examples, and documentation, and also the format of the documentation\. The user
can overide these defaults in the GUI, or by specifying additional options\. The
defaults depend on the platform detected \(Unix/Windows\) and on the __tclsh__
executable used to run the installer\.

*Options*

  - __\-help__

    Show the list of options explained here on the standard output channel and
    exit\.

  - __\+excluded__

    Include deprecated packages in the installation\.

  - __\-no\-gui__

    Force command line operation of the installer

  - __\-no\-wait__

    In CLI mode the installer will by default ask the user to confirm that the
    chosen configuration \(destination paths, things to install\) is correct
    before performing any action\. Using this option causes the installer to skip
    this query and immediately jump to installation\.

  - __\-app\-path__ *path*

  - __\-example\-path__ *path*

  - __\-html\-path__ *path*

  - __\-nroff\-path__ *path*

  - __\-pkg\-path__ *path*

    Declare the destination paths for the applications, examples, html
    documentation, nroff manpages, and packages\. The defaults are derived from
    the location of the __tclsh__ used to run the installer\.

  - __\-dry\-run__

  - __\-simulate__

    Run the installer without modifying the destination directories\.

  - __\-apps__

  - __\-no\-apps__

  - __\-examples__

  - __\-no\-examples__

  - __\-pkgs__

  - __\-no\-pkgs__

  - __\-html__

  - __\-no\-html__

  - __\-nroff__

  - __\-no\-nroff__

    \(De\)activate the installation of applications, examples, packages, html
    documentation, and nroff manpages\.

    Applications, examples, and packages are installed by default\.

    On Windows the html documentation is installed by default\.

    On Unix the nroff manpages are installed by default\.

[//000000001]: # (tcllib\_license \- )
[//000000002]: # (Generated from file 'tcllib\_license\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_license\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_license \- Tcllib \- License

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [License](#section2)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The collection is under the BSD license\.

# <a name='section2'></a>License

This software is copyrighted by Ajuba Solutions and other parties\. The following
terms apply to all files associated with the software unless explicitly
disclaimed in individual files\.

The authors hereby grant permission to use, copy, modify, distribute, and
license this software and its documentation for any purpose, provided that
existing copyright notices are retained in all copies and that this notice is
included verbatim in any distributions\. No written agreement, license, or
royalty fee is required for any of the authorized uses\. Modifications to this
software may be copyrighted by their authors and need not follow the licensing
terms described here, provided that the new terms are clearly indicated on the
first page of each file where they apply\.

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE
AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\.

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON\-INFRINGEMENT\. THIS SOFTWARE IS PROVIDED ON AN "AS
IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\.

GOVERNMENT USE: If you are acquiring this software on behalf of the U\.S\.
government, the Government shall have only "Restricted Rights" in the software
and related documentation as defined in the Federal Acquisition Regulations
\(FARs\) in Clause 52\.227\.19 \(c\) \(2\)\. If you are acquiring the software on behalf
of the Department of Defense, the software shall be classified as "Commercial
Computer Software" and the Government shall have only "Restricted Rights" as
defined in Clause 252\.227\-7013 \(c\) \(1\) of DFARs\. Notwithstanding the foregoing,
the authors grant the U\.S\. Government and others acting in its behalf permission
to use and distribute the software in accordance with the terms specified in
this license\.

[//000000001]: # (tcllib\_releasemgr \- )
[//000000002]: # (Generated from file 'tcllib\_releasemgr\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_releasemgr\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_releasemgr \- Tcllib \- The Release Manager's Guide

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Tools](#section2)

  - [Tasks](#section3)

      - [Start a release candidate](#subsection1)

      - [Ready the candidate](#subsection2)

      - [Make it official](#subsection3)

      - [Distribute the release](#subsection4)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is the release manager for Tcllib, their deputies,
and anybody else interested in the task of creating an official release of
Tcllib for distribution\.

Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first,
if that was not done already\. Here we assume that the sources are already
available in a directory of your choice\.

# <a name='section2'></a>Tools

The "sak\.tcl" script in the toplevel directory of a Tcllib checkout is the one
tool used by the release manager to perform its [Tasks](#section3)\.

The main commands to be used are

    sak.tcl validate
    sak.tcl test run
    sak.tcl review
    sak.tcl readme
    sak.tcl localdoc
    sak.tcl release

More detail will be provided in the explanations of the various
[Tasks](#section3)\.

# <a name='section3'></a>Tasks

## <a name='subsection1'></a>Start a release candidate

todo: open a candidate for release

## <a name='subsection2'></a>Ready the candidate

todo: test, validate and check that the candidate is worthy of release fix
testsuites, possibly fix packages, documentation regenerate docs coordinate with
package maintainers wrt fixes big thing: going over the packages, classify
changes since last release to generate a nice readme\.

## <a name='subsection3'></a>Make it official

todo: finalize release, make candidate official

## <a name='subsection4'></a>Distribute the release

With the release made it has to be published and the world notified of its
existence\.

  1. Create a proper fossil event for the release, via
     [http://core\.tcl\-lang\.org/tcllib/eventedit](http://core\.tcl\-lang\.org/tcllib/eventedit)\.

     An [existing
     event](http://core\.tcl\-lang\.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817)
     should be used as template\.

  1. Update a number of web locations:

       1) [Home
          page](http://core\.tcl\-lang\.org/tcllib/doc/trunk/embedded/index\.md)

       1) [Downloads](http://core\.tcl\-lang\.org/tcllib/wiki?name=Downloads)

       1) [Past
          Releases](http://core\.tcl\-lang\.org/tcllib/wiki?name=Past\+Releases)

       1) [http://www\.tcl\-lang\.org/home/release\.txt](http://www\.tcl\-lang\.org/home/release\.txt)

       1) [http://www\.tcl\-lang\.org/software/tcllib/\*\.tml](http://www\.tcl\-lang\.org/software/tcllib/\*\.tml)

       1) [http://wiki\.tcl\-lang\.org/page/Tcllib](http://wiki\.tcl\-lang\.org/page/Tcllib)

     The first location maps to the file "embedded/index\.md" in the repository
     itself, as such it can edited as part of the release process\. This is where
     reference to the new fossil event is added, as the new current release\.

     The next two locations are in the fossil tcllib wiki and require admin or
     wiki write permissions for
     [http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)\.

     The last two locations require ssh access to
     [http://www\.tcl\-lang\.org](http://www\.tcl\-lang\.org) and permission to
     edit files in the web area\.

  1. \*\*\*TODO\*\*\* mailing lists and other places to send notes to\.

[//000000001]: # (tcllib\_sources \- )
[//000000002]: # (Generated from file 'tcllib\_sources\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (tcllib\_sources\(n\) 1 tcllib "")

<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../toc.md">Table Of Contents</a> &#124; <a
href="../../../index.md">Keyword Index</a> &#124; <a
href="../../../toc0.md">Categories</a> &#124; <a
href="../../../toc1.md">Modules</a> &#124; <a
href="../../../toc2.md">Applications</a> ] <hr>

# NAME

tcllib\_sources \- Tcllib \- How To Get The Sources

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Description](#section1)

  - [Source Location](#section2)

  - [Retrieval](#section3)

  - [Source Code Management](#section4)

# <a name='description'></a>DESCRIPTION

Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package
itself\. It is a collection of \(semi\-independent\)
*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions
useful to a large collection of Tcl programmers\.

The audience of this document is anyone wishing to either have just a look at
Tcllib's source code, or build the packages, or to extend and modify them\.

For builders and developers we additionally provide

  1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*\.

  1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\.

respectively\.

# <a name='section2'></a>Source Location

The official repository for Tcllib can be found at
[http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)

# <a name='section3'></a>Retrieval

Assuming that you simply wish to look at the sources, or build a specific
revision, the easiest way of retrieving it is to:

  1. Log into this site, as "anonymous", using the semi\-random password in the
     captcha\.

  1. Go to the "Timeline"\.

  1. Choose the revision you wish to have\.

  1. Follow its link to its detailed information page\.

  1. On that page, choose either the "ZIP" or "Tarball" link to get a copy of
     this revision in the format of your choice\.

# <a name='section4'></a>Source Code Management

For the curious \(or a developer\-to\-be\), the sources are managed by the [Fossil
SCM](http://www\.fossil\-scm\.org)\. Binaries for popular platforms can be found
directly at its [download page](http://www\.fossil\-scm\.org/download\.html)\.

With that tool available the full history can be retrieved via:

    fossil clone  http://core.tcl-lang.org/tcllib  tcllib.fossil

followed by

    mkdir tcllib
    cd tcllib
    fossil open ../tcllib.fossil

to get a checkout of the head of the trunk\.

    [keywords {doctools language}]
    [keywords {doctools markup}]
    [keywords {doctools syntax}]
    [keywords markup]
    [keywords {semantic markup}]
        [description]
        [vset CATEGORY doctools]
    [include ../common-text/feedback.inc]
    [manpage_end]

This also shows us that all doctools documents are split into two parts, the
*header* and the *body*\. Everything coming before \[__description__\]
belongs to the header, and everything coming after belongs to the body, with the
whole document bracketed by the two __manpage\_\*__ commands\. Before and after
these opening and closing commands we have only *whitespace*\.

Remember that the whitespace is optional\. The document

        [manpage_begin NAME SECTION VERSION]
        [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
        [require PACKAGE VERSION][require PACKAGE][description]
        [vset CATEGORY doctools]
    [include ../common-text/feedback.inc]
    [manpage_end]

has the same meaning as the example before\.

On the other hand, if *whitespace* is present it consists not only of any
sequence of characters containing the space character, horizontal and vertical
tabs, carriage return, and newline, but it may contain comment markup as well,

  - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption

  - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal

  - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression

  - [tcl\_community\_communication](tcllib/files/devdoc/tcl\_community\_communication\.md) Tcl Community \- Kind Communication

  - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers

  - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers

  - [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor

  - [tcllib\_devguide](tcllib/files/devdoc/tcllib\_devguide\.md) Tcllib \- The Developer's Guide

  - [tcllib\_install\_guide](tcllib/files/devdoc/tcllib\_installer\.md) Tcllib \- The Installer's Guide

  - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation

  - [tcllib\_license](tcllib/files/devdoc/tcllib\_license\.md) Tcllib \- License

  - [tcllib\_releasemgr](tcllib/files/devdoc/tcllib\_releasemgr\.md) Tcllib \- The Release Manager's Guide

  - [tcllib\_sources](tcllib/files/devdoc/tcllib\_sources\.md) Tcllib \- How To Get The Sources

  - [tclrep/machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\.

  - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

  - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual

  - [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual

'\"
'\" Generated from file 'tcl_community_communication\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "tcl_community_communication" n 1 tcllib ""
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tcl_community_communication \- Tcl Community - Kind Communication
.SH DESCRIPTION
The Tcl Community encourages contributions from anyone who wishes to
advance the development of:
.IP \(bu
The Tcl Language
.IP \(bu
Tcl derived languages
.IP \(bu
Tcl related libraries
.IP \(bu
Tcl extensions
.IP \(bu
External Projects that Integrate Tcl
.PP
.PP
We welcome those contributions from anyone\&. We are blind to
gender, race, religion, cultural background, cybernetic nature, and
any other demographic characteristics, as well as personal political
views\&.
.PP
A community lives and dies by communications\&. And occasionally
our communications are peppered with patterns that are harsh,
unfriendly, unwelcoming and/or otherwise unkind\&. As a volunteer
community, we need all of the help we can get\&. Therefore, we ask all
contributors to make a conscious effort, in Tcl Community discussions,
to communicate in ways that are welcoming\&. Ways that are
friendly\&. Ways that are, in a word: kind\&.
.PP
These guidelines suggest specific ways to accomplish that goal\&.
.PP
Please note: for the balance of this document any reference to
"People", "Persons", "anybody" or "somebody" can refer to any sentient
being, not merely corporeal members of the species Homo Sapien\&.
.TP
We are a Sanctuary not a Clubhouse
The Tcl Community is a collective of amateurs and professionals who
code, test, and use tools\&. Our community is open to all\&. There is no
velvet rope\&. There is no bouncer at the door\&. There are no secret
handshakes\&. Any sentient being who enters our midst is welcome\&. If
someone is ever asked to leave, it is only because they are being
disruptive to the functioning of the community\&.
.TP
We Merit Ideas, Not People
A good idea can come from anyone, regardless of how little time they
have been with us\&. A bad idea can come from anyone, regardless of how
much time or how little time they have been with us\&. We judge a
concept by how it stands up to scrutiny of logic, implementation, and
regression testing\&. We don’t judge ideas based on who had the idea
first, who agrees with the idea, or who disagrees with it\&.
.TP
Treat Everyone with Respect
Everyone is deserving of respect and courtesy at all times\&.
.TP
Refer to people by the names they use\&.
If grammar requires you to state a gender for a person, honor their
preferences about their gender identity\&. If you are unsure as to the
gender of an individual, ask\&. If someone had to guess about your
gender and got it wrong, please correct them and do not take it
personally\&.
.TP
Do not take a harsh tone towards other participants\&.
Do not make personal attacks against anyone (participant or not\&.)
.sp
Criticize statements and actions, never people\&.
.TP
Don’t Take Things Personally
When in doubt, assume the best in people\&. A criticism of your
statements is not a personal attack on you\&.
.TP
Persons, not People
Stereotypes are an unhelpful tool on many accounts\&. They are generally
oversimplified\&. They are usually flat out wrong\&. And even if "right"
they are of absolutely no utility in determining the capabilities,
motivations, or fitness of an individual\&.
.sp
Don’t use them in Tcl Community communications\&.
.TP
Mistakes Happen
The human condition is a series of trials and errors\&. Progress is when
we get one more trial than error\&. Being wrong or making a mistake is
the default state of humanity\&. Accept the errors of your fellow
sentient beings, and be aware that you are also fallible\&.
.TP
Keep it Real
Please respond to what people actually say\&. We are all amazing
individuals, but none among us are mind readers\&. If you find yourself
responding to what you imagine someone is thinking, odds are you are
going to be wrong\&.
.sp
If you must criticize someone, stick to things they have
actually done\&. Never criticize for something you speculate they have
done\&. Or imagine they have done\&. Or something someone who shares some
attribute with them has done in the past\&.
.sp
Keep discussions about any non-Tcl subjects to what can be
stated factually and without emotion or judgement\&.
.TP
When Trouble Arises, Don’t Escalate
If you feel you are being personally attacked or offended, take the
high road\&. Punching back in a public forum will only makes things
worse\&. Address the matter in a private correspondence\&. Be
polite\&. Express your feelings, but note that you are expressing your
feelings\&. When writing, look for a way to calm matters down\&. And when
in doubt, sleep on your letter before pressing send\&. And when not in
doubt, sleep on it for another day after that\&.
.sp
If you are a spectator to a fight in progress, politely request
the two parties take the matter to a more private forum\&.
.TP
Always get the Last Word: I’m Sorry
If an personal argument does arise, be the first to apologize\&. An
apology does not concede a logical point\&. It merely acknowledges that
at some point the discussion left either logic, community decency, or
both\&. Return to the topic when cooler heads can prevail\&.
.TP
Nobody is Keeping Score
There is no prize for being right\&. There is no cost for being wrong\&. A
hard sell is not going to advance your idea along any more than a
logical argument\&. You aren’t running for office\&. This isn’t debate
club\&. If you find yourself continuing a discussion beyond where a
topic can be logically discussed, stop\&.
.TP
No Evangelizing
The Tcl Community is not the place to promote your chosen operating
system, political outlook, religion, marketing scheme, or economic
model\&. Period\&.
.sp
(And if you do bring it up, be prepared to have your chosen
topic discussed logically\&. And odds are, not favorably\&.)
.TP
Respect the Community
If the Community has come to a decision on a course of action, please
stop arguing\&.
.sp
If someone complains about how you are expressing your ideas,
listen\&.
.sp
If your words are hurting people, stop\&. There is no amount of
being "right" that makes up for someone leaving our midst because they
felt insulted, threatened, or ignored\&.
.PP
By following these guidelines, we will build our community, encourage
more contribution to our projects, and our discussions will be
friendlier and reach conclusions more easily\&.
.PP
Thank You\&.
.SH SIGNATORIES
.IP \(bu
Sean "the Hypnotoad" Woods
.IP \(bu
Andreas Kupries
.PP
.SH AUTHORS
.TP
Primary
Sean "the Hypnotoad" Woods
.TP
Light editing
Andreas Kupries
.PP

'\"
'\" Generated from file 'tcllib_devguide\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "tcllib_devguide" n 1 tcllib ""
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tcllib_devguide \- Tcllib - The Developer's Guide
.SH SYNOPSIS
\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
.sp
\fBApplication\fR \fIname\fR
.sp
\fBExclude\fR \fIname\fR
.sp
.BE
.SH DESCRIPTION
Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a
package itself\&. It is a collection of (semi-independent) \fITcl\fR
packages that provide utility functions useful to a large collection
of Tcl programmers\&.
.PP
This document is a guide for developers working on Tcllib,
i\&.e\&. maintainers fixing bugs, extending the collection's
functionality, etc\&.
.PP
Please read
.IP [1]
\fITcllib - How To Get The Sources\fR and
.IP [2]
\fITcllib - The Installer's Guide\fR
.PP
first, if that was not done already\&.
.PP
Here we assume that the sources are already available in a
directory of your choice, and that you not only know how to build and
install them, but also have all the necessary requisites to actually
do so\&. The guide to the sources in particular also explains which
source code management system is used, where to find it, how to set it
up, etc\&.
.SH COMMITMENTS
.SS CONTRIBUTOR
As a contributor to Tcllib you are committing yourself to:
.IP [1]
keep the guidelines written down in
\fITcl Community - Kind Communication\fR in your mind\&.
The main point to take away from there is
\fIto be kind to each other\fR\&.
.IP [2]
Your contributions getting distributed under a BSD/MIT license\&.
For the details see \fITcllib - License\fR
.PP
Contributions are made by entering tickets into our tracker, providing
patches, bundles or branches of code for inclusion, or posting to the
Tcllib related mailing lists\&.
.SS MAINTAINER
When contributing one or more packages for full inclusion into Tcllib
you are committing yourself to
.IP [1]
Keep the guidelines written down in
\fITcl Community - Kind Communication\fR
(as any contributor) in your mind\&. The main point to take away
from there is \fIto be kind to each other\fR\&.
.IP [2]
Your packages getting distributed under a BSD/MIT license\&.  For
the details see \fITcllib - License\fR
.IP [3]
Maintenance of the new packages for a period of two years under
the following rules, and responsibilities:
.RS
.IP [1]
A maintainer may step down after the mandatory period as
they see fit\&.
.IP [2]
A maintainer may step down before the end of the
mandatory period, under the condition that a replacement
maintainer is immediately available and has agreed to
serve the remainder of the period, plus their own
mandatory period (see below)\&.
.IP [3]
When stepping down without a replacement maintainer
taking over the relevant packages have to be flagged as
\fBunmaintained\fR\&.
.IP [4]
When a replacement mantainer is brought in for a package
it is (kept) marked as \fBmaintained\fR (again)\&.
.sp
A replacement maintainer is bound by the same rules as
the original maintainer, except that the mandatory
period of maintenance is shortened to one year\&.
.IP [5]
For any \fBunmaintained\fR package a contributor
interested in becoming its maintainer can become so by
flagging them as \fBmaintained\fR with their name and
contact information, committing themselves to the rules
of a replacement maintainer (see previous point)\&.
.IP [6]
For any already \fBmaintained\fR package a contributor
interested in becoming a co-maintainer can become so
with the agreement of the existing maintainer(s),
committing themselves to the rules of a replacement
maintainer (see two points previous)\&.
.RE
.sp
The responsibilities as a maintainer include:
.RS
.IP [1]
Watching Tcllib's ticket tracker for bugs, bug fixes,
and feature requests related to the new packages\&.
.IP [2]
Reviewing the aforementioned tickets, rejecting or
applying them
.IP [3]
Coordination and discussion with ticket submitter during
the development and/or application of bug fixes\&.
.RE
.IP [4]
Follow the \fBBranching and Workflow\fR of this guide\&.
.PP
.SH "BRANCHING AND WORKFLOW"
.SS "PACKAGE DEPENDENCIES"
Regarding packages and dependencies between them Tcllib occupies a
middle position between two extremes:
.IP [1]
On one side a strongly interdependent set of packages, usually
by a single author, for a single project\&. Looking at my
(Andreas Kupries) own work examples of such are
\fIMarpa\fR [https://core\&.tcl\&.tk/akupries/marpa/index],
\fICRIMP\fR [https://core\&.tcl\&.tk/akupries/crimp/index],
\fIKinetcl\fR [https://core\&.tcl\&.tk/akupries/kinetcl/index], etc\&.
.sp
For every change the author of the project handles all the
modifications cascading from any incompatibilities it
introduced to the system\&.
.IP [2]
On the other side, the world of semi-independent projects by
many different authors where authors know what packages their
own creations depend on, yet usually do not know who else
depends on them\&.
.sp
The best thing an author making an (incompatible) change to
their project can do is to for one announce such changes in
some way, and for two use versioning to distinguish the code
before and after the change\&.
.sp
The world is then responsible for adapting, be it by updating
their own projects to the new version, or by sticking to the
old\&.
.PP
As mentioned already, Tcllib lives in the middle of that\&.
.PP
While we as maintainers cannot be aware of all users of
Tcllib's packages, and thus have to rely on the mechanisms
touched on in point 2 above for that, the dependencies between
the packages contained in Tcllib are a different matter\&.
.PP
As we are collectively responsible for the usability of Tcllib
in toto to the outside world, it behooves us to be individually
mindful even of Tcllib packages we are not directly
maintaining, when they depend on packages under our
maintainership\&.
This may be as simple as coordinating with the maintainers of
the affected packages\&.
It may also require us to choose how to adapt affected packages
which do not have maintainers, i\&.e\&. modify them to use our
changed package properly, or modify them to properly depend on
the unchanged version of our package\&.
.PP
Note that the above is not only a chore but an opportunity as
well\&.
Additional insight can be had by forcing ourselves to look at
our package and the planned change(s) from an outside
perspective, to consider the ramifications of our actions on
others in general, and on dependent packages in particular\&.
.SS TRUNK
The management and use of branches is an important part of working
with a \fIDistributed Version Control System\fR (\fIDVCS\fR) like
\fIfossil\fR [https://www\&.fossil-scm\&.org/]\&.
.PP
For Tcllib the main branch of the collection is
\fItrunk\fR\&. In \fIgit\fR this branch would be called
\fImaster\fR, and this is exactly the case in the
\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of
Tcllib\&.
.PP
To properly support debugging \fIeach commit\fR on this
branch \fIhas to pass the entire testsuite\fR of the
collection\&. Using bisection to determine when an issue appeared
is an example of an action made easier by this constraint\&.
.PP
This is part of our collective responsibility for the usability
of Tcllib in toto to the outside world\&.
As \fIfossil\fR has no mechanism to enforce this condition
this is handled on the honor system for developers and maintainers\&.
.PP
To make the task easier Tcllib comes with a tool
("\fIsak\&.tcl\fR") providing a number of commands in
support\&. These commands are explained in the following sections
of this guide\&.
.PP
While it is possible and allowed to commit directly to trunk
remember the above constraint regarding the testsuite, and the
coming notes about other possible issues with a commit\&.
.SS BRANCHES
Given the constraints placed on the \fItrunk\fR branch of the
repository it is (strongly) recommended to perform any development
going beyond trivial changes on a non-trunk branch\&.
.PP
Outside of the trunk developers are allowed to commit
intermediate broken states of their work\&.
Only at the end of a development cycle, when the relevant
branch is considered ready for merging, will it be necessary to
perform full the set of validations ensuring that the merge to
come will create a good commit on trunk\&.
.PP
Note that while a review from a second developer is not a
required condition for merging a branch it is recommended to
seek out such an independent opinion as a means of
cross-checking the work\&.
.PP
It also recommended to give any new branch a name which aids in
determining additional details about it\&. Examples of good
things to stick into a branch name would be
.IP \(bu
Developer (nick)name
.IP \(bu
Ticket hash/reference
.IP \(bu
One or two keywords applicable to the work
.IP \(bu
\&.\&.\&.
.PP
.PP
Further, while most development branches are likely quite
short-lived, no prohibitions exist against making longer-lived
branches\&.
Creators should however be mindful that the longer such a
branch exists without merges the more divergent they will tend
to be, with an associated increase in the effort which will
have to be spent on either merging from and merging to trunk\&.
.SS "WORKING WITH BRANCHES"
In the hope of engendering good work practices now a few example
operations which will come up with branches, and their associated
fossil command (sequences)\&.
.TP
\fIAwareness\fR
When developing we have to keep ourselves aware of the context of our
work\&. On what branch are we ? What files have we changed ? What new
files are not yet known to the repository ? What has happened remotely
since we used our checkout ?
The answers to these questions become especially important when using
a long-lived checkout and coming back to it after some time away\&.
.sp
Commands to answer questions like the above are:
.RS
.TP
\fBfossil pull\fR
Get all changes done on the remote since the last pull or sync
from it\&. This has to be done first, before any of the commands
below\&.
.sp
Even if the commit in our checkout refers to the branch we want
right now control operations committed to the remote may have
changed that from underneath us\&.
.TP
\fBfossil info | grep tags\fR
.TP
\fBfossil branch list | grep '\\*'\fR
Two different ways of determining the branch our checkout is
on\&.
.TP
\fBfossil timeline\fR
What have we (and others) done recently ?
.sp
\fIAttention\fR, this information is very likely outdated, the
more the longer we did not use this checkout\&.
Run \fBfossil pull\fR first to get latest information from
the remote repository of the project\&.
.TP
\fBfossil timeline current\fR
Place the commit our checkout is based on at the top of the
timeline\&.
.TP
\fBfossil changes\fR
Lists the files we have changed compared to the commit the
checkout is based on\&.
.TP
\fBfossil extra\fR
Lists the files we have in the checkout the repository does not
know about\&. This may be leftover chaff from our work, or
something we have forgotten to \fBfossil add\fR to the
repository yet\&.
.RE
.TP
\fIClean checkouts\fR
Be aware of where you are (see first definition)\&.
.sp
For pretty much all the operation recipes below a clean
checkout is at least desired, often required\&.
To check that a checkout is clean invoke
.CS


    fossil changes
    fossil extra

.CE
.IP
How to clean up when uncommitted changes of all sorts are found is
context-specific and outside of the scope of this guide\&.
.TP
\fIStarting a new branch\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
It is \fIrequired\fR\&.
.sp
In most situations you want to be on branch \fItrunk\fR, and
you want to be on the latest commit for it\&. To get there use
.CS


    fossil pull
    fossil update trunk

.CE
.IP
If some other branch is desired as the starting point for the coming
work replace \fItrunk\fR in the commands above with the name of that
branch\&.
.sp
With the base line established we now have two ways of creating
the new branch, with differing (dis)advantages\&.
The simpler way is to
.CS


    fossil branch new NAME_OF_NEW_BRANCH

.CE
.IP
and start developing\&. The advantage here is that you cannot forget to
create the branch\&. The disadvantages are that we have a branch commit
unchanged from where we branched from, and that we have to use
high-handed techniques like hiding or shunning to get rid of the
commit should we decide to abandon the work before the first actual
commit on the branch\&.
.sp
The other way of creating the branch is to start developing,
and then on the first commit use the option \fB--branch\fR to tell
\fBfossil\fR that we are starting a branch now\&. I\&.e\&. run
.CS


    fossil commit --branch NAME_OF_NEW_BRANCH \&.\&.\&.

.CE
.IP
where \fI\&.\&.\&.\fR are any other options used to supply the commit
message, files to commit, etc\&.
.sp
The (dis)advantages are now reversed\&.
.sp
We have no superflous commit, only what is actually
developed\&. The work is hidden until we commit to make our first
commit\&.
.sp
We may forget to use \fB--branch NAME_OF_NEW_BRANCH\fR and
then have to correct that oversight via the fossil web
interface (I am currently unaware of ways of doing such from
the command line, although some magic incantantion of
\fBfossil tag create\fR may work)\&.
.sp
It helps to keep awareness, like checking before any commit
that we are on the desired branch\&.
.TP
\fIMerging a branch into trunk\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
In the full-blown sequence (zig-zag) it is \fIrequired\fR, due
to the merging from trunk\&. In the shorter sequence it is only
desired\&. That said, keeping the checkout clean before
any major operations is a good habit to have, in my opinion\&.
.sp
The full-blown sequencing with checks all the way is to
.RS
.IP [1]
Validate the checkout, i\&.e\&. last commit on your branch\&. Run the
full test suite and other validations, fix all the issues which
have cropped up\&.
.IP [2]
Merge the latest state of the \fItrunk\fR (see next definition)\&.
.IP [3]
Validate the checkout again\&. The incoming trunk changes may
have broken something now\&. Do any required fixes\&.
.IP [4]
Now merge to the trunk using
.CS


    fossil update trunk
    fossil merge --integrate YOUR_BRANCH

.CE
.IP [5]
At this point the checkout should be in the same state as at
the end of point (3) above, because we resolved any issues with
the trunk already\&. Thus a simple
.CS


    fossil commit \&.\&.\&.

.CE
.IP
should be sufficient now to commit the merge back and close the
branch (due to the \fB--integrate\fR we used on the merge)\&.
.sp
The more paranoid may validate the checkout a third time before
commiting\&.
.RE
.sp
I call this a \fIzig-zag merge\fR because of how the arrows
look in the timeline, from trunk to feature branch for the
first merge, and then back for the final merge\&.
.sp
A less paranoid can do what I call a \fIsimple merge\fR,
which moves step (2) after step (4) and skips step (3)
entirely\&. The resulting shorter sequence is
.RS
.IP [1]
Validate
.IP [2]
Merge to trunk
.IP [3]
Validate again
.IP [4]
Commit to trunk
.RE
.IP
The last step after either zig-zag or plain merge is to
.CS


    fossil sync

.CE
.IP
This saves our work to the remote side, and further gives us any other
work done while we were doing our merge\&. It especially allows us to
check if we raced somebody else, resulting in a split trunk\&.
.sp
When that happens we should coordinate with the other developer
on who fixes the split, to ensure that we do not race each
other again\&.
.TP
\fIMerging from trunk\fR
Be aware of where you are (see first definition)\&.
.sp
Ensure that you have clean checkout (see second definition)\&.
It is \fIrequired\fR\&.
.sp
In most situations you want to import the latest commit of
branch \fItrunk\fR (or other origin)\&. To get it use
.CS


    fossil pull

.CE
.sp
With that done we can now import this commit into our current
branch with
.CS


    fossil merge trunk

.CE
.sp
Even if \fBfossil\fR does not report any conflicts it is a
good idea to check that the operation has not broken the new
and/or changed functionality we are working on\&.
.sp
With the establishment of a good merge we then save the state
with
.CS


    fossil commit \&.\&.\&.

.CE
.IP
before continuing development\&.
.PP
.SS "VERSION NUMBERS"
In Tcllib all changes to a package have to come with an increment of
its version number\&. What part is incremented (patchlevel, minor, major
version) depends on the kind of change made\&. With multiple changes in
a commit the highest "wins"\&.
.PP
When working in a development branch the version change can be
deferred until it is time to merge, and then has to cover all
the changes in the branch\&.
.PP
Below a list of the kinds of changes and their associated
version increments:
.TP
\fID - documentation\fR
No increment
.TP
\fIT - testsuite\fR
No increment
.TP
\fIB - bugfix\fR
Patchlevel
.TP
\fII - implementation tweak\fR
Patchlevel
.TP
\fIP - performance tweak\fR
Patchlevel
.TP
\fIE - backward-compatible extension\fR
Minor
.TP
\fIAPI - incompatible change\fR
Major
.PP
.PP
Note that a commit containing a version increment has to
mention the new version number in its commit message, as well
as the kind of change which caused it\&.
.PP
Note further that the version number of a package currently
exists in three places\&. An increment has to update all of them:
.IP [1]
The package implementation\&.
.IP [2]
The package index ("\fIpkgIndex\&.tcl\fR")
.IP [3]
The package documentation\&.
.PP
.PP
The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps
finding discrepancies between the first two\&.
All the other \fBvalidate\fR methods are also of interest to
any developer\&. Invoke it with
.CS

 sak\&.tcl help validate
.CE
to see their documentation\&.
.SH "STRUCTURAL OVERVIEW"
.SS "MAIN DIRECTORIES"
The main directories in the Tcllib toplevel directory and of interest
to a developer are:
.TP
"\fImodules\fR"
Each child directory represents one or more packages\&.
In the case of the latter the packages are usually related in some
way\&. Examples are "\fIbase64\fR", "\fImath\fR", and "\fIstruct\fR", with
loose (base64) to strong (math) relations between the packages in the
directory\&.
.TP
"\fIapps\fR"
This directory contains all the installable applications, with their
documentation\&. Note that this directory is currently \fInot\fR split
into sub-directories\&.
.TP
"\fIexamples\fR"
Each child directory "\fIfoo\fR" contains one or more example
application for the packages in "\fImodules/foo\fR"\&. These examples are
generally not polished enough to be considered for installation\&.
.PP
.SS "MORE DIRECTORIES"
.TP
"\fIconfig\fR"
This directory contains files supporting the Unix build system,
i\&.e\&. "\fIconfigure\fR" and "\fIMakefile\&.in\fR"\&.
.TP
"\fIdevdoc\fR"
This directories contains the doctools sources for the global
documentation, like this document and its sibling guides\&.
.TP
"\fIembedded\fR"
This directory contains the entire documentation formatted for
\fIHTML\fR and styled to properly mix into the web site generated by
fossil for the repository\&.
.sp
This is the documentation accessible from the Tcllib home
directory, represented in the repository as "\fIembedded/index\&.md\fR"\&.
.TP
"\fIidoc\fR"
This directory contains the entire documentation formatted for
\fInroff\fR and \fIHTML\fR, the latter without any styling\&.
This is the documentation which will be installed\&.
.TP
"\fIsupport\fR"
This directory contains the sources of internal packages and utilities
used in the implementation of the "\fIinstaller\&.tcl\fR" and
"\fIsak\&.tcl\fR" scripts/tools\&.
.PP
.SS "TOP FILES"
.TP
"\fIaclocal\&.m4\fR"
.TP
"\fIconfigure\fR"
.TP
"\fIconfigure\&.in\fR"
.TP
"\fIMakefile\&.in\fR"
These four files comprise the Unix build system layered on top of the
"\fIinstaller\&.tcl\fR" script\&.
.TP
"\fIinstaller\&.tcl\fR"
The Tcl-based installation script/tool\&.
.TP
"\fIproject\&.shed\fR"
Configuration file for \fISean Wood\fR's \fBPracTcl\fR
buildsystem\&.
.TP
"\fIsak\&.tcl\fR"
This is the main tool for developers and release managers, the
\fISwiss Army Knife\fR of management operations on the collection\&.
.TP
"\fIChangeLog\fR"
The log of changes to the global support, when the sources were held
in \fICVS\fR\&. Not relevant any longer with the switch to the
\fIfossil\fR SCM\&.
.TP
"\fIlicense\&.terms\fR"
The license in plain ASCII\&. See also \fITcllib - License\fR for the
nicely formatted form\&. The text is identical\&.
.TP
"\fIREADME\&.md\fR"
.TP
"\fI\&.github/CONTRIBUTING\&.md\fR"
.TP
"\fI\&.github/ISSUE_TEMPLATE\&.md\fR"
.TP
"\fI\&.github/PULL_REQUEST_TEMPLATE\&.md\fR"
These markdown-formatted documents are used and shown by the github
mirror of these sources, pointing people back to the official location
and issue trackers\&.
.TP
"\fIDESCRIPTION\&.txt\fR"
.TP
"\fISTATUS\fR"
.TP
"\fItcllib\&.spec\fR"
.TP
"\fItcllib\&.tap\fR"
.TP
"\fItcllib\&.yml\fR"
????
.PP
.SS "FILE TYPES"
The most common file types, by file extension, are:
.TP
"\fI\&.tcl\fR"
Tcl code for a package, application, or example\&.
.TP
"\fI\&.man\fR"
Doctools-formatted documentation, usually for a package\&.
.TP
"\fI\&.test\fR"
Test suite for a package, or part of\&.
Based on \fBtcltest\fR\&.
.TP
"\fI\&.bench\fR"
Performance benchmarks for a package, or part of\&.
Based on "\fImodules/bench\fR"\&.
.TP
"\fI\&.pcx\fR"
Syntax rules for \fITclDevKit\fR's \fBtclchecker\fR\&. Using these
rules allows the checker to validate the use of commands of a Tcllib
package \fBfoo\fR without having to scan the "\fI\&.tcl\fR" files
implementing it\&.
.PP
.SH "TESTSUITE TOOLING"
Testsuites in Tcllib are based on Tcl's standard test package
\fBtcltest\fR, plus utilities found in the directory
"\fImodules/devtools\fR"
.PP
Tcllib developers invoke the suites through the
\fBtest run\fR method of the "\fIsak\&.tcl\fR" tool, with other methods
of \fBtest\fR providing management operations, for example setting a
list of standard Tcl shells to use\&.
.SS "INVOKE THE TESTSUITES OF A SPECIFIC MODULE"
Invoke either
.CS

  \&./sak\&.tcl test run foo
.CE
or
.CS

  \&./sak\&.tcl test run modules/foo
.CE
to invoke the testsuites found in a specific module "\fIfoo\fR"\&.
.SS "INVOKE THE TESTSUITES OF ALL MODULES"
Invoke the tool without a module name, i\&.e\&.
.CS

  \&./sak\&.tcl test run
.CE
to invoke the testsuites of all modules\&.
.SS "DETAILED TEST LOGS"
In all the previous examples the test runner will write a combination
of progress display and testsuite log to the standard output, showing
for each module only the tests that passed or failed and how many of
each in a summary at the end\&.
.PP
To get a detailed log, it is necessary to invoke the test
runner with additional options\&.
.PP
For one:
.CS


   \&./sak\&.tcl test run --log LOG foo

.CE
While this shows the same short log on the terminal as before, it also
writes a detailed log to the file "\fILOG\&.log\fR", and excerpts to
other files ("\fILOG\&.summary\fR", "\fILOG\&.failures\fR", etc\&.)\&.
.PP
For two:
.CS


  \&./sak\&.tcl test run -v foo

.CE
This writes the detailed log to the standard output, instead of the
short log\&.
.PP
Regardless of form, the detailed log contains a list of all test
cases executed, which failed, and how they failed (expected versus
actual results)\&.
.SS "SHELL SELECTION"
By default the test runner will use all the Tcl shells specified via
\fBtest add\fR to invoke the specified testsuites, if any\&. If no
such are specified it will fall back to the Tcl shell used to run the
tool itself\&.
.PP
Use option \fB--shell\fR to explicitly specify the Tcl shell
to use, like
.CS


  \&./sak\&.tcl test run --shell /path/to/tclsh \&.\&.\&.

.CE
.SS HELP
Invoke the tool as
.CS

  \&./sak\&.tcl help test
.CE
to see the detailed help for all methods of \fBtest\fR, and the
associated options\&.
.SH "DOCUMENTATION TOOLING"
The standard format used for documentation of packages and other
things in Tcllib is \fIdoctools\fR\&.
Its supporting packages are a part of Tcllib, see the directories
"\fImodules/doctools\fR" and "\fImodules/dtplite\fR"\&. The latter is
an application package, with the actual application
"\fIapps/dtplite\fR" a light wrapper around it\&.
.PP
Tcllib developers gain access to these through the \fBdoc\fR
method of the "\fIsak\&.tcl\fR" tool, another (internal) wrapper around
the "\fImodules/dtplite\fR" application package\&.
.SS "GENERATE DOCUMENTATION FOR A SPECIFIC MODULE"
Invoke either
.CS

  \&./sak\&.tcl doc html foo
.CE
or
.CS

  \&./sak\&.tcl doc html modules/foo
.CE
to generate HTML for the documentation found in the module "\fIfoo\fR"\&.
Instead of \fBhtml\fR any other supported format can be used here,
of course\&.
.PP
The generated formatted documentation will be placed into a
directory "\fIdoc\fR" in the current working directory\&.
.SS "GENERATE DOCUMENTATION FOR ALL MODULES"
Invoke the tool without a module name, i\&.e\&.
.CS

  \&./sak\&.tcl doc html
.CE
to generate HTML for the documentation found in all modules\&.
Instead of \fBhtml\fR any other supported format can be used here,
of course\&.
.PP
The generated formatted documentation will be placed into a
directory "\fIdoc\fR" in the current working directory\&.
.SS "AVAILABLE OUTPUT FORMATS, HELP"
Invoke the tool as
.CS

  \&./sak\&.tcl help doc
.CE
to see the entire set of supported output formats which can be
generated\&.
.SS "VALIDATION WITHOUT OUTPUT"
Note the special format \fBvalidate\fR\&.
.PP
Using this value as the name of the format to generate forces
the tool to simply check that the documentation is syntactically
correct, without generating actual output\&.
.PP
Invoke it as either
.CS

  \&./sak\&.tcl doc validate (modules/)foo
.CE
or
.CS

  \&./sak\&.tcl doc validate
.CE
to either check the packages of a specific module or check all of
them\&.
.SH "NOTES ON WRITING A TESTSUITE"
While previous sections talked about running the testsuites for a
module and the packages therein, this has no meaning if the module in
question has no testsuites at all\&.
.PP
This section gives a very basic overview on possible
methodologies for writing tests and testsuites\&.
.PP
First there are "drudgery" tests\&. Written to check absolutely
basic assumptions which should never fail\&.
.PP
For example for a command FOO taking two arguments, three tests
calling it with zero, one, and three arguments\&. The basic checks that
the command fails if it has not enough arguments, or too many\&.
.PP
After that come the tests checking things based on our
knowledge of the command, about its properties and assumptions\&. Some
examples based on the graph operations added during Google's Summer of
Code 2009 are:
.IP \(bu
The BellmanFord command in struct::graph::ops takes a
\fIstartnode\fR as argument, and this node should be a node of
the graph\&. This equals one test case checking the behavior when the
specified node is not a node of the graph\&.
.sp
This often gives rise to code in the implementation which
explicitly checks the assumption and throws an understandable error,
instead of letting the algorithm fail later in some weird
non-deterministic way\&.
.sp
It is not always possible to do such checks\&. The graph argument
for example is just a command in itself, and while we expect
it to exhibit a certain interface, i\&.e\&. a set of sub-commands
aka methods, we cannot check that it has them, except by
actually trying to use them\&. That is done by the algorithm
anyway, so an explicit check is just overhead we can get by
without\&.
.IP \(bu
IIRC one of the distinguishing characteristic of either
BellmanFord and/or Johnson is that they are able to handle
negative weights\&. Whereas Dijkstra requires positive weights\&.
.sp
This induces (at least) three testcases \&.\&.\&. Graph with all
positive weights, all negative, and a mix of positive and
negative weights\&.
Thinking further does the algorithm handle the weight
\fB0\fR as well ? Another test case, or several, if we mix
zero with positive and negative weights\&.
.IP \(bu
The two algorithms we are currently thinking about are about
distances between nodes, and distance can be 'Inf'inity,
i\&.e\&. nodes may not be connected\&. This means that good test
cases are
.RS
.IP [1]
Strongly connected graph
.IP [2]
Connected graph
.IP [3]
Disconnected graph\&.
.RE
.sp
At the extremes of strongly connected and disconnected
we have the fully connected graphs and graphs without edges,
only nodes, i\&.e\&. completely disconnected\&.
.IP \(bu
IIRC both of the algorithms take weighted arcs, and fill in a
default if arcs are left unweighted in the input graph\&.
.sp
This also induces three test cases:
.RS
.IP [1]
Graph will all arcs with explicit weights\&.
.IP [2]
Graph without weights at all\&.
.IP [3]
Graph with mixture of weighted and unweighted graphs\&.
.RE
.PP
.PP
What was described above via examples is called
\fIblack-box\fR testing\&. Test cases are designed and written based on
the developer's knowledge of the properties of the algorithm and its
inputs, without referencing a particular implementation\&.
.PP
Going further, a complement to \fIblack-box\fR testing is
\fIwhite-box\fR\&. For this we know the implementation of the
algorithm, we look at it and design our tests cases so that they force
the code through all possible paths in the implementation\&. Wherever a
decision is made we have a test case forcing a specific direction of
the decision, for all possible combinations and directions\&. It is easy
to get a combinatorial explosion in the number of needed test-cases\&.
.PP
In practice I often hope that the black-box tests I have made
are enough to cover all the paths, obviating the need for white-box
tests\&.
.PP
The above should be enough to make it clear that writing tests
for an algorithm takes at least as much time as coding the algorithm,
and often more time\&. Much more time\&.
See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup
on how the Sqlite database engine is tested\&. Another article of
interest might be \fIhttps://www\&.researchgate\&.net/publication/298896236\fR\&.
While geared to a particular numerical algorithm it still shows that
even a simple-looking algorithm can lead to an incredible number of
test cases\&.
.PP
An interesting connection is to documentation\&. In one
direction, the properties checked with black-box testing are exactly
the properties which should be documented in the algorithm's man
page\&. And conversely, the documentation of the properties of an
algorithm makes a good reference to base the black-box tests on\&.
.PP
In practice test cases and documentation often get written
together, cross-influencing each other\&. And the actual writing of test
cases is a mix of black and white box, possibly influencing the
implementation while writing the tests\&. Like writing a test for a
condition like \fIstartnode not in input graph\fR serving as
reminder to put a check for this condition into the code\&.
.SH "INSTALLATION TOOLING"
A last thing to consider when adding a new package to the collection
is installation\&.
.PP
How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented
in \fITcllib - The Installer's Guide\fR\&.
.PP
Here we document how to extend said installer so that it may
install new package(s) and/or application(s)\&.
.PP
In most cases only a single file has to be modified, the
"\fIsupport/installation/modules\&.tcl\fR" holding one command per module
and application to install\&.
.PP
The relevant commands are:
.TP
\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR
Install the packages of module \fIname\fR, found in
"\fImodules/\fIname\fR\fR"\&.
.sp
The \fIcode-action\fR is responsible for installing the
packages and their index\&. The system currently provides
.RS
.TP
\fB_tcl\fR
Copy all "\fI\&.tcl\fR" files found in
"\fImodules/\fIname\fR\fR" into the installation\&.
.TP
\fB_tcr\fR
As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in
the subdirectories of "\fImodules/\fIname\fR\fR" as well\&.
.TP
\fB_tci\fR
As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file
as well\&.
.TP
\fB_msg\fR
As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR"
as well\&.
.TP
\fB_doc\fR
As \fB_tcl\fR, and copy the subdirectory
"\fImpformats\fR" as well\&.
.TP
\fB_tex\fR
As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&.
.RE
.sp
The \fIdoc-action\fR is responsible for installing the package
documentation\&. The system currently provides
.RS
.TP
\fB_null\fR
No documentation available, do nothing\&.
.TP
\fB_man\fR
Process the "\fI\&.man\fR" files found in
"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML)
in the proper location, as given to the installer\&.
.sp
This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under "\fIidoc\fR"\&.
.RE
.sp
The \fIexample-action\fR is responsible for installing the
examples\&. The system currently provides
.RS
.TP
\fB_null\fR
No examples available, do nothing\&.
.TP
\fB_exa\fR
Copy the the directory "\fIexamples/\fIname\fR\fR"
recursively to the install location for examples\&.
.RE
.TP
\fBApplication\fR \fIname\fR
Install the application with \fIname\fR, found in "\fIapps\fR"\&.
.TP
\fBExclude\fR \fIname\fR
This command signals to the installer which of the listed modules to
\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&.
.PP
.PP
If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
"\fIsupport/installation/actions\&.tcl\fR"\&.
.PP
This file contains the implementations of the available
actions, and is the place where any custom action needed to handle the
special circumstances of module has to be added\&.