Merge commit '60d692811c12788ed4468d5ff680633304e8f641' as 'tkimg'

1 files changed, 283 insertions, 0 deletions

diff --git a/tkimg/Reorganization.Notes.txt b/tkimg/Reorganization.Notes.txt
new file mode 100755
index 0000000..6b3b9e6
--- /dev/null
+++ b/tkimg/Reorganization.Notes.txt
@@ -0,0 +1,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.in 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.