include/llvm/Bytecode/Archive.h

   1 //===-- llvm/Bytecode/Archive.h - LLVM Bytecode Archive ---------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This header file defines the interface to LLVM Archive files. The interface
  11 // is provided by the Archive class implemented by the lib/Bytecode/Archive
  12 // library.  This library is used to read and write archive (*.a) files that
  13 // contain LLVM bytecode files (or others). It provides rudimentary capabilities
  14 // to construct an archive file from a set of files, read the archive members
  15 // into memory, search the archive for member files that fulfill unresolved
  16 // symbols, and extract the archive back to the file system.  Full
  17 // symbol table support is provided for loading only those files that resolve
  18 // symbols. Note that read performance of this library is _crucial_ for
  19 // performance of JIT type applications and the linkers. Consequently, the
  20 // library is optimized for reading.
  21 //
  22 //===----------------------------------------------------------------------===//
  23
  24 #ifndef LLVM_BYTECODE_ARCHIVE_H
  25 #define LLVM_BYTECODE_ARCHIVE_H
  26
  27 #include "llvm/System/Path.h"
  28 #include <map>
  29
  30 namespace llvm {
  31
  32 class ModuleProvider;
  33 class Module;
  34
  35 /// This class represents an archive file. It abstracts away the file format,
  36 /// and logical operations that can be done on an archive file. It also provides
  37 /// utilities for controlling the runtime loading/reading of the archive file
  38 /// to provide efficient access mechanisms for JIT systems and linkers.
  39 class Archive {
  40
  41   /// @name Types
  42   /// @{
  43   public:
  44     /// The user's interface to the archive symbol table. This multimap allows
  45     /// symbols to be looked up and modules to be instantiated from the file
  46     /// lazily via the ModuleProvider::materializeModule method.
  47     typedef std::map<std::string,ModuleProvider*> SymTab;
  48
  49     /// This typedef is just shorthand for a vector of Path names
  50     typedef std::vector<sys::Path> PathList;
  51
  52     /// This typedef is just shorthand for a vector of Modules
  53     typedef std::vector<Module*> ModuleList;
  54
  55   /// @}
  56   /// @name Constructors
  57   /// @{
  58   public:
  59     /// Create an empty archive file, \p Filename. The returned Archive object
  60     /// will have no file members and an empty symbol table. The actual archive
  61     /// file is not created until the returned Archive object is destructed.
  62     /// @throws std::string if an error occurs
  63     /// @returns An Archive* that represents the new archive file.
  64     /// @brief Create an empty archive file.
  65     static Archive* CreateEmpty(
  66       const sys::Path& Filename        ///< Name of archive file
  67     );
  68
  69     /// Create a new archive file, \p Filename, from the LLVM modules \p Modules.
  70     /// The module's externally visible linkage symbols will be added to the
  71     /// archive's symbol table.  The names of the file members will be obtained
  72     /// from the Module::getModuleId() method. If that name is not unique, it will
  73     /// be made unique by appending a monotonically increasing integer to it. If
  74     /// \p StripName is non-empty, it specifies a prefix to be stripped from the
  75     /// name of the file members. This allows archives with relative path names
  76     /// to be created. The actual archive file is not created until the
  77     /// returned Archive object is destructed.
  78     /// @returns An Archive* that that represents the newly created archive file.
  79     /// @throws std::string if an error occurs
  80     /// @brief Create an archive file from modules.
  81     static Archive* CreateFromModules(
  82       const sys::Path& Filename,       ///< Name of archive file
  83       const ModuleList& Modules,       ///< Modules to be put in archive
  84       const std::string& StripName=""  ///< Prefix to strip from member names
  85     );
  86
  87     /// Create a new archive file, \p Filename, from a set of existing \p Files.
  88     /// Each entry in \p Files will be added to the archive. If any file is an
  89     /// llvm bytecode file, its externally visible linkage symbols will be added
  90     /// to the archive's symbol table. If any of the paths in \p Files refer to
  91     /// directories, those directories will be ignored. Full path names to
  92     /// files must be provided. However, if \p StripName is non-empty, it
  93     /// specifies a prefix string to be removed from each path before it is
  94     /// written as the name of the file member. Any path names that do not have
  95     /// the \p StripName as a prefix will be saved with the full path name
  96     /// provided in \p Files. This permits archives relative to a top level
  97     /// directory to be created.
  98     /// @throws std::string if an error occurs
  99     /// @brief Create an archive file from files.
 100     static Archive* CreateFromFiles(
 101       const sys::Path& Filename,       ///< Name of archive file
 102       const PathList& Files,           ///< File paths to be put in archive
 103       const std::string& StripName=""  ///< Prefix path name to strip from names
 104     );
 105
 106     /// Open an existing archive file from \p Filename. The necessary
 107     /// arrangements to read the file are made, but nothing much is actually
 108     /// read from the file. Use the Accessor methods below to lazily obtain
 109     /// those portions of the file that are of interest.
 110     /// @throws std::string if an error occurs
 111     /// @brief Open an existing archive.
 112     static Archive* Open(
 113       const sys::Path& Filename       ///< Name of the archive file
 114     );
 115
 116     /// This destructor "finalizes" the archive. Regardless of whether the
 117     /// archive was created or opened, all memory associated with the archive
 118     /// is released, including any SymTab* returned by the getSymbolTable()
 119     /// method, any ModuleProviders and their associated Modules returned by
 120     /// any interface method, etc.  Additionally, if the archive was created
 121     /// using one of the Create* methods, the archive is written to disk in
 122     /// its final format. After this method exits, none of the memory
 123     /// associated with the archive is valid. It is the user's responsibility
 124     /// to ensure that all references to such memory is removed before the
 125     /// Archive is destructed.
 126     /// @throws std::string if an error occurs
 127     /// @brief Destruct in-memory archive
 128     ~Archive();
 129
 130   /// @}
 131   /// @name Accessors
 132   /// @{
 133   public:
 134     /// This accessor looks up the \p symbol in the archive's symbol table and
 135     /// returns the associated module that defines that symbol. This method can
 136     /// be called as many times as necessary. This is handy for linking the
 137     /// archive into another module based on unresolved symbols. Note that the
 138     /// ModuleProvider returned by this accessor is constant and it may refer
 139     /// to the same ModuleProvider object returned by this accessor in a
 140     /// previous call (because the associated module defines both symbols). To
 141     /// use the returned ModuleProvider* you must make a copy and call the
 142     /// materializeModule method on the copy.
 143     /// @throws std::string if an error occurs
 144     /// @returns The ModuleProvider* found or null if the archive does not
 145     /// contain a module that defines the \p symbol.
 146     /// @brief Look up a module by symbol name.
 147     const ModuleProvider* findModuleContainingSymbol(
 148       const std::string& symbol        ///< Symbol to be sought
 149     ) const;
 150
 151     /// Return the list of all the \p Paths for the file members in the archive.
 152     /// This is handy for generating the table of contents of the archive. Note
 153     /// that \p Paths is *not* cleared before it is populated. New entries are
 154     /// appended to the end of the PathList.
 155     /// @throw std::string if an error occurs
 156     /// @returns nothing
 157     /// @brief Get all the paths in the archive
 158     void getAllPaths(
 159       PathList& Paths                ///< The list of paths returned
 160     );
 161
 162     /// This method returns a caller readable SymTab object which is a map
 163     /// of symbol names to ModuleProviders. Callers can traverse this symbol
 164     /// table, look up specific symbols, etc. and materialize any Modules they
 165     /// want with the associated ModuleProviders.  It is unnecessary to call
 166     /// this accessor more than once as the same object is alway returned, even
 167     /// if changes have been made.
 168     /// @returns a constant SymTab* that is the same for every invocation. The
 169     /// caller should not attempt to free or modify this SymTab object, just use
 170     /// it.
 171     /// @brief Get the archive's symbol table.
 172     const SymTab* getSymbolTable();
 173
 174     /// Extract the contents of the archive back to the file system using \p
 175     /// RootDir as the directory at the root of the extraction.  Each file
 176     /// member is written back as a separate file. If \p flat is false, then
 177     /// directories are created as necessary to restore the files to the correct
 178     /// sub-directory of \p root as specified in the full path of the file
 179     /// member. Otherwise, paths are ignored and all file members will be
 180     /// extracted to the \p root directory using only the filename portion of
 181     /// the path (directories ignored). If \p symtab is true, the archive's
 182     /// symbol table will also be extracted to a file named __SYMTAB.
 183     /// @returns nothing
 184     /// @throws std::string if an error occurs
 185     /// @brief Extract archive contents to a file.
 186     void extractAllToDirectory(
 187       const sys::Path& RootDir,      ///< The root directory for extraction
 188       bool Flat = true,              ///< false = recreate directory structure
 189       bool Symtab = false            ///< true = extract symbol table too
 190     );
 191
 192     /// Extract one file in the archive back to the file system using \p RootDir
 193     /// as the directory at the root of the extraction. The file \p name is
 194     /// extracted and placed into \p RootDir. If \p Flat is false, then any
 195     /// intermediate directory names in the file member's path will also be
 196     /// created. Otherwise, the member's file is created in RootDir ignoring
 197     /// the leading path and using only the member's file name.
 198     /// @throws std::string if an error occurs.
 199     /// @returns nothing
 200     /// @brief Extract a single archive file.
 201     void extractOneFileToDirectory(
 202       const sys::Path& RootDir,      ///< The root directory for extraction
 203       const sys::Path& name,         ///< Name of file to extract
 204       bool Flat = true               ///< false = recreate directories
 205     );
 206
 207   /// @}
 208   /// @name Mutators
 209   /// @{
 210   public:
 211     /// Each entry in \p Files will be added to the archive. If any file is an
 212     /// llvm bytecode file, its externally visible linkage symbols will be added
 213     /// to the archive's symbol table. If any of the paths in \p Files refer to
 214     /// directories, those directories will be ignored. Full path names to
 215     /// files must be provided. However, if \p StripName is non-empty, it
 216     /// specifies a prefix string to be removed from each path before it is
 217     /// written as the name of the file member. Any path names that do not have
 218     /// the \p StripName as a prefix will be saved with the full path name
 219     /// provided. This permits archives relative to a top level directory
 220     /// to be created.
 221     /// @throws std::string if an error occurs
 222     /// @returns nothing
 223     /// @brief Add a set of files to the archive.
 224     void addFiles(
 225       const PathList& Files,           ///< The names of files to add to archive
 226       const std::string& StripName=""  ///< Prefix path to strip from names
 227     );
 228
 229     /// Add a set of Modules to the archive.  Names of member files will
 230     /// be taken from the Module identifier (Module::getModuleIdentifier) if it
 231     /// is unique. Non-unique member names will be made unique by appending a
 232     /// number. The symbol table will be augmented with the global symbols of
 233     /// all the modules provided. If \p StripName is non-empty, it
 234     /// specifies a prefix string to be removed from each moduleId  before it is
 235     /// written as the name of the file member. Any path names that do not have
 236     /// the \p StripName as a prefix will be saved with the full path name
 237     /// provided. This permits archives relative to a top level directory  to
 238     /// be created.
 239     /// @throws std::string if an error occurs
 240     /// @returns nothing
 241     /// @brief Add a set of modules to the archive.
 242     void addModules(
 243       const ModuleList& Modules,       ///< The modules to add to the archive
 244       const std::string& StripName=""  ///< Prefix path to strip from names
 245     );
 246
 247   /// @}
 248 };
 249
 250 } // End llvm namespace
 251
 252 // vim: sw=2 ai
 253
 254 #endif