• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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:
Status()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.
getName()60   StringRef getName() const { return Name; }
61 
62   /// @name Status interface from llvm::sys::fs
63   /// @{
getType()64   llvm::sys::fs::file_type getType() const { return Type; }
getPermissions()65   llvm::sys::fs::perms getPermissions() const { return Perms; }
getLastModificationTime()66   llvm::sys::TimeValue getLastModificationTime() const { return MTime; }
getUniqueID()67   llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
getUser()68   uint32_t getUser() const { return User; }
getGroup()69   uint32_t getGroup() const { return Group; }
getSize()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
getName()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;
117   Status CurrentEntry;
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.
123 class directory_iterator {
124   std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
125 
126 public:
directory_iterator(std::shared_ptr<detail::DirIterImpl> I)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.
directory_iterator()135   directory_iterator() { }
136 
137   /// \brief Equivalent to operator++, with an error code.
increment(std::error_code & EC)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.
163 class 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.
recursive_directory_iterator()174   recursive_directory_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.
level()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.
242 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
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).
254 class OverlayFileSystem : public FileSystem {
255   typedef SmallVector<IntrusiveRefCntPtr<FileSystem>, 1> FileSystemList;
256   /// \brief The stack of file systems, implemented as a list in order of
257   /// their addition.
258   FileSystemList FSList;
259 
260 public:
261   OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
262   /// \brief Pushes a file system on top of the stack.
263   void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
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.
overlays_begin()275   iterator overlays_begin() { return FSList.rbegin(); }
276 
277   /// \brief Get an iterator pointing one-past the least recently added file
278   /// system.
overlays_end()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.
287 class InMemoryFileSystem : public FileSystem {
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.
useNormalizedPaths()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;
getCurrentWorkingDirectory()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.
324 IntrusiveRefCntPtr<FileSystem>
325 getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,
326                llvm::SourceMgr::DiagHandlerTy DiagHandler,
327                StringRef YAMLFilePath,
328                void *DiagContext = nullptr,
329                IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
330 
331 struct YAMLVFSEntry {
YAMLVFSEntryYAMLVFSEntry332   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 
338 class YAMLVFSWriter {
339   std::vector<YAMLVFSEntry> Mappings;
340   Optional<bool> IsCaseSensitive;
341   Optional<bool> IsOverlayRelative;
342   Optional<bool> UseExternalNames;
343   std::string OverlayDir;
344 
345 public:
YAMLVFSWriter()346   YAMLVFSWriter() {}
347   void addFileMapping(StringRef VirtualPath, StringRef RealPath);
setCaseSensitivity(bool CaseSensitive)348   void setCaseSensitivity(bool CaseSensitive) {
349     IsCaseSensitive = CaseSensitive;
350   }
setUseExternalNames(bool UseExtNames)351   void setUseExternalNames(bool UseExtNames) {
352     UseExternalNames = UseExtNames;
353   }
setOverlayDir(StringRef OverlayDirectory)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
365