| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When the VFS plugin is loaded, it searches for a configuration file named `vfs.cfg' in the following locations in the order shown:
csGetResourceDir().)
csGetAppDir().)
csGetConfigPath().)
The full set of directories mounted by VFS after it scans for configuration files is the union of the entries in all of the discovered `vfs.cfg' files. If there are conflicting entries, then mounts and variable assignments specified in configuration files discovered earlier in the scan take precedence over those discovered later.
Keys in the `vfs.cfg' configuration file with names starting with `VFS.Mount.' describe the layout of the virtual file system. Imagine a clean disk drive onto which you start to create directories by making links to existing real directories and archive (`.zip') files. An archive is treated exactly like a subdirectory; you even can link one "virtual directory" to several "real" paths and archives; however if you write files they will be written to the first directory or archive in list.
These keys present a list of virtual-to-real path mappings. The local name of a key with the `VFS.Mount.' prefix define the virtual directory, and the values define the real paths, which can represent a list of physical directories and ZIP archives. The physical directory path lists should be separated by commas (,), therefore commas cannot be used in directory names. This should not be much of a restriction, but if it is a problem for a particular platform, you may want to take the drastic action of changing `VFS_PATH_DIVIDER' macro in `vfs.cpp'.
The `VFS.Mount.' values typically makes heavy use of variables since
most operating systems have different pathname semantics and syntax. The
"common denominator" that VFS emulates is a Unix-like filesystem. To
include the value of a variable in a VFS path use the
`$(variable-name)' construct. In the case where
`variable-name' consists of a single letter, you can omit the
parentheses, as in $variable-name (for example `$A').
Variables that are defined in the environment override those defined in this file. For example, the `$HOME' environment variable is set in all Unixes, but is undefined in many other operating systems. They can define their own values for these variables in system-dependent sections, but if the user defines the `$HOME' environment variable it will always override the one from this file. You also can refer the variables in the following way: `$(var:expr)' which means "use the contents of `var' if `var' is set (usually in environment), or use `expr' if not". This can be used for more complex expressions, for example:
$(HOME:$(HOMEDIR:$(HOMEPATH:/home))) |
This expression means "take the value of the `$HOME' variable; if it is not set, use the contents of `$HOMEDIR'; if it is also not set, use `$HOMEPATH'; and if none are set, use the literal string `/home' as the resulting value.
VFS defines a pseudo-variable named `/' that contains the path delimiter for the current operating system (i.e. `/' for Unix and MacOS/X, and `\' for Windows/DOS). You reference this variable by writing `$/' rather than using the "real-world" delimiters `/', or `\'.
Here is the complete list of pseudo-variables understood by VFS:
$/Platform-specific path delimiter; `/' on Unix and MacOS/X; `\' on Windows.
$@Crystal Space installation directory.
$*Application resource directory; typically, the directory in which the application executable resides but, on MacOS/X, it is the `Resources' directory within the Cocoa application wrapper for GUI programs.
$^Directory where application executable resides, or the directory where Cocoa application wrapper resides on MacOS/X.
The following is an example VFS configuration file.
Assume we wrote a game with three levels; the game is located on CD-ROM and we want to be able to release patches in the future which will replace several files from level archives (each level is presumed to be placed in a separate ZIP archive on either CD-ROM or cached on the hard drive). Additionally, we will add a link to user's home directory (something somewhat vaguely defined on non-Unix platforms) so that game can store the user's settings into the file `~/game.profile'.
Note that in this example many of the options in the real `vfs.cfg' are omitted. So you should not take this example for your game, because one of the libraries or plug-in modules you use may require a mapping that is not listed here. This example is only intended to understand the concept:
;;; Virtual File System mount table ;;; ;;; $/ -- path delimiter (i.e. "/" on Unix; "\" on Windows) ;;; $@ -- installation directory of Crystal Space ;;; $* -- application resource directory ;;; $^ -- directory in which application resides ;;; The expansions of $@, $*, and $^ always have a trailing ;;; path delimiter. ; ; The following variables should be defined either in ; the environment or in system-dependent sections: ; ; $CD - The path to CD-ROM. ; $HOME - user's home directory ; ; A common error is to omit the last $/ from directories. ; This is an error since VFS will treat any path not ending ; in $/ as an archive file name and not as a physical ; directory. ; Mount points. (These are split over multiple lines in order to ; fit correctly on a printed page in the documentation. In real ; life, the values would appear immediately after the `=' signs!) VFS.Mount.~ = $(HOME)$/ VFS.Mount.map1 = $*$/patch$/map1$/, $*$/cache$/map1.zip, $(CD)$/data$/map1.zip VFS.Mount.map2 = $*$/patch$/map2$/, $*$/cache$/map2.zip, $(CD)$/data$/map2.zip VFS.Mount.map3 = $*$/patch$/map3$/, $*$/cache$/map3.zip, $(CD)$/data$/map3.zip ; Platform aliases. Aliases are always read first; VFS ; entries specific to each platform override those defined ; in the platform alias section. For example, if your ; current platform is MacOS/X, VFS will look for the value ; of a variable first in the environment, then in ; VFS.MacOS/X., and finally in VFS.Unix. (as specified in ; section below). ; Unix-style filesystems VFS.Alias.Unix = VFS.Unix VFS.Alias.MacOS/X = VFS.Unix ; CP/M-style filesystems VFS.Alias.Win32 = VFS.CP/M VFS.Alias.DOS = VFS.CP/M ; Strange key names follow: ; VFS.Unix.. means key '.' in section VFS.Unix.* ; VFS.Unix... means key '..' in section VFS.Unix.* VFS.Unix.. = . VFS.Unix... = .. VFS.Unix.CDROM = /mnt/cdrom VFS.Unix.TMP = /tmp VFS.CP/M.. = . VFS.CP/M... = .. VFS.CP/M.HOME = $(HOMEDIR:$(HOMEPATH:.)) VFS.CP/M.CDROM = x: VFS.CP/M.TMP = $(TEMP:$(TMP:$(SYSTEMROOT)$/temp)) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated using texi2html 1.76.