zipfs - Mount and work with ZIP files within Tcl

Description

The zipfs command provides Tcl with the ability to mount the contents of a ZIP archive file as a virtual
file system. Tcl's ZIP archive support is limited to basic features and options. Supported storage
methods include only STORE and DEFLATE with optional simple encryption, sufficient to prevent casual
inspection of their contents but not able to prevent access by even a moderately determined attacker.
Strong encryption, multi-part archives, platform metadata, zip64 formats and other compression methods
like bzip2 are not supported.

Files within mounted archives can be written to but new files or directories cannot be created. Further,
modifications to files are limited to the mounted archive in memory and are not persisted to disk.

Paths in mounted archives are case-sensitive on all platforms.

zipfscanonical ?mountpoint? filename
This takes the name of a file, filename, and produces where it would be mapped into a zipfs mount
as its result. If specified, mountpoint says within which mount the mapping will be done; if
omitted, the main root of the zipfs system is used.

zipfsexistsfilename
Return 1 if the given filename exists in the mounted zipfs and 0 if it does not.

zipfsfinddirectoryName
Returns the list of paths under directory directoryName which need not be within a zipfs mounted
archive. The paths are prefixed with directoryName. This command is also used by the zipfsmkzip
and zipfsmkimg commands.

zipfsinfofile
Return information about the given file in the mounted zipfs. The information consists of:

(1) the name of the ZIP archive file that contains the file,

(2) the size of the file after decompressions,

(3) the compressed size of the file, and

(4) the offset of the compressed data in the ZIP archive file.

As a special case, querying the mount point gives the start of the zip data as the offset in (4),
which can be used to truncate the zip information from an executable. Querying an ancestor of a
mount point will raise an error.

zipfslist ?(-glob|-regexp)? ?pattern?
If pattern is not specified, the command returns a list of files across all zipfs mounted
archives. If pattern is specified, only those paths matching the pattern are returned. By default,
or with the -glob option, the pattern is treated as a glob pattern and matching is done as
described for the stringmatch command. Alternatively, the -regexp option may be used to specify
matching pattern as a regular expression. The file names are returned in arbitrary order. Note
that path separators are treated as ordinary characters in the matching. Thus forward slashes
should be used as path separators in the pattern. The returned paths only include those actually
in the archive and does not include intermediate directories in mount paths.

zipfsmountzipfsmountmountpointzipfsmountzipfilemountpoint ?password?

The zipfsmount command mounts ZIP archives as Tcl virtual file systems and returns information
about current mounts.

With no arguments, the command returns a dictionary mapping mount points to the path of the
corresponding ZIP archive.

In the single argument form, the command returns the file path of the ZIP archive mounted at the
specified mount point.

In the third form, the command mounts the ZIP archive zipfile as a Tcl virtual filesystem at
mountpoint. After this command executes, files contained in zipfile will appear to Tcl to be
regular files at the mount point. If mountpoint is specified as an empty string, it is defaulted
to the [zipfsroot]. The command returns the normalized mount point path.

If not under the zipfs file system root, mountpoint is normalized with respect to it. For example,
a mount point passed as either mt or /mt would be normalized to //zipfs:/mt (given that zipfsroot
returns “//zipfs:/”). An error is raised if the mount point includes a drive or UNC volume.

NB: because the current working directory is a concept maintained by the operating system, using
cd into a mounted archive will only work in the current process, and then not entirely
consistently (e.g., if a shared library uses direct access to the OS rather than through Tcl's
filesystem API, it will not see the current directory as being inside the mount and will not be
able to access the files inside the mount).

zipfsmountdatadatamountpoint
Mounts the ZIP archive content data as a Tcl virtual filesystem at mountpoint.

zipfsroot
Returns a constant string which indicates the mount point for zipfs volumes for the current
platform. User should not rely on the mount point being the same constant string for all
platforms.

zipfsunmountmountpoint
Unmounts a previously mounted ZIP archive mounted to mountpoint. The command will fail with an
error exception if there are any files within the mounted archive are open.

ZIPCREATIONCOMMANDS
This package also provides several commands to aid the creation of ZIP archives as Tcl applications.

zipfsmkzipoutfileindir ?strip? ?password?
Creates a ZIP archive file named outfile from the contents of the input directory indir (contained
regular files only) with optional ZIP password password. While processing the files below indir
the optional file name prefix given in strip is stripped off the beginning of the respective file
name if non-empty. When stripping, it is common to remove either the whole source directory name
or the name of its parent directory.

Caution: the choice of the indir parameter (less the optional stripped prefix) determines the
later root name of the archive's content.

zipfsmkimgoutfileindir ?strip? ?password? ?infile?
Creates an image (potentially a new executable file) similar to zipfsmkzip; see that command for
a description of most parameters to this command, as they behave identically here. If outfile
exists, it will be silently overwritten.

