LLVM 20.0.0git
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
llvm::vfs::RedirectingFileSystem Class Reference

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

#include "llvm/Support/VirtualFileSystem.h"

Inheritance diagram for llvm::vfs::RedirectingFileSystem:
Inheritance graph
[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< LookupResultlookupPath (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< Statusstatus (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 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::StringRefgetRoots () 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 void *const ClassID) const override
 
- Public Member Functions inherited from llvm::vfs::FileSystem
virtual ~FileSystem ()
 
virtual llvm::ErrorOr< Statusstatus (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 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)
 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< boolequivalent (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
 
const void * dynamicClassID () const override
 
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.
 
template<typename QueryT >
bool isA () const
 Check whether this instance is a subclass of QueryT.
 

Static Public Member Functions

static std::unique_ptr< RedirectingFileSystemcreate (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< RedirectingFileSystemcreate (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 RTTIRoot *R)
 
- Static Public Member Functions inherited from llvm::RTTIExtends< FileSystem, RTTIRoot >
static const void * classID ()
 
static bool classof (const RTTIRoot *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 &)
 
ThreadSafeRefCountedBaseoperator= (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 764 of file VirtualFileSystem.h.

Member Enumeration Documentation

◆ EntryKind

Enumerator
EK_Directory 
EK_DirectoryRemap 
EK_File 

Definition at line 768 of file VirtualFileSystem.h.

◆ NameKind

Enumerator
NK_NotSet 
NK_External 
NK_Virtual 

Definition at line 769 of file VirtualFileSystem.h.

◆ RedirectKind

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 772 of file VirtualFileSystem.h.

◆ RootRelativeKind

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 786 of file VirtualFileSystem.h.

Member Function Documentation

◆ clearHasBeenUsed()

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

Definition at line 1082 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

◆ 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 2163 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

◆ 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 2451 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 1341 of file VirtualFileSystem.cpp.

Referenced by makeAbsolute().

◆ getOverlayFileDir()

StringRef RedirectingFileSystem::getOverlayFileDir ( ) const

Definition at line 1530 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 2601 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 1547 of file VirtualFileSystem.cpp.

◆ hasBeenUsed()

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

Definition at line 1081 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 1359 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 2296 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().

◆ makeAbsolute()

std::error_code RedirectingFileSystem::makeAbsolute ( SmallVectorImpl< char > &  Path) const
overridevirtual

Make Path an absolute path.

Makes Path absolute using the current directory if it is not already. An empty Path will result in the current directory.

/absolute/path => /absolute/path relative/../path => <current-directory>/relative/../path

Parameters
PathA path that is modified to be an absolute path.
Returns
success if path has been made absolute, otherwise a platform-specific error_code.

Reimplemented from llvm::vfs::FileSystem.

Definition at line 1370 of file VirtualFileSystem.cpp.

References getCurrentWorkingDirectory(), llvm::sys::path::is_absolute(), llvm::sys::path::posix, and llvm::sys::path::windows_backslash.

◆ openFileForRead()

ErrorOr< std::unique_ptr< File > > RedirectingFileSystem::openFileForRead ( const Twine Path)
overridevirtual

◆ printEntry()

void RedirectingFileSystem::printEntry ( raw_ostream OS,
RedirectingFileSystem::Entry E,
unsigned  IndentLevel = 0 
) const

◆ printImpl()

void RedirectingFileSystem::printImpl ( raw_ostream OS,
PrintType  Type,
unsigned  IndentLevel 
) const
overrideprotectedvirtual

◆ setCurrentWorkingDirectory()

std::error_code RedirectingFileSystem::setCurrentWorkingDirectory ( const Twine Path)
overridevirtual

Set the working directory.

This will affect all following operations on this file system and may propagate down for nested file systems.

Implements llvm::vfs::FileSystem.

Definition at line 1346 of file VirtualFileSystem.cpp.

References exists(), and llvm::no_such_file_or_directory.

◆ setFallthrough()

void RedirectingFileSystem::setFallthrough ( bool  Fallthrough)

Sets the redirection kind to Fallthrough if true or RedirectOnly otherwise.

Will removed in the future, use setRedirection instead.

Definition at line 1534 of file VirtualFileSystem.cpp.

References Fallthrough, and RedirectOnly.

◆ setOverlayFileDir()

void RedirectingFileSystem::setOverlayFileDir ( StringRef  PrefixDir)

Definition at line 1526 of file VirtualFileSystem.cpp.

References llvm::StringRef::str().

◆ setRedirection()

void RedirectingFileSystem::setRedirection ( RedirectingFileSystem::RedirectKind  Kind)

Definition at line 1542 of file VirtualFileSystem.cpp.

◆ setUsageTrackingActive()

void llvm::vfs::RedirectingFileSystem::setUsageTrackingActive ( bool  Active)
inline

Definition at line 1084 of file VirtualFileSystem.h.

◆ status()

ErrorOr< Status > RedirectingFileSystem::status ( const Twine Path)
overridevirtual

Get the status of the entry at Path, if one exists.

Implements llvm::vfs::FileSystem.

Definition at line 2414 of file VirtualFileSystem.cpp.

References Fallback, Fallthrough, llvm::ErrorOr< T >::getError(), lookupPath(), and llvm::Twine::toVector().

◆ visitChildFileSystems()

void RedirectingFileSystem::visitChildFileSystems ( VisitCallbackTy  Callback)
overrideprotectedvirtual

Reimplemented from llvm::vfs::FileSystem.

Definition at line 1608 of file VirtualFileSystem.cpp.

Friends And Related Function Documentation

◆ RedirectingFileSystemParser

friend class RedirectingFileSystemParser
friend

Definition at line 933 of file VirtualFileSystem.h.

◆ RedirectingFSDirIterImpl

friend class RedirectingFSDirIterImpl
friend

Definition at line 932 of file VirtualFileSystem.h.

Member Data Documentation

◆ ID

const char RedirectingFileSystem::ID = 0
static

Definition at line 767 of file VirtualFileSystem.h.


The documentation for this class was generated from the following files: