ZIP virtual file system
Not logged in

AndroWish comes with a special ZIP virtual file system which uses mmap(2) to read-only map a ZIP file (in this case AndroWish's APK, i.e. its own installation package) into the process address space to speed up startup time and subsequent read accesses. While this file system was designed primarily for AndroWish it can be used on other platforms, too. Namely, undroidwish uses it on Windows and Linux to mount an archive of Tcl and native extensions which is appended to the executable portion of its binary. It is implemented in the files zipfs.c and zipfs.h in AndroWish's .../jni/tcl/generic folder and enabled in the Tcl core by the presence of the C preprocessor macro ZIPFS_IN_TCL.

Low-level C interface

Zipfs_Init(Tcl_Interp *interp)

Performs one-time initialization of the file system and registers it process wide. Additionally, a package named zipfs is provided and supplemental Tcl commands are created in the given interpreter.

Zipfs_Mount(Tcl_Interp *interp, const char *zipname, const char *mntpt, const char *passwd)

Mounts the ZIP archive file zipname on the mount point mntpt using the optional ZIP password passwd. Errors are reported in the interpreter interp. If zipname is NULL information on all currently mounted ZIP file systems is written into interp as a sequence of mount points and ZIP file names.

Zipfs_Unmount(Tcl_Interp *interp, const char *zipname)

Undoes the effect of Zipfs_Mount(), i.e. unmounts the mounted ZIP archive file zipname. Errors are reported in the interpreter interp.

Tcl commands

zipfs::mount ?zipfile ?mountpoint password?

Mounts the ZIP archive file zipfile on mount point mountpoint using the optional ZIP password password. If invoked without or with a single argument information as described above in Zipfs_Mount() is returned.

zipfs::unmount zipfile

Unmounts the mounted ZIP archive file zipfile.

zipfs::mkzip outfile indir ?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 prefix given in strip is stripped off the beginning of the respective file name. Caution: the choice of the indir parameter (less the optional strip prefix) determines the later root name of the archive's content.

zipfs::mkimg outfile indir ?strip password infile?

Caution: highly experimental, not usable on Android, only partially tested on Linux and Windows. Create an image (potentially a new executable file) similar to zipfs::mkzip. If the infile parameter is specified, this file is prepended in front of the ZIP archive, otherwise the file returned by Tcl_NameOfExecutable(3) (i.e. the executable file of the running process) is used. If the password parameter is not empty, an obfuscated version of that password is placed between the image and ZIP chunks of the output file and the contents of the ZIP chunk are protected with that password.

zipfs::exists pathname

Tests if pathname exists in any of the currently mounted ZIP archives.

zipfs::info pathname

Returns information on pathname as a list made up of the name of its enclosing and mounted ZIP archive file, file size uncompressed, file size compressed, and byte offset of the file from start of its enclosing ZIP archive file.

zipfs::list ?-glob|-regexp? ?pattern?

Lists files of any or all of the mounted ZIP archives. If pattern is omitted all files are listed. Otherwise pattern is interpreted as a glob or regexp pattern and used to list only files matching this pattern.

zipfs::find dir

Recursively lists files including and below the directory dir. The result list consists of relative path names starting from the given directory. This command is also used by the zipfs::mkzip and zipfs::mkimg commands.

zipfs as Tcl (and Tk) bootstrap file system

On the Android platform zipfs is used to boot Tcl/Tk from the APK by early mounting the APK file on the file system root. Since nearly all relevant files within the APK are below the assets folder, this lets Tcl see the directory /assets with its library directories, e.g. the /assets/tcl8.6 directory with Tcl's library modules, encoding tables etc. That relationship to /assets/tcl8.6 is hard coded into the Tcl shared library and based on it all other packaged library directories can be found during Tcl initialization.

For standalone apps a similar approach is chosen by hard coding the file /assets/app/main.tcl as the file to be sourced (if present) right after Tcl's initialization. This allows for packaging Tcl based apps as an APK, see the description in AndroWish SDK for instructions.

On other platforms (currently tested Linux and Windows) the initial mount of an embedded ZIP file system is done on the executable itself, e.g. if /home/john/awish is the Tcl/Tk binary with an included ZIP file system, the Tcl library directory of the file system when mounted becomes /home/john/awish/tcl8.6. Similarly, built in application code will be started from the file /home/john/awish/app/main.tcl if present. Additionally, the contents of the optional file /home/john/awish/app/cmdline are appended to the command line before Tk is initialized and control is transferred to the main.tcl script. This is useful to setup certain aspects of SDL, e.g. to start in full screen mode with or without changed display resolution (see description of SDL startup options in Beyond AndroWish). Another hook is /home/john/awish/app/icon.bmp which (if present) should be a Windows BMP 24 bit RGB bitmap file used as the icon for the SDL root window.