Wrap 0.3       October 12, 1999

This is the third trial release of a brand-new "Wrap" package. The
implementation is far from complete. Be warned. Therefore use
it with caution.

What does it do
---------------
The main portion of this library provides commands to extract
entries from zip-files which are attached to other files. The
"Wrap" package currently has 3 commands:

     ::wrap::source <name>
	evaluate the Tcl-script in entry <name> of the zip-file 
     ::wrap::open <name>
	open's a channel to entry <name> in the zip-file 
     ::wrap::info index <name>
	same as ::wrap::source, but should be used
	for index files (pkgIndex.tcl and tclIndex)

This package provides a very flexible way to use entries from zip-files
as if they are normal files. zip-files can be attached to executables,
dll's, anything (use your fantasy), and still Wrap can open all
entries as a normal channel. When "Wrap" opens a file, it will
inspect the last bytes of the file, which should contain special
ZIP-specific markers. If those markers are there, Wrap can extract
the content-table and store it in a hash-table. From there, entries
can be found directly by seeking directly to the correct offset in
the file. Everything is optimized for speed.

For example, assume you have an executable tclsh8.2s and you want
to add zip-entries to the executable. First you have to attach
the zip-markers to the end of the file:
    cat null.zip >>tclsh8.2s
This "null.zip", which is included in the Wrap distribution, is
nothing more than an empty zip-file. Now you can attach any number
of scripts, for example:
     zip -A -9 tclsh8.2s lib/tcl8.2/*   (assuming we are in <prefix>)
The only option that we have to remember is to use "-A", otherwise
zip assumes that the zip-header is at the beginning of the file.

Now tclsh8.2s is able to open all zip-entries which are in its
own executable, using the "Wrap" package. In stead of:
    open [file join $tcl_library init.tcl]
it now can do:
    ::wrap::open [file join lib tcl$tcl_version init.tcl]
remember, the filename can be omitted, because the zip-file
is attached to the executable itself!!!!


Why another new package to make "standalone executables"
--------------------------------------------------------

The tcl2c utility is old. It was a too clumsy way to
attach scripts to executables. Therefore tcl2c and all the
"standalone" support is now abandoned, and thus removed
from the plus-patches starting with 8.1. The "Wrap" package
is intended to provide all functionality that the plus-patches
provided in respect to standalone executables, but much better,
faster and more userfriendly. And, most important, it works
as a separate package without the need for core-patches.

Files:
---------

wrapRsrc.c
   implements a new "rsrc" object type, which holds
   a hash-table of all zip entries. This gives a very fast process
   in locating the zip-file entry: Only the first time when a
   file is opened, the table-of-contents will be stored in the
   hash-table. Later, when the content is needed, a seek can
   be done to the correct file position immediately.

wrapChan.c
   implements the rsrc-channel, which also handles the
   the zip-decompression. All the normal channel options, such
   as "-translation" and "-buffering" are available.
   In addition, there are 3 read-only options:
    -crc    gives the crc-value of the current entry
    -date   gives the time-stamp of the current entry
    -length gives the length of the current entry.

wrapInit.c
   implements the Tcl part of the "source", "open" and "resource"
   commands.

wrapMain.c
   Replacement for Tcl_Main and Tk_Main for standalone executables.


Limitations
-----------
- Only tested on Linux and Windows, not on any other system.
- Many more scripts are needed to make it realy useful.
- Only supported with Tcl8.2 and higher (8.2.1 recommended).
- tclsh8.2s has a very limited stdin console (see "tclsh8.2.tcl")
- wish8.2s uses TkCon as console.

The package can be built in 2 ways:

    1) configure --enable-shared
       make

         Then a binary package "libwrap0.3.so" will be built, which
         is loadable as "package require Wrap".
         Additionally, two executables "tclsh8.2s" and "wish8.2s"
         are built. Those two executables contain all initialization
         scripts of $tcl_library and $tk_library, but they require
         libtcl8.2.so, libtk8.2.so and libwrap0.3.so to be present
         on your system (set LD_LIBRARY_PATH!!!!!!!)

       make z

         Builds libz.so.1.1.3    (In case your sytems doesn't have it yet)
         Needed for compression support.

       make crypt

         Builds libcrypt.so.2.1.2 (In case your systems doesn't have it yet)
         Needed for MD5 support (to be implemented).

   2) "configure"
       make

       Now the package will be built as a static library "libwrap0.3.a".
       The executables "tclsh8.2s and "wish8.2s" now are relativly big.

       make z

         Builds libz.a

       make crypt

         Builds libcrypt.a


ToDo
      Many things. Idea's still have to be worked out.

Acknowledgement.
   Jean-Claude Wippler
      This package is for a great deal inspired by the useful
      discussions I had with him about software
      installation issues. Let's hope this partial implementation
      gives inspiration for more ideas.
   Matt Newman
      Gave many very useful suggestions, supplied the initial
      VC++ makefiles and the date/time handling.