clang  3.9.0
VirtualFileSystem.h
Go to the documentation of this file.
1 //===- VirtualFileSystem.h - Virtual File System Layer ----------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 /// \file
10 /// \brief Defines the virtual file system interface vfs::FileSystem.
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
14 #define LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
15 
16 #include "clang/Basic/LLVM.h"
17 #include "llvm/ADT/IntrusiveRefCntPtr.h"
18 #include "llvm/ADT/Optional.h"
19 #include "llvm/Support/ErrorOr.h"
20 #include "llvm/Support/FileSystem.h"
21 #include "llvm/Support/SourceMgr.h"
22 #include "llvm/Support/raw_ostream.h"
23 #include <utility>
24 
25 namespace llvm {
26 class MemoryBuffer;
27 }
28 
29 namespace clang {
30 namespace vfs {
31 
32 /// \brief The result of a \p status operation.
33 class Status {
34  std::string Name;
35  llvm::sys::fs::UniqueID UID;
36  llvm::sys::TimeValue MTime;
37  uint32_t User;
38  uint32_t Group;
39  uint64_t Size;
40  llvm::sys::fs::file_type Type;
41  llvm::sys::fs::perms Perms;
42 
43 public:
44  bool IsVFSMapped; // FIXME: remove when files support multiple names
45 
46 public:
47  Status() : Type(llvm::sys::fs::file_type::status_error) {}
48  Status(const llvm::sys::fs::file_status &Status);
49  Status(StringRef Name, llvm::sys::fs::UniqueID UID,
50  llvm::sys::TimeValue MTime, uint32_t User, uint32_t Group,
51  uint64_t Size, llvm::sys::fs::file_type Type,
52  llvm::sys::fs::perms Perms);
53 
54  /// Get a copy of a Status with a different name.
55  static Status copyWithNewName(const Status &In, StringRef NewName);
56  static Status copyWithNewName(const llvm::sys::fs::file_status &In,
57  StringRef NewName);
58 
59  /// \brief Returns the name that should be used for this file or directory.
60  StringRef getName() const { return Name; }
61 
62  /// @name Status interface from llvm::sys::fs
63  /// @{
64  llvm::sys::fs::file_type getType() const { return Type; }
65  llvm::sys::fs::perms getPermissions() const { return Perms; }
66  llvm::sys::TimeValue getLastModificationTime() const { return MTime; }
67  llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
68  uint32_t getUser() const { return User; }
69  uint32_t getGroup() const { return Group; }
70  uint64_t getSize() const { return Size; }
71  /// @}
72  /// @name Status queries
73  /// These are static queries in llvm::sys::fs.
74  /// @{
75  bool equivalent(const Status &Other) const;
76  bool isDirectory() const;
77  bool isRegularFile() const;
78  bool isOther() const;
79  bool isSymlink() const;
80  bool isStatusKnown() const;
81  bool exists() const;
82  /// @}
83 };
84 
85 /// \brief Represents an open file.
86 class File {
87 public:
88  /// \brief Destroy the file after closing it (if open).
89  /// Sub-classes should generally call close() inside their destructors. We
90  /// cannot do that from the base class, since close is virtual.
91  virtual ~File();
92  /// \brief Get the status of the file.
93  virtual llvm::ErrorOr<Status> status() = 0;
94  /// \brief Get the name of the file
95  virtual llvm::ErrorOr<std::string> getName() {
96  if (auto Status = status())
97  return Status->getName().str();
98  else
99  return Status.getError();
100  }
101  /// \brief Get the contents of the file as a \p MemoryBuffer.
102  virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
103  getBuffer(const Twine &Name, int64_t FileSize = -1,
104  bool RequiresNullTerminator = true, bool IsVolatile = false) = 0;
105  /// \brief Closes the file.
106  virtual std::error_code close() = 0;
107 };
108 
109 namespace detail {
110 /// \brief An interface for virtual file systems to provide an iterator over the
111 /// (non-recursive) contents of a directory.
112 struct DirIterImpl {
113  virtual ~DirIterImpl();
114  /// \brief Sets \c CurrentEntry to the next entry in the directory on success,
115  /// or returns a system-defined \c error_code.
116  virtual std::error_code increment() = 0;
118 };
119 } // end namespace detail
120 
121 /// \brief An input iterator over the entries in a virtual path, similar to
122 /// llvm::sys::fs::directory_iterator.
124  std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
125 
126 public:
127  directory_iterator(std::shared_ptr<detail::DirIterImpl> I)
128  : Impl(std::move(I)) {
129  assert(Impl.get() != nullptr && "requires non-null implementation");
130  if (!Impl->CurrentEntry.isStatusKnown())
131  Impl.reset(); // Normalize the end iterator to Impl == nullptr.
132  }
133 
134  /// \brief Construct an 'end' iterator.
136 
137  /// \brief Equivalent to operator++, with an error code.
138  directory_iterator &increment(std::error_code &EC) {
139  assert(Impl && "attempting to increment past end");
140  EC = Impl->increment();
141  if (EC || !Impl->CurrentEntry.isStatusKnown())
142  Impl.reset(); // Normalize the end iterator to Impl == nullptr.
143  return *this;
144  }
145 
146  const Status &operator*() const { return Impl->CurrentEntry; }
147  const Status *operator->() const { return &Impl->CurrentEntry; }
148 
149  bool operator==(const directory_iterator &RHS) const {
150  if (Impl && RHS.Impl)
151  return Impl->CurrentEntry.equivalent(RHS.Impl->CurrentEntry);
152  return !Impl && !RHS.Impl;
153  }
154  bool operator!=(const directory_iterator &RHS) const {
155  return !(*this == RHS);
156  }
157 };
158 
159 class FileSystem;
160 
161 /// \brief An input iterator over the recursive contents of a virtual path,
162 /// similar to llvm::sys::fs::recursive_directory_iterator.
164  typedef std::stack<directory_iterator, std::vector<directory_iterator>>
165  IterState;
166 
167  FileSystem *FS;
168  std::shared_ptr<IterState> State; // Input iterator semantics on copy.
169 
170 public:
171  recursive_directory_iterator(FileSystem &FS, const Twine &Path,
172  std::error_code &EC);
173  /// \brief Construct an 'end' iterator.
175 
176  /// \brief Equivalent to operator++, with an error code.
177  recursive_directory_iterator &increment(std::error_code &EC);
178 
179  const Status &operator*() const { return *State->top(); }
180  const Status *operator->() const { return &*State->top(); }
181 
182  bool operator==(const recursive_directory_iterator &Other) const {
183  return State == Other.State; // identity
184  }
185  bool operator!=(const recursive_directory_iterator &RHS) const {
186  return !(*this == RHS);
187  }
188  /// \brief Gets the current level. Starting path is at level 0.
189  int level() const {
190  assert(State->size() && "Cannot get level without any iteration state");
191  return State->size()-1;
192  }
193 };
194 
195 /// \brief The virtual file system interface.
196 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
197 public:
198  virtual ~FileSystem();
199 
200  /// \brief Get the status of the entry at \p Path, if one exists.
201  virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;
202  /// \brief Get a \p File object for the file at \p Path, if one exists.
203  virtual llvm::ErrorOr<std::unique_ptr<File>>
204  openFileForRead(const Twine &Path) = 0;
205 
206  /// This is a convenience method that opens a file, gets its content and then
207  /// closes the file.
208  llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
209  getBufferForFile(const Twine &Name, int64_t FileSize = -1,
210  bool RequiresNullTerminator = true, bool IsVolatile = false);
211 
212  /// \brief Get a directory_iterator for \p Dir.
213  /// \note The 'end' iterator is directory_iterator().
214  virtual directory_iterator dir_begin(const Twine &Dir,
215  std::error_code &EC) = 0;
216 
217  /// Set the working directory. This will affect all following operations on
218  /// this file system and may propagate down for nested file systems.
219  virtual std::error_code setCurrentWorkingDirectory(const Twine &Path) = 0;
220  /// Get the working directory of this file system.
221  virtual llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const = 0;
222 
223  /// Check whether a file exists. Provided for convenience.
224  bool exists(const Twine &Path);
225 
226  /// Make \a Path an absolute path.
227  ///
228  /// Makes \a Path absolute using the current directory if it is not already.
229  /// An empty \a Path will result in the current directory.
230  ///
231  /// /absolute/path => /absolute/path
232  /// relative/../path => <current-directory>/relative/../path
233  ///
234  /// \param Path A path that is modified to be an absolute path.
235  /// \returns success if \a path has been made absolute, otherwise a
236  /// platform-specific error_code.
237  std::error_code makeAbsolute(SmallVectorImpl<char> &Path) const;
238 };
239 
240 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
241 /// the operating system.
243 
244 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
245 /// of another.
246 ///
247 /// Consists of a stack of >=1 \p FileSystem objects, which are treated as being
248 /// one merged file system. When there is a directory that exists in more than
249 /// one file system, the \p OverlayFileSystem contains a directory containing
250 /// the union of their contents. The attributes (permissions, etc.) of the
251 /// top-most (most recently added) directory are used. When there is a file
252 /// that exists in more than one file system, the file in the top-most file
253 /// system overrides the other(s).
256  /// \brief The stack of file systems, implemented as a list in order of
257  /// their addition.
258  FileSystemList FSList;
259 
260 public:
262  /// \brief Pushes a file system on top of the stack.
264 
265  llvm::ErrorOr<Status> status(const Twine &Path) override;
266  llvm::ErrorOr<std::unique_ptr<File>>
267  openFileForRead(const Twine &Path) override;
268  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
269  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;
270  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
271 
272  typedef FileSystemList::reverse_iterator iterator;
273 
274  /// \brief Get an iterator pointing to the most recently added file system.
275  iterator overlays_begin() { return FSList.rbegin(); }
276 
277  /// \brief Get an iterator pointing one-past the least recently added file
278  /// system.
279  iterator overlays_end() { return FSList.rend(); }
280 };
281 
282 namespace detail {
283 class InMemoryDirectory;
284 } // end namespace detail
285 
286 /// An in-memory file system.
288  std::unique_ptr<detail::InMemoryDirectory> Root;
289  std::string WorkingDirectory;
290  bool UseNormalizedPaths = true;
291 
292 public:
293  explicit InMemoryFileSystem(bool UseNormalizedPaths = true);
294  ~InMemoryFileSystem() override;
295  /// Add a buffer to the VFS with a path. The VFS owns the buffer.
296  /// \return true if the file was successfully added, false if the file already
297  /// exists in the file system with different contents.
298  bool addFile(const Twine &Path, time_t ModificationTime,
299  std::unique_ptr<llvm::MemoryBuffer> Buffer);
300  /// Add a buffer to the VFS with a path. The VFS does not own the buffer.
301  /// \return true if the file was successfully added, false if the file already
302  /// exists in the file system with different contents.
303  bool addFileNoOwn(const Twine &Path, time_t ModificationTime,
304  llvm::MemoryBuffer *Buffer);
305  std::string toString() const;
306  /// Return true if this file system normalizes . and .. in paths.
307  bool useNormalizedPaths() const { return UseNormalizedPaths; }
308 
309  llvm::ErrorOr<Status> status(const Twine &Path) override;
310  llvm::ErrorOr<std::unique_ptr<File>>
311  openFileForRead(const Twine &Path) override;
312  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
313  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
314  return WorkingDirectory;
315  }
316  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
317 };
318 
319 /// \brief Get a globally unique ID for a virtual file or directory.
320 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
321 
322 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
323 /// format.
325 getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,
326  llvm::SourceMgr::DiagHandlerTy DiagHandler,
327  StringRef YAMLFilePath,
328  void *DiagContext = nullptr,
330 
331 struct YAMLVFSEntry {
332  template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
333  : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
334  std::string VPath;
335  std::string RPath;
336 };
337 
339  std::vector<YAMLVFSEntry> Mappings;
340  Optional<bool> IsCaseSensitive;
341  Optional<bool> IsOverlayRelative;
342  Optional<bool> UseExternalNames;
343  std::string OverlayDir;
344 
345 public:
347  void addFileMapping(StringRef VirtualPath, StringRef RealPath);
348  void setCaseSensitivity(bool CaseSensitive) {
349  IsCaseSensitive = CaseSensitive;
350  }
351  void setUseExternalNames(bool UseExtNames) {
352  UseExternalNames = UseExtNames;
353  }
354  void setOverlayDir(StringRef OverlayDirectory) {
355  IsOverlayRelative = true;
356  OverlayDir.assign(OverlayDirectory.str());
357  }
358 
359  void write(llvm::raw_ostream &OS);
360 };
361 
362 } // end namespace vfs
363 } // end namespace clang
364 #endif
bool addFile(const Twine &Path, time_t ModificationTime, std::unique_ptr< llvm::MemoryBuffer > Buffer)
Add a buffer to the VFS with a path.
const Status * operator->() const
IntrusiveRefCntPtr< FileSystem > getRealFileSystem()
Gets an vfs::FileSystem for the 'real' file system, as seen by the operating system.
void setOverlayDir(StringRef OverlayDirectory)
virtual llvm::ErrorOr< Status > status()=0
Get the status of the file.
The base class of the type hierarchy.
Definition: Type.h:1281
bool equivalent(const Status &Other) const
std::unique_ptr< llvm::MemoryBuffer > Buffer
bool isStatusKnown() const
uint32_t getUser() const
llvm::sys::TimeValue getLastModificationTime() const
virtual llvm::ErrorOr< std::unique_ptr< llvm::MemoryBuffer > > getBuffer(const Twine &Name, int64_t FileSize=-1, bool RequiresNullTerminator=true, bool IsVolatile=false)=0
Get the contents of the file as a MemoryBuffer.
virtual llvm::ErrorOr< std::unique_ptr< File > > openFileForRead(const Twine &Path)=0
Get a File object for the file at Path, if one exists.
virtual directory_iterator dir_begin(const Twine &Dir, std::error_code &EC)=0
Get a directory_iterator for Dir.
bool useNormalizedPaths() const
Return true if this file system normalizes . and .. in paths.
The virtual file system interface.
llvm::ErrorOr< std::string > getCurrentWorkingDirectory() const override
Get the working directory of this file system.
class LLVM_ALIGNAS(8) DependentTemplateSpecializationType const IdentifierInfo * Name
Represents a template specialization type whose template cannot be resolved, e.g. ...
Definition: Type.h:4549
void write(llvm::raw_ostream &OS)
virtual std::error_code close()=0
Closes the file.
IntrusiveRefCntPtr< FileSystem > getVFSFromYAML(std::unique_ptr< llvm::MemoryBuffer > Buffer, llvm::SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath, void *DiagContext=nullptr, IntrusiveRefCntPtr< FileSystem > ExternalFS=getRealFileSystem())
Gets a FileSystem for a virtual file system described in YAML format.
An input iterator over the recursive contents of a virtual path, similar to llvm::sys::fs::recursive_...
directory_iterator(std::shared_ptr< detail::DirIterImpl > I)
An in-memory file system.
directory_iterator()
Construct an 'end' iterator.
directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override
Get a directory_iterator for Dir.
bool addFileNoOwn(const Twine &Path, time_t ModificationTime, llvm::MemoryBuffer *Buffer)
Add a buffer to the VFS with a path.
directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override
Get a directory_iterator for Dir.
A file system that allows overlaying one AbstractFileSystem on top of another.
virtual llvm::ErrorOr< Status > status(const Twine &Path)=0
Get the status of the entry at Path, if one exists.
directory_iterator & increment(std::error_code &EC)
Equivalent to operator++, with an error code.
llvm::sys::fs::file_type getType() const
void addFileMapping(StringRef VirtualPath, StringRef RealPath)
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
bool operator!=(const recursive_directory_iterator &RHS) const
FileSystemList::reverse_iterator iterator
llvm::ErrorOr< std::unique_ptr< File > > openFileForRead(const Twine &Path) override
Get a File object for the file at Path, if one exists.
The result of a status operation.
void pushOverlay(IntrusiveRefCntPtr< FileSystem > FS)
Pushes a file system on top of the stack.
detail::InMemoryDirectory::const_iterator I
recursive_directory_iterator()
Construct an 'end' iterator.
virtual std::error_code setCurrentWorkingDirectory(const Twine &Path)=0
Set the working directory.
llvm::sys::fs::UniqueID getUniqueID() const
virtual llvm::ErrorOr< std::string > getCurrentWorkingDirectory() const =0
Get the working directory of this file system.
static Status copyWithNewName(const Status &In, StringRef NewName)
Get a copy of a Status with a different name.
iterator overlays_end()
Get an iterator pointing one-past the least recently added file system.
uint64_t getSize() const
Represents an open file.
void setCaseSensitivity(bool CaseSensitive)
llvm::ErrorOr< std::string > getCurrentWorkingDirectory() const override
Get the working directory of this file system.
virtual llvm::ErrorOr< std::string > getName()
Get the name of the file.
InMemoryFileSystem(bool UseNormalizedPaths=true)
recursive_directory_iterator & increment(std::error_code &EC)
Equivalent to operator++, with an error code.
bool operator!=(const directory_iterator &RHS) const
llvm::ErrorOr< std::unique_ptr< File > > openFileForRead(const Twine &Path) override
Get a File object for the file at Path, if one exists.
uint32_t getGroup() const
iterator overlays_begin()
Get an iterator pointing to the most recently added file system.
bool isDirectory() const
YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
std::error_code setCurrentWorkingDirectory(const Twine &Path) override
Set the working directory.
bool isRegularFile() const
int level() const
Gets the current level. Starting path is at level 0.
bool operator==(const directory_iterator &RHS) const
llvm::sys::fs::perms getPermissions() const
OverlayFileSystem(IntrusiveRefCntPtr< FileSystem > Base)
llvm::sys::fs::UniqueID getNextVirtualUniqueID()
Get a globally unique ID for a virtual file or directory.
const Status & operator*() const
bool exists(const Twine &Path)
Check whether a file exists. Provided for convenience.
void setUseExternalNames(bool UseExtNames)
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...
StringRef getName() const
Returns the name that should be used for this file or directory.
virtual ~File()
Destroy the file after closing it (if open).
An input iterator over the entries in a virtual path, similar to llvm::sys::fs::directory_iterator.
llvm::ErrorOr< Status > status(const Twine &Path) override
Get the status of the entry at Path, if one exists.
std::error_code setCurrentWorkingDirectory(const Twine &Path) override
Set the working directory.
bool operator==(const recursive_directory_iterator &Other) const
An interface for virtual file systems to provide an iterator over the (non-recursive) contents of a d...
llvm::ErrorOr< Status > status(const Twine &Path) override
Get the status of the entry at Path, if one exists.
virtual std::error_code increment()=0
Sets CurrentEntry to the next entry in the directory on success, or returns a system-defined error_co...
std::error_code makeAbsolute(SmallVectorImpl< char > &Path) const
Make Path an absolute path.