LLVM: llvm::vfs::RedirectingFileSystem Class Reference (original) (raw)

A virtual file system parsed from a YAML file.

Currently, this class allows creating virtual files and directories. Virtual files map to existing external files in ExternalFS, and virtual directories may either map to existing directories in ExternalFS or list their contents in the form of other virtual directories and/or files.

The basic structure of the parsed file is:

/// { /// 'version': , /// /// 'roots': [ /// /// ] /// } ///

The roots may be absolute or relative. If relative they will be made absolute against either current working directory or the directory where the Overlay YAML file is located, depending on the 'root-relative' configuration.

All configuration options are optional. 'case-sensitive': <boolean, default=(true for Posix, false for Windows)> 'use-external-names': <boolean, default=true> 'root-relative': <string, one of 'cwd' or 'overlay-dir', default='cwd'> 'overlay-relative': <boolean, default=false> 'fallthrough': <boolean, default=true, deprecated - use 'redirecting-with' instead> 'redirecting-with': <string, one of 'fallthrough', 'fallback', or 'redirect-only', default='fallthrough'>

To clarify, 'root-relative' option will prepend the current working directory, or the overlay directory to the 'roots->name' field only if 'roots->name' is a relative path. On the other hand, when 'overlay-relative' is set to 'true', external paths will always be prepended with the overlay directory, even if external paths are not relative paths. The 'root-relative' option has no interaction with the 'overlay-relative' option.

Virtual directories that list their contents are represented as

/// { /// 'type': 'directory', /// 'name': , /// 'contents': [ ] /// } ///

The default attributes for such virtual directories are:

/// MTime = now() when created /// Perms = 0777 /// User = Group = 0 /// Size = 0 /// UniqueID = unspecified unique value ///

When a path prefix matches such a directory, the next component in the path is matched against the entries in the 'contents' array.

Re-mapped directories, on the other hand, are represented as ///

/// { /// 'type': 'directory-remap', /// 'name': , /// 'use-external-name': , # Optional /// 'external-contents': /// } ///

and inherit their attributes from the external directory. When a path prefix matches such an entry, the unmatched components are appended to the 'external-contents' path, and the resulting path is looked up in the external file system instead.

Re-mapped files are represented as

/// { /// 'type': 'file', /// 'name': , /// 'use-external-name': , # Optional /// 'external-contents': /// } ///

Their attributes and file contents are determined by looking up the file at their 'external-contents' path in the external file system.

For 'file', 'directory' and 'directory-remap' entries the 'name' field may contain multiple path components (e.g. /path/to/file). However, any directory in such a path that contains more than one child must be uniquely represented by a 'directory' entry.

When the 'use-external-name' field is set, calls to vfs::File::status() give the external (remapped) filesystem name instead of the name the file was accessed by. This is an intentional leak through the RedirectingFileSystem abstraction layer. It enables clients to discover (and use) the external file location when communicating with users or tools that don't use the same VFS overlay.

FIXME: 'use-external-name' causes behaviour that's inconsistent with how "real" filesystems behave. Maybe there should be a separate channel for this information.

Definition at line 777 of file VirtualFileSystem.h.