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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
RCS: @(#) $Id: README.developer,v 1.5 2007/08/30 17:24:13 andreas_kupries Exp $
Welcome to the tcllib, the Tcl Standard Library.
================================================
Introduction
------------
This README is intended to be a guide to the tools available to a
Developer
working on Tcllib to help him with his tasks, i.e. making the tasks easier
to perform. It is our hope that this will improve the quality of even
non-released revisions of Tcllib, and make the work of the release
manager easier as well.
Audience
--------
The intended audience, are first and foremost, developers beginning to
work on Tcllib. To an experienced developer this document will be less
of a guide and more of a reference. Anybody else interested in working
on Tcllib is invited as well.
Basics
------
< Flesh this out >
sak.tcl
< Tasks, and how to perform them >
Adding a new module
-------------------
Assuming that FOO is the name of the new module, and T is the toplevel
directory of the Tcllib sources
(1) Create the directory T/modules/FOO and put all the files of
the module into it. Note:
* The file 'pkgIndex.tcl' is required.
* Implementation files should have the extension '.tcl',
naturally.
* If available, documentation should be in doctools format,
and the files should have the extension '.man' for SAK to
recognize them.
* If available the testsuite(s) should use 'tcltest' and the
general format as used by the other modules in Tcllib
(declaration of minimally needed Tcl, tcltest, supporting
packages, etc.). The file(s) should have the extension
'.test' for SAK to recognize them.
Note that an empty testsuite, or a testsuite which does not
perform any tests is less than useful and will not be
accepted.
* If available the benchmark(s) should use 'bench' and the
general format as used by the other modules in Tcllib. The
file(s) should have the extension '.bench' for SAK to
recognize them.
* Other files can be named and placed as the module sees fit.
(2) If the new module has an example application A which is
polished enough for general use, put this application into the
file "T/apps/A.tcl", and its documentation into the file
"T/apps/A.man". While documentation for the application is
optional, it is preferred.
For examples which are not full-fledged applications, a
skeleton, or not really polished for use, etc., create the
directory T/examples/FOO/ and put them there.
A key difference is what happens to them on installation, and
what the target audience is.
The examples are for developers using packages in Tcllib,
whereas the applications are also for users of Tcllib which do
not have an interest in developing for and with it. As such,
they are installed as regular commands, accessible through the
PATH, and example files are not installed.
(3) To make Tcllib's installer aware of FOO, edit the file
T/support/installation/modules.tcl
Add a line 'Module FOO $impaction $docaction $exaction'. The
various actions describe to the installer how to install the
implementation files, the documentation, and the examples.
Add a line 'Application A' for any application A which was
added to T/apps for FOO.
The following actions are available:
Implementation
_tcl - Copy all .tcl files in T/modules/FOO into the installation.
_tcr - See above, does it for .tcl files in subdirectories as well.
_tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'.
_msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'.
_doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'.
_tex - _tcl + Copying of .tex files - special to module 'textutil'.
The _null action, see below, is available in principle
too, but a module without implementation does not make
sense.
Documentation
_null - Module has no documentation, do nothing.
_man - Process the .man files in T/modules/FOO and
install the results (nroff and/or HTML) in the
proper location, as given to the installer.
Examples
_null - Module has no examples, do nothing
_exa - Copy the directory T/examples/FOO
(recursively) to the install location for
examples.
Testing modules
---------------
To run the testsuite of a module FOO in tcllib use the 'test run'
argument of sak.tcl, like so:
% pwd
/the/tcllib/toplevel/directory
% ./sak.tcl test run FOO
or % ./sak.tcl test run modules/FOO
To run the testsuites of all modules either invoke 'test run' without a
module name, or use 'make test'. The latter assumes that configure was
run for Tcllib before, i.e.:
% ./sak.tcl test run FOO
or % ./sak.tcl test run modules/FOO
% make test
In all of the above cases the result will be a combination of progress
display and testsuite log, showing for each module the tests that pass
or failed and how many of each in a summary at the end.
To get a detailed log, it is necessary to invoke 'test run' with
additional options.
First example:
% ./sak.tcl test run -l LOG FOO
This shows the same short log on the terminal, and writes a detailed
log to the file LOG.log, and excerpts to other files (LOG.summary,
LOG.failures, etc.).
Second example:
% ./sak.tcl test run -v FOO
% make test > LOG
This writes the detailed log to stdout, or to the file LOG, instead of
the short log. In all cases, the detailed log contains a list of all
test cases executed, which failed, and how they failed (expected
versus actual results).
Note:
The commands
% make test
and % make test > LOG
are able to generate different output (short vs long log) because the
Makefile target contains code which detects that stdout has been
redirected to a file and acts accordingly.
Non-developers should reports problems in Tcllib's bug tracker.
Information about its location and the relevant category can be found
in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module
and/or package.
|
