clang  6.0.0svn
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/ADT/SmallVector.h"
20 #include "llvm/ADT/StringRef.h"
21 #include "llvm/ADT/Twine.h"
22 #include "llvm/Support/Chrono.h"
23 #include "llvm/Support/ErrorOr.h"
24 #include "llvm/Support/FileSystem.h"
25 #include "llvm/Support/SourceMgr.h"
26 #include "llvm/Support/raw_ostream.h"
27 #include <algorithm>
28 #include <cassert>
29 #include <cstdint>
30 #include <ctime>
31 #include <memory>
32 #include <stack>
33 #include <string>
34 #include <system_error>
35 #include <utility>
36 #include <vector>
37 
38 namespace llvm {
39 
40 class MemoryBuffer;
41 
42 } // end namespace llvm
43 
44 namespace clang {
45 namespace vfs {
46 
47 /// \brief The result of a \p status operation.
48 class Status {
49  std::string Name;
50  llvm::sys::fs::UniqueID UID;
51  llvm::sys::TimePoint<> MTime;
52  uint32_t User;
53  uint32_t Group;
54  uint64_t Size;
55  llvm::sys::fs::file_type Type;
56  llvm::sys::fs::perms Perms;
57 
58 public:
59  bool IsVFSMapped; // FIXME: remove when files support multiple names
60 
61 public:
62  Status() : Type(llvm::sys::fs::file_type::status_error) {}
63  Status(const llvm::sys::fs::file_status &Status);
64  Status(StringRef Name, llvm::sys::fs::UniqueID UID,
65  llvm::sys::TimePoint<> MTime, uint32_t User, uint32_t Group,
66  uint64_t Size, llvm::sys::fs::file_type Type,
67  llvm::sys::fs::perms Perms);
68 
69  /// Get a copy of a Status with a different name.
70  static Status copyWithNewName(const Status &In, StringRef NewName);
71  static Status copyWithNewName(const llvm::sys::fs::file_status &In,
72  StringRef NewName);
73 
74  /// \brief Returns the name that should be used for this file or directory.
75  StringRef getName() const { return Name; }
76 
77  /// @name Status interface from llvm::sys::fs
78  /// @{
79  llvm::sys::fs::file_type getType() const { return Type; }
80  llvm::sys::fs::perms getPermissions() const { return Perms; }
81  llvm::sys::TimePoint<> getLastModificationTime() const { return MTime; }
82  llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
83  uint32_t getUser() const { return User; }
84  uint32_t getGroup() const { return Group; }
85  uint64_t getSize() const { return Size; }
86  /// @}
87  /// @name Status queries
88  /// These are static queries in llvm::sys::fs.
89  /// @{
90  bool equivalent(const Status &Other) const;
91  bool isDirectory() const;
92  bool isRegularFile() const;
93  bool isOther() const;
94  bool isSymlink() const;
95  bool isStatusKnown() const;
96  bool exists() const;
97  /// @}
98 };
99 
100 /// \brief Represents an open file.
101 class File {
102 public:
103  /// \brief Destroy the file after closing it (if open).
104  /// Sub-classes should generally call close() inside their destructors. We
105  /// cannot do that from the base class, since close is virtual.
106  virtual ~File();
107 
108  /// \brief Get the status of the file.
109  virtual llvm::ErrorOr<Status> status() = 0;
110 
111  /// \brief Get the name of the file
112  virtual llvm::ErrorOr<std::string> getName() {
113  if (auto Status = status())
114  return Status->getName().str();
115  else
116  return Status.getError();
117  }
118 
119  /// \brief Get the contents of the file as a \p MemoryBuffer.
120  virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
121  getBuffer(const Twine &Name, int64_t FileSize = -1,
122  bool RequiresNullTerminator = true, bool IsVolatile = false) = 0;
123 
124  /// \brief Closes the file.
125  virtual std::error_code close() = 0;
126 };
127 
128 namespace detail {
129 
130 /// \brief An interface for virtual file systems to provide an iterator over the
131 /// (non-recursive) contents of a directory.
132 struct DirIterImpl {
133  virtual ~DirIterImpl();
134 
135  /// \brief Sets \c CurrentEntry to the next entry in the directory on success,
136  /// or returns a system-defined \c error_code.
137  virtual std::error_code increment() = 0;
138 
140 };
141 
142 } // end namespace detail
143 
144 /// \brief An input iterator over the entries in a virtual path, similar to
145 /// llvm::sys::fs::directory_iterator.
147  std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
148 
149 public:
150  directory_iterator(std::shared_ptr<detail::DirIterImpl> I)
151  : Impl(std::move(I)) {
152  assert(Impl.get() != nullptr && "requires non-null implementation");
153  if (!Impl->CurrentEntry.isStatusKnown())
154  Impl.reset(); // Normalize the end iterator to Impl == nullptr.
155  }
156 
157  /// \brief Construct an 'end' iterator.
158  directory_iterator() = default;
159 
160  /// \brief Equivalent to operator++, with an error code.
161  directory_iterator &increment(std::error_code &EC) {
162  assert(Impl && "attempting to increment past end");
163  EC = Impl->increment();
164  if (!Impl->CurrentEntry.isStatusKnown())
165  Impl.reset(); // Normalize the end iterator to Impl == nullptr.
166  return *this;
167  }
168 
169  const Status &operator*() const { return Impl->CurrentEntry; }
170  const Status *operator->() const { return &Impl->CurrentEntry; }
171 
172  bool operator==(const directory_iterator &RHS) const {
173  if (Impl && RHS.Impl)
174  return Impl->CurrentEntry.equivalent(RHS.Impl->CurrentEntry);
175  return !Impl && !RHS.Impl;
176  }
177  bool operator!=(const directory_iterator &RHS) const {
178  return !(*this == RHS);
179  }
180 };
181 
182 class FileSystem;
183 
184 /// \brief An input iterator over the recursive contents of a virtual path,
185 /// similar to llvm::sys::fs::recursive_directory_iterator.
187  typedef std::stack<directory_iterator, std::vector<directory_iterator>>
188  IterState;
189 
190  FileSystem *FS;
191  std::shared_ptr<IterState> State; // Input iterator semantics on copy.
192 
193 public:
194  recursive_directory_iterator(FileSystem &FS, const Twine &Path,
195  std::error_code &EC);
196  /// \brief Construct an 'end' iterator.
197  recursive_directory_iterator() = default;
198 
199  /// \brief Equivalent to operator++, with an error code.
200  recursive_directory_iterator &increment(std::error_code &EC);
201 
202  const Status &operator*() const { return *State->top(); }
203  const Status *operator->() const { return &*State->top(); }
204 
205  bool operator==(const recursive_directory_iterator &Other) const {
206  return State == Other.State; // identity
207  }
208  bool operator!=(const recursive_directory_iterator &RHS) const {
209  return !(*this == RHS);
210  }
211 
212  /// \brief Gets the current level. Starting path is at level 0.
213  int level() const {
214  assert(State->size() && "Cannot get level without any iteration state");
215  return State->size()-1;
216  }
217 };
218 
219 /// \brief The virtual file system interface.
220 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
221 public:
222  virtual ~FileSystem();
223 
224  /// \brief Get the status of the entry at \p Path, if one exists.
225  virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;
226  /// \brief Get a \p File object for the file at \p Path, if one exists.
227  virtual llvm::ErrorOr<std::unique_ptr<File>>
228  openFileForRead(const Twine &Path) = 0;
229 
230  /// This is a convenience method that opens a file, gets its content and then
231  /// closes the file.
232  llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
233  getBufferForFile(const Twine &Name, int64_t FileSize = -1,
234  bool RequiresNullTerminator = true, bool IsVolatile = false);
235 
236  /// \brief Get a directory_iterator for \p Dir.
237  /// \note The 'end' iterator is directory_iterator().
238  virtual directory_iterator dir_begin(const Twine &Dir,
239  std::error_code &EC) = 0;
240 
241  /// Set the working directory. This will affect all following operations on
242  /// this file system and may propagate down for nested file systems.
243  virtual std::error_code setCurrentWorkingDirectory(const Twine &Path) = 0;
244  /// Get the working directory of this file system.
245  virtual llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const = 0;
246 
247  /// Check whether a file exists. Provided for convenience.
248  bool exists(const Twine &Path);
249 
250  /// Make \a Path an absolute path.
251  ///
252  /// Makes \a Path absolute using the current directory if it is not already.
253  /// An empty \a Path will result in the current directory.
254  ///
255  /// /absolute/path => /absolute/path
256  /// relative/../path => <current-directory>/relative/../path
257  ///
258  /// \param Path A path that is modified to be an absolute path.
259  /// \returns success if \a path has been made absolute, otherwise a
260  /// platform-specific error_code.
261  std::error_code makeAbsolute(SmallVectorImpl<char> &Path) const;
262 };
263 
264 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
265 /// the operating system.
267 
268 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
269 /// of another.
270 ///
271 /// Consists of a stack of >=1 \p FileSystem objects, which are treated as being
272 /// one merged file system. When there is a directory that exists in more than
273 /// one file system, the \p OverlayFileSystem contains a directory containing
274 /// the union of their contents. The attributes (permissions, etc.) of the
275 /// top-most (most recently added) directory are used. When there is a file
276 /// that exists in more than one file system, the file in the top-most file
277 /// system overrides the other(s).
280  /// \brief The stack of file systems, implemented as a list in order of
281  /// their addition.
282  FileSystemList FSList;
283 
284 public:
286  /// \brief Pushes a file system on top of the stack.
287  void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
288 
289  llvm::ErrorOr<Status> status(const Twine &Path) override;
290  llvm::ErrorOr<std::unique_ptr<File>>
291  openFileForRead(const Twine &Path) override;
292  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
293  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;
294  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
295 
296  typedef FileSystemList::reverse_iterator iterator;
297 
298  /// \brief Get an iterator pointing to the most recently added file system.
299  iterator overlays_begin() { return FSList.rbegin(); }
300 
301  /// \brief Get an iterator pointing one-past the least recently added file
302  /// system.
303  iterator overlays_end() { return FSList.rend(); }
304 };
305 
306 namespace detail {
307 
308 class InMemoryDirectory;
309 
310 } // end namespace detail
311 
312 /// An in-memory file system.
314  std::unique_ptr<detail::InMemoryDirectory> Root;
315  std::string WorkingDirectory;
316  bool UseNormalizedPaths = true;
317 
318 public:
319  explicit InMemoryFileSystem(bool UseNormalizedPaths = true);
320  ~InMemoryFileSystem() override;
321 
322  /// Add a file containing a buffer or a directory to the VFS with a
323  /// path. The VFS owns the buffer. If present, User, Group, Type
324  /// and Perms apply to the newly-created file or directory.
325  /// \return true if the file or directory was successfully added,
326  /// false if the file or directory already exists in the file system with
327  /// different contents.
328  bool addFile(const Twine &Path, time_t ModificationTime,
329  std::unique_ptr<llvm::MemoryBuffer> Buffer,
330  Optional<uint32_t> User = None, Optional<uint32_t> Group = None,
332  Optional<llvm::sys::fs::perms> Perms = None);
333  /// Add a buffer to the VFS with a path. The VFS does not own the buffer.
334  /// If present, User, Group, Type and Perms apply to the newly-created file
335  /// or directory.
336  /// \return true if the file or directory was successfully added,
337  /// false if the file or directory already exists in the file system with
338  /// different contents.
339  bool addFileNoOwn(const Twine &Path, time_t ModificationTime,
340  llvm::MemoryBuffer *Buffer,
341  Optional<uint32_t> User = None,
342  Optional<uint32_t> Group = None,
344  Optional<llvm::sys::fs::perms> Perms = None);
345 
346  std::string toString() const;
347  /// Return true if this file system normalizes . and .. in paths.
348  bool useNormalizedPaths() const { return UseNormalizedPaths; }
349 
350  llvm::ErrorOr<Status> status(const Twine &Path) override;
351  llvm::ErrorOr<std::unique_ptr<File>>
352  openFileForRead(const Twine &Path) override;
353  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
354  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
355  return WorkingDirectory;
356  }
357  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
358 };
359 
360 /// \brief Get a globally unique ID for a virtual file or directory.
361 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
362 
363 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
364 /// format.
366 getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,
367  llvm::SourceMgr::DiagHandlerTy DiagHandler,
368  StringRef YAMLFilePath,
369  void *DiagContext = nullptr,
371 
372 struct YAMLVFSEntry {
373  template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
374  : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
375  std::string VPath;
376  std::string RPath;
377 };
378 
379 /// \brief Collect all pairs of <virtual path, real path> entries from the
380 /// \p YAMLFilePath. This is used by the module dependency collector to forward
381 /// the entries into the reproducer output VFS YAML file.
382 void collectVFSFromYAML(
383  std::unique_ptr<llvm::MemoryBuffer> Buffer,
384  llvm::SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath,
385  SmallVectorImpl<YAMLVFSEntry> &CollectedEntries,
386  void *DiagContext = nullptr,
388 
390  std::vector<YAMLVFSEntry> Mappings;
391  Optional<bool> IsCaseSensitive;
392  Optional<bool> IsOverlayRelative;
393  Optional<bool> UseExternalNames;
394  Optional<bool> IgnoreNonExistentContents;
395  std::string OverlayDir;
396 
397 public:
398  YAMLVFSWriter() = default;
399 
400  void addFileMapping(StringRef VirtualPath, StringRef RealPath);
401 
402  void setCaseSensitivity(bool CaseSensitive) {
403  IsCaseSensitive = CaseSensitive;
404  }
405 
406  void setUseExternalNames(bool UseExtNames) {
407  UseExternalNames = UseExtNames;
408  }
409 
410  void setIgnoreNonExistentContents(bool IgnoreContents) {
411  IgnoreNonExistentContents = IgnoreContents;
412  }
413 
414  void setOverlayDir(StringRef OverlayDirectory) {
415  IsOverlayRelative = true;
416  OverlayDir.assign(OverlayDirectory.str());
417  }
418 
419  void write(llvm::raw_ostream &OS);
420 };
421 
422 } // end namespace vfs
423 } // end namespace clang
424 
425 #endif // LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
DominatorTree GraphTraits specialization so the DominatorTree can be iterable by generic graph iterat...
Definition: Dominators.h:26
IntrusiveRefCntPtr< FileSystem > getRealFileSystem()
Gets an vfs::FileSystem for the &#39;real&#39; file system, as seen by the operating system.
void setOverlayDir(StringRef OverlayDirectory)
llvm::sys::fs::perms getPermissions() const
The base class of the type hierarchy.
Definition: Type.h:1353
StringRef getName() const
Returns the name that should be used for this file or directory.
void setIgnoreNonExistentContents(bool IgnoreContents)
uint32_t getUser() const
bool operator==(const recursive_directory_iterator &Other) const
The virtual file system interface.
llvm::ErrorOr< std::string > getCurrentWorkingDirectory() const override
Get the working directory of this file system.
LineState State
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.
Definition: Format.h:1900
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.
bool useNormalizedPaths() const
Return true if this file system normalizes . and .. in paths.
A file system that allows overlaying one AbstractFileSystem on top of another.
directory_iterator & increment(std::error_code &EC)
Equivalent to operator++, with an error code.
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified...
int level() const
Gets the current level. Starting path is at level 0.
FileSystemList::reverse_iterator iterator
The result of a status operation.
const Status * operator->() const
iterator overlays_end()
Get an iterator pointing one-past the least recently added file system.
Represents an open file.
void setCaseSensitivity(bool CaseSensitive)
virtual llvm::ErrorOr< std::string > getName()
Get the name of the file.
llvm::sys::fs::file_type getType() const
void collectVFSFromYAML(std::unique_ptr< llvm::MemoryBuffer > Buffer, llvm::SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath, SmallVectorImpl< YAMLVFSEntry > &CollectedEntries, void *DiagContext=nullptr, IntrusiveRefCntPtr< FileSystem > ExternalFS=getRealFileSystem())
Collect all pairs of <virtual path, real path> entries from the YAMLFilePath.
iterator overlays_begin()
Get an iterator pointing to the most recently added file system.
llvm::sys::TimePoint getLastModificationTime() const
YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
Dataflow Directional Tag Classes.
uint64_t getSize() const
llvm::sys::fs::UniqueID getNextVirtualUniqueID()
Get a globally unique ID for a virtual file or directory.
bool operator==(const directory_iterator &RHS) const
std::string toString(const til::SExpr *E)
void setUseExternalNames(bool UseExtNames)
llvm::sys::fs::UniqueID getUniqueID() const
const Status & operator*() const
An input iterator over the entries in a virtual path, similar to llvm::sys::fs::directory_iterator.
An interface for virtual file systems to provide an iterator over the (non-recursive) contents of a d...
bool operator!=(const directory_iterator &RHS) const
uint32_t getGroup() const
bool operator!=(const recursive_directory_iterator &RHS) const