1 //===- VirtualFileSystem.h - Virtual File System Layer ----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 /// \brief Defines the virtual file system interface vfs::FileSystem.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
14 #define LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
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"
34 #include <system_error>
42 } // end namespace llvm
47 /// \brief The result of a \p status operation.
50 llvm::sys::fs::UniqueID UID;
51 llvm::sys::TimePoint<> MTime;
55 llvm::sys::fs::file_type Type;
56 llvm::sys::fs::perms Perms;
59 bool IsVFSMapped; // FIXME: remove when files support multiple names
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);
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,
74 /// \brief Returns the name that should be used for this file or directory.
75 StringRef getName() const { return Name; }
77 /// @name Status interface from llvm::sys::fs
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; }
87 /// @name Status queries
88 /// These are static queries in llvm::sys::fs.
90 bool equivalent(const Status &Other) const;
91 bool isDirectory() const;
92 bool isRegularFile() const;
94 bool isSymlink() const;
95 bool isStatusKnown() const;
100 /// \brief Represents an open file.
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.
108 /// \brief Get the status of the file.
109 virtual llvm::ErrorOr<Status> status() = 0;
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();
116 return Status.getError();
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;
124 /// \brief Closes the file.
125 virtual std::error_code close() = 0;
130 /// \brief An interface for virtual file systems to provide an iterator over the
131 /// (non-recursive) contents of a directory.
133 virtual ~DirIterImpl();
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;
142 } // end namespace detail
144 /// \brief An input iterator over the entries in a virtual path, similar to
145 /// llvm::sys::fs::directory_iterator.
146 class directory_iterator {
147 std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
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.
157 /// \brief Construct an 'end' iterator.
158 directory_iterator() = default;
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 (EC || !Impl->CurrentEntry.isStatusKnown())
165 Impl.reset(); // Normalize the end iterator to Impl == nullptr.
169 const Status &operator*() const { return Impl->CurrentEntry; }
170 const Status *operator->() const { return &Impl->CurrentEntry; }
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;
177 bool operator!=(const directory_iterator &RHS) const {
178 return !(*this == RHS);
184 /// \brief An input iterator over the recursive contents of a virtual path,
185 /// similar to llvm::sys::fs::recursive_directory_iterator.
186 class recursive_directory_iterator {
187 typedef std::stack<directory_iterator, std::vector<directory_iterator>>
191 std::shared_ptr<IterState> State; // Input iterator semantics on copy.
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;
199 /// \brief Equivalent to operator++, with an error code.
200 recursive_directory_iterator &increment(std::error_code &EC);
202 const Status &operator*() const { return *State->top(); }
203 const Status *operator->() const { return &*State->top(); }
205 bool operator==(const recursive_directory_iterator &Other) const {
206 return State == Other.State; // identity
208 bool operator!=(const recursive_directory_iterator &RHS) const {
209 return !(*this == RHS);
212 /// \brief Gets the current level. Starting path is at level 0.
214 assert(State->size() && "Cannot get level without any iteration state");
215 return State->size()-1;
219 /// \brief The virtual file system interface.
220 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
222 virtual ~FileSystem();
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;
230 /// This is a convenience method that opens a file, gets its content and then
232 llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
233 getBufferForFile(const Twine &Name, int64_t FileSize = -1,
234 bool RequiresNullTerminator = true, bool IsVolatile = false);
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;
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;
247 /// Check whether a file exists. Provided for convenience.
248 bool exists(const Twine &Path);
250 /// Make \a Path an absolute path.
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.
255 /// /absolute/path => /absolute/path
256 /// relative/../path => <current-directory>/relative/../path
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;
264 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
265 /// the operating system.
266 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
268 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
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).
278 class OverlayFileSystem : public FileSystem {
279 typedef SmallVector<IntrusiveRefCntPtr<FileSystem>, 1> FileSystemList;
280 /// \brief The stack of file systems, implemented as a list in order of
282 FileSystemList FSList;
285 OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
286 /// \brief Pushes a file system on top of the stack.
287 void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
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;
296 typedef FileSystemList::reverse_iterator iterator;
298 /// \brief Get an iterator pointing to the most recently added file system.
299 iterator overlays_begin() { return FSList.rbegin(); }
301 /// \brief Get an iterator pointing one-past the least recently added file
303 iterator overlays_end() { return FSList.rend(); }
308 class InMemoryDirectory;
310 } // end namespace detail
312 /// An in-memory file system.
313 class InMemoryFileSystem : public FileSystem {
314 std::unique_ptr<detail::InMemoryDirectory> Root;
315 std::string WorkingDirectory;
316 bool UseNormalizedPaths = true;
319 explicit InMemoryFileSystem(bool UseNormalizedPaths = true);
320 ~InMemoryFileSystem() override;
322 /// Add a buffer to the VFS with a path. The VFS owns the buffer.
323 /// \return true if the file was successfully added, false if the file already
324 /// exists in the file system with different contents.
325 bool addFile(const Twine &Path, time_t ModificationTime,
326 std::unique_ptr<llvm::MemoryBuffer> Buffer);
327 /// Add a buffer to the VFS with a path. The VFS does not own the buffer.
328 /// \return true if the file was successfully added, false if the file already
329 /// exists in the file system with different contents.
330 bool addFileNoOwn(const Twine &Path, time_t ModificationTime,
331 llvm::MemoryBuffer *Buffer);
332 std::string toString() const;
333 /// Return true if this file system normalizes . and .. in paths.
334 bool useNormalizedPaths() const { return UseNormalizedPaths; }
336 llvm::ErrorOr<Status> status(const Twine &Path) override;
337 llvm::ErrorOr<std::unique_ptr<File>>
338 openFileForRead(const Twine &Path) override;
339 directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
340 llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
341 return WorkingDirectory;
343 std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
346 /// \brief Get a globally unique ID for a virtual file or directory.
347 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
349 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
351 IntrusiveRefCntPtr<FileSystem>
352 getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,
353 llvm::SourceMgr::DiagHandlerTy DiagHandler,
354 StringRef YAMLFilePath,
355 void *DiagContext = nullptr,
356 IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
358 struct YAMLVFSEntry {
359 template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
360 : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
365 /// \brief Collect all pairs of <virtual path, real path> entries from the
366 /// \p YAMLFilePath. This is used by the module dependency collector to forward
367 /// the entries into the reproducer output VFS YAML file.
368 void collectVFSFromYAML(
369 std::unique_ptr<llvm::MemoryBuffer> Buffer,
370 llvm::SourceMgr::DiagHandlerTy DiagHandler, StringRef YAMLFilePath,
371 SmallVectorImpl<YAMLVFSEntry> &CollectedEntries,
372 void *DiagContext = nullptr,
373 IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
375 class YAMLVFSWriter {
376 std::vector<YAMLVFSEntry> Mappings;
377 Optional<bool> IsCaseSensitive;
378 Optional<bool> IsOverlayRelative;
379 Optional<bool> UseExternalNames;
380 Optional<bool> IgnoreNonExistentContents;
381 std::string OverlayDir;
384 YAMLVFSWriter() = default;
386 void addFileMapping(StringRef VirtualPath, StringRef RealPath);
388 void setCaseSensitivity(bool CaseSensitive) {
389 IsCaseSensitive = CaseSensitive;
392 void setUseExternalNames(bool UseExtNames) {
393 UseExternalNames = UseExtNames;
396 void setIgnoreNonExistentContents(bool IgnoreContents) {
397 IgnoreNonExistentContents = IgnoreContents;
400 void setOverlayDir(StringRef OverlayDirectory) {
401 IsOverlayRelative = true;
402 OverlayDir.assign(OverlayDirectory.str());
405 void write(llvm::raw_ostream &OS);
408 } // end namespace vfs
409 } // end namespace clang
411 #endif // LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H