A virtual file system parsed from a YAML file. More...

#include "llvm/Support/VirtualFileSystem.h"

Inheritance diagram for llvm::vfs::RedirectingFileSystem:

[legend]

Classes
class	DirectoryEntry
	A directory in the vfs with explicitly specified contents. More...

class	DirectoryRemapEntry
	A directory in the vfs that maps to a directory in the external file system. More...

class	Entry
	A single file or directory in the VFS. More...

class	FileEntry
	A file in the vfs that maps to a file in the external file system. More...

struct	LookupResult
	Represents the result of a path lookup into the RedirectingFileSystem. More...

class	RemapEntry
	A file or directory in the vfs that is mapped to a file or directory in the external filesystem. More...

Public Types
enum	EntryKind { EK_Directory , EK_DirectoryRemap , EK_File }

enum	NameKind { NK_NotSet , NK_External , NK_Virtual }

enum class	RedirectKind { Fallthrough , Fallback , RedirectOnly }
	The type of redirection to perform. More...

enum class	RootRelativeKind { CWD , OverlayDir }
	The type of relative path used by Roots. More...

Public Types inherited from llvm::vfs::FileSystem
enum class	PrintType { Summary , Contents , RecursiveContents }

using	VisitCallbackTy = llvm::function_ref< void(FileSystem &)>

Public Member Functions
ErrorOr< LookupResult >	lookupPath (StringRef Path) const
	Looks up `Path` in `Roots` and returns a LookupResult giving the matched entry and, if the entry was a FileEntry or DirectoryRemapEntry, the path it redirects to in the external file system.

ErrorOr< Status >	status (const Twine &Path) override
	Get the status of the entry at `Path`, if one exists.

bool	exists (const Twine &Path) override
	Check whether `Path` exists.

ErrorOr< std::unique_ptr< File > >	openFileForRead (const Twine &Path) override
	Get a `File` object for the text file at `Path`, if one exists.

std::error_code	getRealPath (const Twine &Path, SmallVectorImpl< char > &Output) override
	Gets real path of `Path` e.g.

llvm::ErrorOr< std::string >	getCurrentWorkingDirectory () const override
	Get the working directory of this file system.

std::error_code	setCurrentWorkingDirectory (const Twine &Path) override
	Set the working directory.

std::error_code	isLocal (const Twine &Path, bool &Result) override
	Is the file mounted on a local filesystem?

std::error_code	makeAbsolute (SmallVectorImpl< char > &Path) const override
	Make Path an absolute path.

directory_iterator	dir_begin (const Twine &Dir, std::error_code &EC) override
	Get a directory_iterator for `Dir`.

void	setOverlayFileDir (StringRef PrefixDir)

StringRef	getOverlayFileDir () const

void	setFallthrough (bool Fallthrough)
	Sets the redirection kind to `Fallthrough` if true or `RedirectOnly` otherwise.

void	setRedirection (RedirectingFileSystem::RedirectKind Kind)

std::vector< llvm::StringRef >	getRoots () const

bool	hasBeenUsed () const

void	clearHasBeenUsed ()

void	setUsageTrackingActive (bool Active)

void	printEntry (raw_ostream &OS, Entry *E, unsigned IndentLevel=0) const

Public Member Functions inherited from llvm::RTTIExtends< RedirectingFileSystem, vfs::FileSystem >
const void *	dynamicClassID () const override

bool	isA () const
	Check whether this instance is a subclass of QueryT.

bool	isA (const void *const ClassID) const override

Public Member Functions inherited from llvm::vfs::FileSystem
virtual	~FileSystem ()

virtual llvm::ErrorOr< Status >	status (const Twine &Path)=0
	Get the status of the entry at `Path`, if one exists.

virtual llvm::ErrorOr< std::unique_ptr< File > >	openFileForRead (const Twine &Path)=0
	Get a `File` object for the text file at `Path`, if one exists.

virtual llvm::ErrorOr< std::unique_ptr< File > >	openFileForReadBinary (const Twine &Path)
	Get a `File` object for the binary file at `Path`, if one exists.

llvm::ErrorOr< std::unique_ptr< llvm::MemoryBuffer > >	getBufferForFile (const Twine &Name, int64_t FileSize=-1, bool RequiresNullTerminator=true, bool IsVolatile=false, bool IsText=true)
	This is a convenience method that opens a file, gets its content and then closes the file.

virtual directory_iterator	dir_begin (const Twine &Dir, std::error_code &EC)=0
	Get a directory_iterator for `Dir`.

virtual std::error_code	setCurrentWorkingDirectory (const Twine &Path)=0
	Set the working directory.

virtual llvm::ErrorOr< std::string >	getCurrentWorkingDirectory () const =0
	Get the working directory of this file system.

virtual std::error_code	getRealPath (const Twine &Path, SmallVectorImpl< char > &Output)
	Gets real path of `Path` e.g.

virtual bool	exists (const Twine &Path)
	Check whether `Path` exists.

virtual std::error_code	isLocal (const Twine &Path, bool &Result)
	Is the file mounted on a local filesystem?

virtual std::error_code	makeAbsolute (SmallVectorImpl< char > &Path) const
	Make Path an absolute path.

llvm::ErrorOr< bool >	equivalent (const Twine &A, const Twine &B)

void	print (raw_ostream &OS, PrintType Type=PrintType::Contents, unsigned IndentLevel=0) const

virtual void	visitChildFileSystems (VisitCallbackTy Callback)

void	visit (VisitCallbackTy Callback)

LLVM_DUMP_METHOD void	dump () const

Public Member Functions inherited from llvm::ThreadSafeRefCountedBase< FileSystem >
unsigned	UseCount () const

void	Retain () const

void	Release () const

Public Member Functions inherited from llvm::RTTIExtends< FileSystem, RTTIRoot >
const void *	dynamicClassID () const override

bool	isA () const
	Check whether this instance is a subclass of QueryT.

bool	isA (const void *const ClassID) const override

Public Member Functions inherited from llvm::RTTIRoot
virtual	~RTTIRoot ()=default

virtual const void *	dynamicClassID () const =0
	Returns the class ID for the dynamic type of this RTTIRoot instance.

virtual bool	isA (const void *const ClassID) const
	Returns true if this class's ID matches the given class ID.

Static Public Member Functions
static std::unique_ptr< RedirectingFileSystem >	create (std::unique_ptr< MemoryBuffer > Buffer, SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath, void *DiagContext, IntrusiveRefCntPtr< FileSystem > ExternalFS)
	Parses `Buffer`, which is expected to be in YAML format and returns a virtual file system representing its contents.

static std::unique_ptr< RedirectingFileSystem >	create (ArrayRef< std::pair< std::string, std::string > > RemappedFiles, bool UseExternalNames, FileSystem &ExternalFS)
	Redirect each of the remapped files from first to second.

Static Public Member Functions inherited from llvm::RTTIExtends< RedirectingFileSystem, vfs::FileSystem >
static const void *	classID ()

static bool	classof (const T *R)

Static Public Member Functions inherited from llvm::RTTIExtends< FileSystem, RTTIRoot >
static const void *	classID ()

static bool	classof (const T *R)

Static Public Member Functions inherited from llvm::RTTIRoot
static const void *	classID ()
	Returns the class ID for this type.

Static Public Attributes
static const char	ID = 0

Static Public Attributes inherited from llvm::vfs::FileSystem
static const char	ID = 0

Protected Member Functions
void	printImpl (raw_ostream &OS, PrintType Type, unsigned IndentLevel) const override

void	visitChildFileSystems (VisitCallbackTy Callback) override

Protected Member Functions inherited from llvm::vfs::FileSystem
virtual void	printImpl (raw_ostream &OS, PrintType Type, unsigned IndentLevel) const

