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