Tcl Library Source Code

Check-in [9e39cdbfe8]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Filled in test writing and install support sections of the devguide.
Timelines: family | ancestors | descendants | both | doc-overhaul
Files: files | file ages | folders
SHA3-256: 9e39cdbfe84c4185e0963b05cb1997d3eb03b7eb86f88330445fe7e22324aabd
User & Date: aku 2019-03-12 04:59:56
Context
2019-03-12
05:49
Added info about branches and version number incrementing. Tweaked install tooling notes. check-in: f6eb7e4e99 user: aku tags: doc-overhaul
04:59
Filled in test writing and install support sections of the devguide. check-in: 9e39cdbfe8 user: aku tags: doc-overhaul
2019-03-08
06:47
Removed deprecated tag `strong`, replaced with `emph`. check-in: fec15b366e user: aku tags: doc-overhaul
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to devdoc/parts/d_installation.inc.






























































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
A last thing to consider when adding a new package to the collection
is installation.

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

[para] Here we document how to extend the installer so that it may
install the new package(s).

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

[para] The 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.

Changes to devdoc/parts/d_testwrite.inc.






































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
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. Equals one test case checking the behavior when the
	specified node is not a node a graph.

[para]  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.

[para]  It 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.

[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.

Changes to devdoc/tcllib_devguide.man.

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
[comment {===================================================================}]
[section {Testsuite Tooling}]
[include parts/d_testing.inc]

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

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

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

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







|



|



|




43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
[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]

Changes to embedded/www/tcllib/files/devdoc/tcllib_devguide.html.

102
103
104
105
106
107
108

109
110
111
112
113
114
115
...
138
139
140
141
142
143
144









145
146
147
148
149
150
151
...
453
454
455
456
457
458
459
460
461
462
463
464












































































465
















466
467
468





































































469
470
<h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_devguide - Tcllib - The Developer's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>

<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commitments</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
<li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
</ul>
</li>
................................................................................
<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
<li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
</ul>









</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>This document is a guide for developers working on Tcllib,
................................................................................
the tool to simply check that the documentation is syntactically
correct, without generating actual output.</p>
<p>Invoke it as either</p>
<pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
<p>or</p>
<pre class="doctools_example">  ./sak.tcl doc validate </pre>
<p>to either check the packages of a specific module or check all of
them.
x</p>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>












































































<p>x</p>
















</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
<p>x</p>





































































</div>
</div>






>







 







>
>
>
>
>
>
>
>
>







 







|
<



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
...
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
...
463
464
465
466
467
468
469
470

471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568

569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
<h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_devguide - Tcllib - The Developer's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commitments</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
<li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
</ul>
</li>
................................................................................
<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
<li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></li>
<li><a href="#2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>This document is a guide for developers working on Tcllib,
................................................................................
the tool to simply check that the documentation is syntactically
correct, without generating actual output.</p>
<p>Invoke it as either</p>
<pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
<p>or</p>
<pre class="doctools_example">  ./sak.tcl doc validate </pre>
<p>to either check the packages of a specific module or check all of
them.</p>

</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>
<p>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.</p>
<p>This section gives a very basic overview on possible
methodologies for writing tests and testsuites.</p>
<p>First there are &quot;drudgery&quot; tests. Written to check absolutely
basic assumptions which should never fail.</p>
<p>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.</p>
<p>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:</p>
<ul class="doctools_itemized">
<li><p>The BellmanFord command in struct::graph::ops takes a
	<i class="arg">startnode</i> 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.</p>
<p>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.</p>
<p>It 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.</p></li>
<li><p>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.</p>
<p>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
	<b class="const">0</b> as well ? Another test case, or several, if we mix
	zero with positive and negative weights.</p></li>
<li><p>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</p>
<ol class="doctools_enumerated">
	
<li><p>Strongly connected graph</p></li>
<li><p>Connected graph</p></li>
<li><p>Disconnected graph.</p></li>
</ol>
<p>At the extremes of strongly connected and disconnected
	we have the fully connected graphs and graphs without edges,
	only nodes, i.e. completely disconnected.</p></li>
<li><p>IIRC both of the algorithms take weighted arcs, and fill in a
	default if arcs are left unweighted in the input graph.</p>
<p>This also induces three test cases:</p>
<ol class="doctools_enumerated">
	
<li><p>Graph will all arcs with explicit weights.</p></li>
<li><p>Graph without weights at all.</p></li>
<li><p>Graph with mixture of weighted and unweighted graphs.</p></li>
</ol>
</li>
</ul>
<p>What was described above via examples is called
<i class="term">black-box</i> 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.</p>
<p>Going further, a complement to <i class="term">black-box</i> testing is
<i class="term">white-box</i>. 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.</p>
<p>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.</p>
<p>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 <a href="http://sqlite.org/testing.html">http://sqlite.org/testing.html</a>, a writeup
on how the Sqlite database engine is tested.</p>
<p>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.</p>
<p>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 <i class="term">startnode not in input graph</i> serving as
reminder to put a check for this condition into the code.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>

<p>A last thing to consider when adding a new package to the collection
is installation.</p>
<p>How to <em>use</em> the tool, the &quot;<b class="file">installer.tcl</b>&quot; script is
doumented in
<i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
<p>Here we document how to extend the installer so that it may
install the new package(s).</p>
<p>In most cases only a single file has to be modified,
&quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
and application to install.</p>
<p>The commands are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></dt>
<dd><p>Install the packages of module <i class="arg">name</i>, found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
<p>The <i class="arg">code-action</i> is responsible for installing the
packages and their index. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_tcl</b></dt>
<dd><p>Copy all &quot;<b class="file">.tcl</b>&quot; files found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; into the installation.</p></dd>
<dt><b class="cmd">_tcr</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, copy the &quot;<b class="file">.tcl</b>&quot; files found in
the subdirectories of &quot;<b class="file">modules/<i class="arg">name</i></b>&quot; as well.</p></dd>
<dt><b class="cmd">_tci</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the &quot;<b class="file">tclIndex.tcl</b>&quot; file
as well.</p></dd>
<dt><b class="cmd">_msg</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory &quot;<b class="file">msgs</b>&quot;
as well.</p></dd>
<dt><b class="cmd">_doc</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory
&quot;<b class="file">mpformats</b>&quot; as well.</p></dd>
<dt><b class="cmd">_tex</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy &quot;<b class="file">.tex</b>&quot; files as well.</p></dd>
</dl>
<p>The <i class="arg">doc-action</i> is responsible for installing the package
documentation. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_null</b></dt>
<dd><p>No documentation available, do nothing.</p></dd>
<dt><b class="cmd">_man</b></dt>
<dd><p>Process the &quot;<b class="file">.man</b>&quot; files found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; and install the results (nroff and/or HTML)
in the proper location, as given to the installer.</p>
<p>This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under &quot;<b class="file">idoc</b>&quot;.</p></dd>
</dl>
<p>The <i class="arg">example-action</i> is responsible for installing the
examples. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_null</b></dt>
<dd><p>No examples available, do nothing.</p></dd>
<dt><b class="cmd">_exa</b></dt>
<dd><p>Copy the the directory &quot;<b class="file">examples/<i class="arg">name</i></b>&quot;
recursively to the install location for examples.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></dt>
<dd><p>Install the application with <i class="arg">name</i>, found in &quot;<b class="file">apps</b>&quot;.</p></dd>
<dt><a name="3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></dt>
<dd><p>This command signals to the installer which of the listed modules to
<em>not</em> install. I.e. they name the deprecated modules of Tcllib.</p></dd>
</dl>
<p>If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
&quot;<b class="file">support/installation/actions.tcl</b>&quot;.</p>
<p>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.</p>
</div>
</div>

Changes to idoc/man/files/devdoc/tcllib_devguide.n.

268
269
270
271
272
273
274








275
276
277
278
279
280
281
...
647
648
649
650
651
652
653
654
655
656


















































































































657
658



























































































.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tcllib_devguide \- Tcllib - The Developer's Guide








.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,
................................................................................
or
.CS

  \&./sak\&.tcl doc validate
.CE
to either check the packages of a specific module or check all of
them\&.
x
.SH "NOTES ON WRITING A TESTSUITE"
x


















































































































.SH "INSTALLATION TOOLING"
x

































































































>
>
>
>
>
>
>
>







 







<

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
...
655
656
657
658
659
660
661

662

663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777

778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
.\"	# 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,
................................................................................
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\&. Equals one test case checking the behavior when the
specified node is not a node a graph\&.
.sp
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\&.
.sp
It 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\&.
.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 tool, the "\fIinstaller\&.tcl\fR" script is
doumented in
\fITcllib - The Installer's Guide\fR\&.
.PP
Here we document how to extend the installer so that it may
install the new package(s)\&.
.PP
In most cases only a single file has to be modified,
"\fIsupport/installation/modules\&.tcl\fR" holding one command per module
and application to install\&.
.PP
The 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\&.

Changes to idoc/www/tcllib/files/devdoc/tcllib_devguide.html.

109
110
111
112
113
114
115

116
117
118
119
120
121
122
...
145
146
147
148
149
150
151









152
153
154
155
156
157
158
...
460
461
462
463
464
465
466
467
468
469
470
471












































































472
















473
474
475





































































476
477
<h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_devguide - Tcllib - The Developer's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>

<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commitments</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
<li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
</ul>
</li>
................................................................................
<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
<li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
</ul>









</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>This document is a guide for developers working on Tcllib,
................................................................................
the tool to simply check that the documentation is syntactically
correct, without generating actual output.</p>
<p>Invoke it as either</p>
<pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
<p>or</p>
<pre class="doctools_example">  ./sak.tcl doc validate </pre>
<p>to either check the packages of a specific module or check all of
them.
x</p>
</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>












































































<p>x</p>
















</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>
<p>x</p>





































































</div>
</div></body></html>






>







 







>
>
>
>
>
>
>
>
>







 







|
<



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
...
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
...
470
471
472
473
474
475
476
477

478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575

576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
<h1 class="doctools_title">tcllib_devguide(n) 1 tcllib &quot;&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>tcllib_devguide - Tcllib - The Developer's Guide</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">Commitments</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Contributor</a></li>
<li class="doctools_subsection"><a href="#subsection2">Maintainer</a></li>
</ul>
</li>
................................................................................
<li class="doctools_subsection"><a href="#subsection14">Available output formats, help</a></li>
<li class="doctools_subsection"><a href="#subsection15">Validation without output</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section7">Notes On Writing A Testsuite</a></li>
<li class="doctools_section"><a href="#section8">Installation Tooling</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_syntax">
<li><a href="#1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></li>
<li><a href="#2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></li>
<li><a href="#3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a
package itself. It is a collection of (semi-independent) <i class="term"><a href="../../../index.html#tcl">Tcl</a></i>
packages that provide utility functions useful to a large collection
of Tcl programmers.</p>
<p>This document is a guide for developers working on Tcllib,
................................................................................
the tool to simply check that the documentation is syntactically
correct, without generating actual output.</p>
<p>Invoke it as either</p>
<pre class="doctools_example">  ./sak.tcl doc validate (modules/)FOO </pre>
<p>or</p>
<pre class="doctools_example">  ./sak.tcl doc validate </pre>
<p>to either check the packages of a specific module or check all of
them.</p>

</div>
</div>
<div id="section7" class="doctools_section"><h2><a name="section7">Notes On Writing A Testsuite</a></h2>
<p>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.</p>
<p>This section gives a very basic overview on possible
methodologies for writing tests and testsuites.</p>
<p>First there are &quot;drudgery&quot; tests. Written to check absolutely
basic assumptions which should never fail.</p>
<p>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.</p>
<p>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:</p>
<ul class="doctools_itemized">
<li><p>The BellmanFord command in struct::graph::ops takes a
	<i class="arg">startnode</i> 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.</p>
<p>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.</p>
<p>It 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.</p></li>
<li><p>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.</p>
<p>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
	<b class="const">0</b> as well ? Another test case, or several, if we mix
	zero with positive and negative weights.</p></li>
<li><p>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</p>
<ol class="doctools_enumerated">
	
<li><p>Strongly connected graph</p></li>
<li><p>Connected graph</p></li>
<li><p>Disconnected graph.</p></li>
</ol>
<p>At the extremes of strongly connected and disconnected
	we have the fully connected graphs and graphs without edges,
	only nodes, i.e. completely disconnected.</p></li>
<li><p>IIRC both of the algorithms take weighted arcs, and fill in a
	default if arcs are left unweighted in the input graph.</p>
<p>This also induces three test cases:</p>
<ol class="doctools_enumerated">
	
<li><p>Graph will all arcs with explicit weights.</p></li>
<li><p>Graph without weights at all.</p></li>
<li><p>Graph with mixture of weighted and unweighted graphs.</p></li>
</ol>
</li>
</ul>
<p>What was described above via examples is called
<i class="term">black-box</i> 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.</p>
<p>Going further, a complement to <i class="term">black-box</i> testing is
<i class="term">white-box</i>. 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.</p>
<p>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.</p>
<p>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 <a href="http://sqlite.org/testing.html">http://sqlite.org/testing.html</a>, a writeup
on how the Sqlite database engine is tested.</p>
<p>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.</p>
<p>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 <i class="term">startnode not in input graph</i> serving as
reminder to put a check for this condition into the code.</p>
</div>
<div id="section8" class="doctools_section"><h2><a name="section8">Installation Tooling</a></h2>

<p>A last thing to consider when adding a new package to the collection
is installation.</p>
<p>How to <em>use</em> the tool, the &quot;<b class="file">installer.tcl</b>&quot; script is
doumented in
<i class="term"><a href="tcllib_installer.html">Tcllib - The Installer's Guide</a></i>.</p>
<p>Here we document how to extend the installer so that it may
install the new package(s).</p>
<p>In most cases only a single file has to be modified,
&quot;<b class="file">support/installation/modules.tcl</b>&quot; holding one command per module
and application to install.</p>
<p>The commands are:</p>
<dl class="doctools_definitions">
<dt><a name="1"><b class="cmd"><a href="../../../index.html#module">Module</a></b> <i class="arg">name</i> <i class="arg">code-action</i> <i class="arg">doc-action</i> <i class="arg">example-action</i></a></dt>
<dd><p>Install the packages of module <i class="arg">name</i>, found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot;.</p>
<p>The <i class="arg">code-action</i> is responsible for installing the
packages and their index. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_tcl</b></dt>
<dd><p>Copy all &quot;<b class="file">.tcl</b>&quot; files found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; into the installation.</p></dd>
<dt><b class="cmd">_tcr</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, copy the &quot;<b class="file">.tcl</b>&quot; files found in
the subdirectories of &quot;<b class="file">modules/<i class="arg">name</i></b>&quot; as well.</p></dd>
<dt><b class="cmd">_tci</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the &quot;<b class="file">tclIndex.tcl</b>&quot; file
as well.</p></dd>
<dt><b class="cmd">_msg</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory &quot;<b class="file">msgs</b>&quot;
as well.</p></dd>
<dt><b class="cmd">_doc</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy the subdirectory
&quot;<b class="file">mpformats</b>&quot; as well.</p></dd>
<dt><b class="cmd">_tex</b></dt>
<dd><p>As <b class="cmd">_tcl</b>, and copy &quot;<b class="file">.tex</b>&quot; files as well.</p></dd>
</dl>
<p>The <i class="arg">doc-action</i> is responsible for installing the package
documentation. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_null</b></dt>
<dd><p>No documentation available, do nothing.</p></dd>
<dt><b class="cmd">_man</b></dt>
<dd><p>Process the &quot;<b class="file">.man</b>&quot; files found in
&quot;<b class="file">modules/<i class="arg">name</i></b>&quot; and install the results (nroff and/or HTML)
in the proper location, as given to the installer.</p>
<p>This is actually a fallback, normally the installer uses the
pre-made formatted documentation found under &quot;<b class="file">idoc</b>&quot;.</p></dd>
</dl>
<p>The <i class="arg">example-action</i> is responsible for installing the
examples. The system currently provides</p>
<dl class="doctools_definitions">
<dt><b class="cmd">_null</b></dt>
<dd><p>No examples available, do nothing.</p></dd>
<dt><b class="cmd">_exa</b></dt>
<dd><p>Copy the the directory &quot;<b class="file">examples/<i class="arg">name</i></b>&quot;
recursively to the install location for examples.</p></dd>
</dl></dd>
<dt><a name="2"><b class="cmd"><a href="../../../index.html#application">Application</a></b> <i class="arg">name</i></a></dt>
<dd><p>Install the application with <i class="arg">name</i>, found in &quot;<b class="file">apps</b>&quot;.</p></dd>
<dt><a name="3"><b class="cmd">Exclude</b> <i class="arg">name</i></a></dt>
<dd><p>This command signals to the installer which of the listed modules to
<em>not</em> install. I.e. they name the deprecated modules of Tcllib.</p></dd>
</dl>
<p>If, and only if the above actions are not suitable for the new
module then a second file has to be modified,
&quot;<b class="file">support/installation/actions.tcl</b>&quot;.</p>
<p>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.</p>
</div>
</div></body></html>