void	printIndent (raw_ostream &OS, unsigned IndentLevel) const

Protected Member Functions inherited from llvm::ThreadSafeRefCountedBase< FileSystem >
	ThreadSafeRefCountedBase ()=default

	ThreadSafeRefCountedBase (const ThreadSafeRefCountedBase &)

ThreadSafeRefCountedBase &	operator= (const ThreadSafeRefCountedBase &)=delete

	~ThreadSafeRefCountedBase ()

Friends
class	RedirectingFSDirIterImpl

class	RedirectingFileSystemParser

Detailed Description

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': <version number>,
///   <optional configuration>
///   'roots': [
///              <directory entries>
///            ]
/// }
///

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': <string>,
///   'contents': [ <file or directory entries> ]
/// }
///

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': <string>,
///   'use-external-name': <boolean>, # Optional
///   'external-contents': <path to external directory>
/// }
///

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': <string>,
///   'use-external-name': <boolean>, # Optional
///   'external-contents': <path to external file>
/// }
///

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.

Member Enumeration Documentation

◆ EntryKind

enum llvm::vfs::RedirectingFileSystem::EntryKind

Enumerator
EK_Directory
EK_DirectoryRemap
EK_File

Definition at line 781 of file VirtualFileSystem.h.

◆ NameKind

enum llvm::vfs::RedirectingFileSystem::NameKind

Enumerator
NK_NotSet
NK_External
NK_Virtual

Definition at line 782 of file VirtualFileSystem.h.

◆ RedirectKind

enum class llvm::vfs::RedirectingFileSystem::RedirectKind

strong

The type of redirection to perform.

Enumerator

Fallthrough

Lookup the redirected path first (ie.

the one specified in 'external-contents') and if that fails "fallthrough" to a lookup of the originally provided path.

Fallback

Lookup the provided path first and if that fails, "fallback" to a lookup of the redirected path.

RedirectOnly

Only lookup the redirected path, do not lookup the originally provided path.

Definition at line 785 of file VirtualFileSystem.h.

◆ RootRelativeKind

enum class llvm::vfs::RedirectingFileSystem::RootRelativeKind

strong

The type of relative path used by Roots.

Enumerator
CWD	The roots are relative to the current working directory.
OverlayDir	The roots are relative to the directory where the Overlay YAML file.

Definition at line 799 of file VirtualFileSystem.h.

Member Function Documentation

◆ clearHasBeenUsed()

void llvm::vfs::RedirectingFileSystem::clearHasBeenUsed ( )

inline

Definition at line 1095 of file VirtualFileSystem.h.

◆ create() [1/2]

std::unique_ptr< RedirectingFileSystem > RedirectingFileSystem::create	(	ArrayRef< std::pair< std::string, std::string > >	RemappedFiles,
		bool	UseExternalNames,
		FileSystem &	ExternalFS
	)

static

Redirect each of the remapped files from first to second.

Definition at line 2217 of file VirtualFileSystem.cpp.

References assert(), llvm::sys::path::begin(), llvm::sys::path::end(), llvm::sys::path::filename(), From, I, llvm::vfs::RedirectingFileSystemParser::lookupOrCreateEntry(), llvm::vfs::FileSystem::makeAbsolute(), NK_External, NK_Virtual, llvm::sys::path::parent_path(), and llvm::reverse().

◆ create() [2/2]

std::unique_ptr< RedirectingFileSystem > RedirectingFileSystem::create	(	std::unique_ptr< MemoryBuffer >	Buffer,
		SourceMgr::DiagHandlerTy	DiagHandler,
		StringRef	YAMLFilePath,
		void *	DiagContext,
		IntrusiveRefCntPtr< FileSystem >	ExternalFS
	)

static

Parses Buffer, which is expected to be in YAML format and returns a virtual file system representing its contents.

Definition at line 2175 of file VirtualFileSystem.cpp.

