-
Notifications
You must be signed in to change notification settings - Fork 2
/
Reorganization.Notes.txt
283 lines (215 loc) · 11.6 KB
/
Reorganization.Notes.txt
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
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
TODO
Test suites
Documentation
Last: Removal of old sources and build system.
=====================================================================
Proposal for a reorganization of the build system used by Img and its
supporting libraries.
=====================================================================
Glossary
--------
Up front a small glossary of terms to avoid confusion later.
[1] 'package library' (can be shortend to 'package').
A shared library having all the special code (xx_Init,
xx_SafeInit) to allow the tcl core to load it as a Tcl
package.
Examples: [incr Tcl], [Trf], ...
[2] 'support library'
A shared library which can not be loaded as a Tcl package.
Examples: libz, libjpeg, libpng, ...
Intro
-----
I propose to slash the existing source code into a number of separate
packages. I do _not_ propose to place each of these new packages into
a separate source tree. The files stay in the existing tree, and this
tree is augmented with additional directories containing the files
relevant to configuring and building the new packages. Essentially
configure.ac and Makefile.in. All build systems will be based upon the
TEA 2 system introduced in the sampleextension (See Tcl SF project).
Note: I created the new build systems for TclXML/DOM/XSLT and their
various subpackages (expat, libxml2, ...) in this way, with success
IMHO :)
There will be one package containing the common utilities and one
package per image format, and support library [*]. The old name of the
package, Img, will be used to define a 'super'-package which loads all
of the existing functionality into the interpreter when required. This
maintains compatibility with existing scripts.
From the points of view of scripts there will be _no_ change in the
perceived functionality. It should however be easier to write
additional image format handlers using the framework provided by Img.
[*] As for why one package per support library see the next section.
Handling of the support libraries coming with Img
(and of support libraries) in general.
-----------------------------------------------------
Available options, discussion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(1) Create the support libraries as part of the package for the
format requiring them. This is essentially a static linkage.
This one of the easiest ways to build a support library.
It also implies that the functionality a support library used
in multiple format handlers is loaded multiple times. To me
this a severe disadvantage.
(2) Create the support libraries independent of the using
packages, as shared libraries
(a) Link support at compile time into the packages.
(1) Via -library. In other words implicit usage of
the shared library loader provided by the OS.
Still relatively easy to do, although it
requires more care to portably generate shared
libraries. Libries used multiple times are
loaded only once.
Also requires a lot of additional support code
if the library a supporting library is linked
to is stored in and loaded from a non-native
filesystem. In other words when used in wrapped
application and such. The support code has to
copy the support libraries to the same place
in the native FS the using library is copied
to, _before_ the using library is loaded, so
that the support libraries are available to
the dyn.loader provided by the OS.
(2) Via direct usage of the objects. In other
words static linkage. This is the same as (1).
(b) Link support at runtime.
(1) Via explicit usage of the shared library
loader provided by the OS.
Generation of the support library is like for
(2a1). Loading however is done by explicitly
invoking the shared library loader of the
OS. This allows the Tcl library to perform the
necessary copying should the support library
reside in a non-native filesystem.
As the support library does not follow the
convention of a tcl package (per definitionem)
the standard load functionality of Tcl cannot
be used to load the library. This means that
(a) either the load functionality in Tcl
is refactored into
- portable low-level loading of
any shared library
- and high-level layer for
handling loaded shared
libraries which are tcl
packages.
(b) or the 'img' package has to carry the
source code implementing the portable
loading of shared libraries.
Option (b) I consider rather unpleasant as it
leads to the duplication of functionality in
all high-level packages requiring the loading
support libraries. Trf and TrfCrypt for
example have need of this functionality too.
(2) Wrap support library into thin package
exporting its functionality via a
stub-table. In other words, turn the support
library into a package library.
In contrast to (2b1) the support library is
not created as simple shared library, but with
all the necessary additional code to cause tcl
to recognize it as true package.
A stub table is used to provide the
functionality of the support library to other
packages.
This option could also be seen as (2b1c). It
makes the library available in a simple manner
with the need to refactor the load
functionality provided by the Tcl core. It
allows us to drive the reoganization of Img
independent of the Tcl core, making do with
the existing functionality. It also
essentially removes the impetus to actually
implement (2b1a). The good (enough) is the
enemy of the best.
Conclusion
~~~~~~~~~~
I have chosen option (2b2) for the support libraries. My reasons for
doing so are this:
* The state of the implementation of (2b1/1) is unclear. It
requires a TIP, and no movement is seen on that front.
The chosen option has no dependency on this vaporous
functionality.
* The chosen option allows us to use TEA 2 based build systems
for the support libraries themselves. They are easier to create
and later maintain, at least I perceive them so, due to the
larger number of existing TEA 2 based package I can draw upon
as templates for the new packages.
* Note that the chosen option does not prevent static linking of
the support libraries. Currently Img uses special code to
setup the function tables with static information when linking
Img statically. These function tables are essentially stub
tables. This means that the explicit usage of stub tables for
the support libraries makes this mode easier to handle too, as
no special code is required anymore.
* Note that the actually created package is also able use
-library to dynamically link to the actual support library. In
this mode it can make use of pre-installed libraries. In this
way we get a mixture of (2b2) and (2a1).
Files, and their organization into packages
-------------------------------------------
| Package | Stubtable | Files | Notes
-+---------------+---------------+----------------+------------------------
Ok | tkimg | Yes | img.h | Base package. Common
Ok | | | imgInt.h | utilities helping in
Ok | | | imgInit.c | the implementation of
Ok | | | imgObj.c | image handlers.
Ok | | | imgUtil.c |
-+---------------+---------------+----------------+------------------------
Ok | tkimg::bmp | | imgBMP.c | BMP format
Ok | tkimg::gif | | imgGIF.c | GIF format
Ok | tkimg::window | | imgWindow.c | windows
Ok | tkimg::xbm | | imgXBM.c | XBM format.
Ok | tkimg::xpm | | imgXPM.c | XPM format.
Ok | tkimg::ps | | imgPS.c | PostScript + PDF format
Ok | tkimg::jpeg | | imgJPEG.c | JPEG format
Ok | tkimg::png | | imgPNG.c | PNG format
Ok | tkimg::pcx | | | PCX format (Paintbrush)
Ok | tkimg::sgi | | | SGI format (SGI native)
Ok | tkimg::sun | | | SUN format (Sun raster)
Ok | tkimg::tga | | | TGA format (Truevision Targa)
-+---------------+---------------+----------------+------------------------
Ok | tkimg::tiff | | imgTIFF.c | TIFF format
Ok | | | imgTIFFjpeg.c | Various additional
Ok | | | imgTIFFpixar.c | codecs.
Ok | | | imgTIFFzip.c |
-+---------------+---------------+----------------+------------------------
Ok | tkimg::pixmap | | imgPmap.h | pixmap format
Ok | | | imgPmap.c | pixmap ? (PPM, XPM ?)
Ok | | | imgUnixPmap.c |
Ok | | | imgWinPmap.c |
-+---------------+---------------+----------------+------------------------
Ok | Img | | -- | Super package loading
Ok | | | | all of the above.
-+---------------+---------------+----------------+------------------------
Ok | jpegtcl | Yes | libjpeg/ | jpeg support library
Ok | pngtcl | Yes | libpng/ | png support library
Ok | zlibtcl | Yes | libz/ | zip support library
Ok | tifftcl | Yes | libtiff/ | tiff support library
-+---------------+---------------+----------------+------------------------
None of the '*Support' packages provides tcl level commands. They only
provide their own functionality, through stubtables. Note that the png
support library depends on libz, and thus has to require this package.
Misc. notes
-----------
* The zip support library (zlib, libz) is also used by
- tkHTML,
- JCW's 'zipper' package,
- zipvfs
- mk4vfs
- and Trf.
Placement of the ZlibSupport package with Img for the time
being is no problem and easy for tkHTML, as that package often
may want to use Img for the handling of additional image
formats in web pages. It is more of an issue when considering
zipper and Trf as there is more disconnect between them and
Img.
In the future we should move ZlibSupport into its own project,
or module in a project. Maybe directly into the source base of
zlib itself ?
The same can be considered for the PNG support.
Regarding JPEG the maintainership of the library much more
vague. In other words I don't know how to talk to for this.
* Regarding the code of img itself. Are the functions in
'imgObj' still necessary ? Especially ByteArray seems to
be a duplication of functionality provided by the Tcl core.
* Future: Reflect handler functionality into the Tcl level,
allow creation of format handlers in Tcl.