diff options
Diffstat (limited to 'tkimg/Reorganization.Notes.txt')
-rw-r--r-- | tkimg/Reorganization.Notes.txt | 283 |
1 files changed, 0 insertions, 283 deletions
diff --git a/tkimg/Reorganization.Notes.txt b/tkimg/Reorganization.Notes.txt deleted file mode 100644 index 4bf621e..0000000 --- a/tkimg/Reorganization.Notes.txt +++ /dev/null @@ -1,283 +0,0 @@ -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. |