References assert(), llvm::yaml::Stream::begin(), DiagHandler(), llvm::SourceMgr::DK_Error, llvm::StringRef::empty(), llvm::yaml::Stream::end(), llvm::sys::fs::make_absolute(), P, llvm::sys::path::parent_path(), llvm::SourceMgr::PrintMessage(), and llvm::SourceMgr::setDiagHandler().

◆ dir_begin()

directory_iterator RedirectingFileSystem::dir_begin	(	const Twine &	Dir,
		std::error_code &	EC
	)

overridevirtual

Get a directory_iterator for Dir.

Note: The 'end' iterator is directory_iterator().

Implements llvm::vfs::FileSystem.

Definition at line 1438 of file VirtualFileSystem.cpp.

References Fallback, Fallthrough, llvm::ErrorOr< T >::getError(), llvm_unreachable, lookupPath(), llvm::no_such_file_or_directory, llvm::not_a_directory, llvm::SmallVectorTemplateBase< T, bool >::push_back(), RedirectOnly, and llvm::Twine::toVector().

◆ exists()

bool RedirectingFileSystem::exists ( const Twine & Path )

overridevirtual

Check whether Path exists.

By default this uses status(), but filesystems may provide a more efficient implementation if available.

Reimplemented from llvm::vfs::FileSystem.

Definition at line 2463 of file VirtualFileSystem.cpp.

References assert(), Fallback, Fallthrough, lookupPath(), and llvm::Twine::toVector().

Referenced by setCurrentWorkingDirectory().

◆ getCurrentWorkingDirectory()

llvm::ErrorOr< std::string > RedirectingFileSystem::getCurrentWorkingDirectory ( ) const

overridevirtual

Get the working directory of this file system.

Implements llvm::vfs::FileSystem.

Definition at line 1353 of file VirtualFileSystem.cpp.

Referenced by makeAbsolute().

◆ getOverlayFileDir()

StringRef RedirectingFileSystem::getOverlayFileDir ( ) const

Definition at line 1542 of file VirtualFileSystem.cpp.

◆ getRealPath()

std::error_code RedirectingFileSystem::getRealPath	(	const Twine &	Path,
		SmallVectorImpl< char > &	Output
	)

overridevirtual

Gets real path of Path e.g.

collapse all . and .. patterns, resolve symlinks. For real file system, this uses llvm::sys::fs::real_path. This returns errc::operation_not_permitted if not implemented by subclass.

Reimplemented from llvm::vfs::FileSystem.

Definition at line 2613 of file VirtualFileSystem.cpp.

References Fallback, Fallthrough, llvm::invalid_argument, lookupPath(), P, and llvm::Twine::toVector().

◆ getRoots()

std::vector< StringRef > RedirectingFileSystem::getRoots ( ) const

Definition at line 1559 of file VirtualFileSystem.cpp.

◆ hasBeenUsed()

bool llvm::vfs::RedirectingFileSystem::hasBeenUsed ( ) const

inline

Definition at line 1094 of file VirtualFileSystem.h.

◆ isLocal()

std::error_code RedirectingFileSystem::isLocal	(	const Twine &	Path,
		bool &	Result
	)

overridevirtual

Is the file mounted on a local filesystem?

Reimplemented from llvm::vfs::FileSystem.

Definition at line 1371 of file VirtualFileSystem.cpp.

References llvm::Twine::toVector().

◆ lookupPath()

ErrorOr< RedirectingFileSystem::LookupResult > RedirectingFileSystem::lookupPath ( StringRef Path ) const

Looks up Path in Roots and returns a LookupResult giving the matched entry and, if the entry was a FileEntry or DirectoryRemapEntry, the path it redirects to in the external file system.

Definition at line 2308 of file VirtualFileSystem.cpp.

References llvm::sys::path::begin(), End, llvm::sys::path::end(), llvm::make_error_code(), llvm::no_such_file_or_directory, and RedirectOnly.

Referenced by dir_begin(), exists(), getRealPath(), openFileForRead(), and status().