contrib/llvm/tools/clang/include/clang/Basic/VirtualFileSystem.h

   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
 139   Status CurrentEntry;
 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.
 146 class 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 (EC || !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.
 186 class 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.
 266 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
 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).
 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
 281   /// their addition.
 282   FileSystemList FSList;
 283
 284 public:
 285   OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
 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.
 313 class InMemoryFileSystem : public FileSystem {
 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 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; }
 335
 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;
 342   }
 343   std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
 344 };
 345
 346 /// \brief Get a globally unique ID for a virtual file or directory.
 347 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
 348
 349 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
 350 /// format.
 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());
 357
 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)) {}
 361   std::string VPath;
 362   std::string RPath;
 363 };
 364
 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());
 374
 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;
 382
 383 public:
 384   YAMLVFSWriter() = default;
 385
 386   void addFileMapping(StringRef VirtualPath, StringRef RealPath);
 387
 388   void setCaseSensitivity(bool CaseSensitive) {
 389     IsCaseSensitive = CaseSensitive;
 390   }
 391
 392   void setUseExternalNames(bool UseExtNames) {
 393     UseExternalNames = UseExtNames;
 394   }
 395
 396   void setIgnoreNonExistentContents(bool IgnoreContents) {
 397     IgnoreNonExistentContents = IgnoreContents;
 398   }
 399
 400   void setOverlayDir(StringRef OverlayDirectory) {
 401     IsOverlayRelative = true;
 402     OverlayDir.assign(OverlayDirectory.str());
 403   }
 404
 405   void write(llvm::raw_ostream &OS);
 406 };
 407
 408 } // end namespace vfs
 409 } // end namespace clang
 410
 411 #endif // LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H