If the infile parameter is specified, this file is prepended in front of the ZIP archive,
otherwise the file returned by infonameofexecutable (i.e., the executable file of the running
process, typically wish or tclsh) is used. If the password parameter is not the empty string, an
obfuscated version of that password (see zipfsmkkey) is placed between the image and ZIP chunks
of the output file and the contents of the ZIP chunk are protected with that password. If the
starting image has a ZIP archive already attached to it, it is removed from the copy in outfile
before the new ZIP archive is added.

If there is a file, main.tcl, in the root directory of the resulting archive and the image file
that the archive is attached to is a tclsh (or wish) instance (true by default, but depends on
your configuration), then the resulting image is an executable that will source the script in that
main.tcl after mounting the ZIP archive, and will exit once that script has been executed.

Note:tclsh and wish can be built using either dynamic binding or static binding of the core
implementation libraries. With a dynamic binding, the base application Tcl_Library contents are
attached to the libtcl and libtk shared library, respectively. With a static binding, the
Tcl_Library contents, etc., are attached to the application, tclsh or wish. When using mkimg with
a statically built tclsh, it is the user's responsibility to preserve the attached archive by
first extracting it to a temporary location, and then add whatever additional files desired,
before creating and attaching the new archive to the new application.

zipfsmkkeypassword
Given the clear text password argument, an obfuscated string version is returned with the same
format used in the zipfsmkimg command.

zipfslmkimgoutfileinlist ?password? ?infile?
This command is like zipfsmkimg, but instead of an input directory, inlist must be a Tcl list
where the odd elements are the names of files to be copied into the archive in the image, and the
even elements are their respective names within that archive.

zipfslmkzipoutfileinlist ?password?
This command is like zipfsmkzip, but instead of an input directory, inlist must be a Tcl list
where the odd elements are the names of files to be copied into the archive, and the even elements
are their respective names within that archive.

Examples

       Mounting an ZIP archive as an application directory and running code  out  of  it  before  unmounting  it
       again:

              set zip myApp.zip
              set base [file join [zipfsroot] myApp]

              zipfsmount $zip $base
              # $base now has the contents of myApp.zip

              source [file join $base app.tcl]
              # use the contents, load libraries from it, etc...

              zipfsunmount $base

       Creating  a ZIP archive, given that a directory exists containing the content to put in the archive. Note
       that the source directory is given twice, in order  to  strip  the  exterior  directory  name  from  each
       filename in the archive.

              set sourceDirectory [file normalize myApp]
              set targetZip myApp.zip

              zipfsmkzip $targetZip $sourceDirectory $sourceDirectory

       Encryption can be applied to ZIP archives by providing a password when building the ZIP and when mounting
       it.

              set zip myApp.zip
              set sourceDir [file normalize myApp]
              set password "hunter2"
              set base [file join [zipfsroot] myApp]

              # Create with password
              zipfsmkzip $targetZip $sourceDir $sourceDir $password

              # Mount with password
              zipfsmount $zip $base $password

       The  following  example creates an executable application by appending a ZIP archive to the tclsh file it
       was called from and storing  the  resulting  executable  in  the  file  “myApp.bin”.   When  creating  an
       executable image with a password, the password is placed within the executable in a shrouded form so that
       the application can read files inside the embedded ZIP archive yet casual inspection cannot read it.

              set appDir [file normalize myApp]
              set img "myApp.bin"
              set password "hunter2"

              # Create some simple content to define a basic application
              file mkdir $appDir
              set f [open $appDir/main.tcl w]
              puts $f {
                  puts "Hi. This is [info script]"
              }
              close $f

              # Create the executable application
              zipfsmkimg $img $appDir $appDir $password

              # remove the now obsolete temporary appDir folder
              file delete -force $appDir

              # Launch the executable, printing its output to stdout
              exec $img >@stdout
              # prints the following line assuming [zipfs root] returns "//zipfs:/":
              # Hi.Thisis//zipfs:/app/main.tcl

Keywords

       compress, filesystem, zip

Zipfs                                                  1.0                                           zipfs(3tcl)

Name

       zipfs - Mount and work with ZIP files within Tcl

Note

       The current syntax for certain subcommands using multiple optional parameters might change in the  future
       to  support  an  ?-optionvalue? pattern instead.  Therfore, the current syntax should not be considered
       stable.

Synopsis

zipfscanonical ?mountpoint? filenamezipfsexistsfilenamezipfsfinddirectoryNamezipfsinfofilenamezipfslist ?(-glob|-regexp)? ?pattern?
       zipfslmkimgoutfileinlist ?password? ?infile?
       zipfslmkzipoutfileinlist ?password?
       zipfsmkimgoutfileindir ?strip? ?password? ?infile?
       zipfsmkkeypasswordzipfsmkzipoutfileindir ?strip? ?password?
       zipfsmount ?zipfile? ?mountpoint? ?password?
       zipfsmountdatadatamountpointzipfsrootzipfsunmountmountpoint
________________________________________________________________________________________________________________