1Hello! The code here has evolved from ideas and excellent work by Matt 2Newman, Jean-Claude Wippler, TclKit etc. To make this really successful, 3we need a group of volunteers to enhance what we have and build a new way 4of writing and distributing Tcl code. 5 6Introduction 7------------ 8 9This is an implementation of a 'vfs' extension (and a 'vfs' package, 10including a small library of Tcl code). The goal of this extension 11is to expose Tcl 8.4's new filesystem C API to the Tcl level. 12 13Using this extension, the editor Alphatk can actually auto-mount, 14view and edit (but not save, since they're read-only) the contents of 15.zip files directly (see <http://www.purl.org/net/alphatk/>), and you 16can do things like: 17 18 file copy ftp://ftp.foo.com/pub/readme.txt . 19 20With 'Tkhtml' and this extension, writing a web-browser in Tcl should be 21pretty trivial. 22 23None of the vfs's included are 100% complete or optimal yet, so if only for 24that reason, code contributions are very welcome. Many of them still 25contain various debugging code, etc. This will be gradually removed and 26the code completely cleaned up and documented as the package evolves. 27 28-- Vince Darley, April 2002-February 2003 29 30Compile/build 31------------- 32 33The standard 'configure ; make ; make install' should work, but if it 34doesn't, I'm afraid I can't help --- I am not an expert on these issues 35and find it amazing that to compile a single C file (generic/vfs.c) a 36dozen or so TEA 'helper' files are required. I believe 'gmake' may 37be required on some platforms. 38 39For windows, there is a VC++ makefile in the win directory ('nmake -f 40makefile.vc') should do the trick. 41 42Tests and installation 43---------------------- 44 45The tests/vfs*.test files should all pass (provided you have an active 46internet connection). 47 48To install, you probably want to rename the directory 'library' to 'vfs1.0' 49and place it in your Tcl hierarchy, with the necessary shared library inside 50(improvements to makefiles to streamline this much appreciated). On Windows 51'nmake -f makefile.vc install' should do everything for you. 52 53Current implementation 54---------------------- 55 56Some of the provided vfs's require the Memchan extension for any operation 57which involves opening files. The zip vfs also require 'Trf' (for its 58'zip' command). 59 60The vfs's currently available are: 61 62package vfs::ftp 1.0 63package vfs::http 0.5 64package vfs::mk4 1.6 65package vfs::ns 0.5 66package vfs::tar 0.9 67package vfs::test 1.0 68package vfs::urltype 1.0 69package vfs::webdav 0.1 70package vfs::zip 1.0 71 72--------+----------------------------------------------------------------- 73vfs | example mount command 74--------+----------------------------------------------------------------- 75zip | vfs::zip::Mount my.zip local 76ftp | vfs::ftp::Mount ftp://user:pass@ftp.foo.com/dir/name/ local 77mk4 | vfs::mk4::Mount myMk4database local 78urltype | vfs::urltype::Mount ftp 79test | vfs::test::Mount ... 80--------+----------------------------------------------------------------- 81 82These are also available, but not so heavily debugged: 83 84--------+----------------------------------------------------------------- 85ns | vfs::ns::Mount ::tcl local 86webdav | vfs::webdav::Mount http://user:pass@foo.com/blah local 87http | vfs::http::Mount http://foo.com/blah local 88--------+----------------------------------------------------------------- 89 90For file-systems which make use of a local file (e.g. mounting zip or mk4 91archives), it is often most simple to have 'local' be the same name as 92the archive itself. The result of this is that Tcl will then see the 93archive as a directory, rather than a file. Otherwise you might wish 94to create a dummy file/directory called 'local' before mounting. 95 96C versus Tcl 97------------ 98 99It may be worth writing a vfs for commonly used formats like 'zip' in C. 100This would make it easier to create single-file executables because with 101this extension we have a bootstrap problem: to mount the executable 102(assuming it has a .zip archive appended to it) we need to have 103'vfs::zip::Mount' and related procedures loaded, but this means that those 104procedures would have to be stored in the executable outside the zip 105archive, wasting space. 106 107Note: Richard Hipp has written 'zvfs' which uses the older, less-complete 108vfs support in Tcl 8.3. It is GNU-licensed, which makes distributing binary 109versions a little more complex. Also Prowrap contains a similar zip-vfs 110implementation using the same old APIs (it is BSD-licensed). Either of 111these can probably be modified to work with the new APIs quite easily. 112 113Helping! 114-------- 115 116Any help is much appreciated! The current code has very much _evolved_ 117which means it isn't necessarily even particular well thought out, so if 118you wish to contribute a single line of code or a complete re-write, I'd be 119very happy! 120 121Future thoughts 122--------------- 123 124See: 125 126http://developer.gnome.org/doc/API/gnome-vfs/ 127http://www.appwatch.com/lists/gnome-announce/2001-May/000267.html 128http://www.lh.com/~oleg/ftp/HTTP-VFS.html 129http://www.atnf.csiro.au/~rgooch/linux/vfs.txt 130 131for some ideas. It would be good to accumulate ideas on the limitations of 132the current VFS support so we can plan out what vfs 2.0 will look like (and 133what changes will be needed in Tcl's core to support it). 134 135"Asynchronicity" -- Obvious things which come to mind are asynchronicity: 136'file copy' from a mounted remote site (ftp or http) is going to be very 137slow and simply block the application. Commands like that should have new 138asynchronous versions which can be used when desired (for example, 'file 139copy from to -callback foo' would be one approach to handling this). 140 141"exec" -- this Tcl command effectively boils down to forking off a variety 142of processes and hooking their input/output/errors up appropriately. Most 143of this code is quite generic, and ends up in 'TclpCreateProcess' for the 144actual forking and execution of another process (whose name is given by 145'argv[0]' in TclpCreateProcess). Would it be possible to make a 146Tcl_FSCreateProcess which can pass the command on either to the native 147filesystem or to virtual filesystems? The simpler answer is "yes", given 148that we can simply examine 'argv[0]' and see if it is it is a path in a 149virtual filesystem and then hand it off appropriately, but could a vfs 150actually implement anything sensible? The kind of thing I'm thinking of is 151this: we mount an ftp site and would then like to execute various ftp 152commands directly. Now, we could use 'ftp::Quote' (from the ftp package) to 153send commands directly, but why not 'exec' them? If my ftp site is mounted 154at /tcl/ftppub, why couldn't "exec /tcl/ftppub FOO arg1 arg2" attempt a 155verbatim "FOO arg1 arg2" command on the ftp connection? (Or would perhaps 156"exec /tcl/ftppub/FOO arg1 arg2" be the command?). Similarly a Tcl 157'namespace' filesystem could use 'exec' to evaluate code in the relevant 158namespace (of course you could just use 'namespace eval' directly, but then 159you couldn't hook the code up to input/output pipes). 160 161Debugging virtual filesystems 162----------------------------- 163 164Bugs in Tcl vfs's are hard to track down, since error _messages_ can't 165necessarily propagate to the toplevel (errors of course do propagate and 166result in a filesystem action failing, but informative error messages cannot 167usually be provided, since Tcl is only expecting one of the standard POSIX 168error codes). We could add a debugging command to this extension so 169unexpected errors are logged somewhere. Alternatively the 'reporting' 170filesystem in Tcl's test suite can be used to aid debugging. 171 172