include/llvm/System/IncludeFile.h

   1 //===- llvm/System/IncludeFile.h - Ensure Linking Of Library ---*- 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 //
  10 // This file defines the FORCE_DEFINING_FILE_TO_BE_LINKED and DEFINE_FILE_FOR
  11 // macros.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_SYSTEM_INCLUDEFILE_H
  16 #define LLVM_SYSTEM_INCLUDEFILE_H
  17
  18 /// This macro is the public interface that IncludeFile.h exports. This gives
  19 /// us the option to implement the "link the definition" capability in any
  20 /// manner that we choose. All header files that depend on a specific .cpp
  21 /// file being linked at run time should use this macro instead of the
  22 /// IncludeFile class directly.
  23 ///
  24 /// For example, foo.h would use:<br/>
  25 /// <tt>FORCE_DEFINING_FILE_TO_BE_LINKED(foo)</tt><br/>
  26 ///
  27 /// And, foo.cp would use:<br/>
  28 /// <tt>DEFINING_FILE_FOR(foo)</tt><br/>
  29 #define FORCE_DEFINING_FILE_TO_BE_LINKED(name) \
  30   namespace llvm { \
  31     extern char name ## LinkVar; \
  32     static IncludeFile name ## LinkObj ( &name ## LinkVar ); \
  33   }
  34
  35 /// This macro is the counterpart to FORCE_DEFINING_FILE_TO_BE_LINKED. It should
  36 /// be used in a .cpp file to define the name referenced in a header file that
  37 /// will cause linkage of the .cpp file. It should only be used at extern level.
  38 #define DEFINING_FILE_FOR(name) namespace llvm { char name ## LinkVar; }
  39
  40 namespace llvm {
  41
  42 /// This class is used in the implementation of FORCE_DEFINING_FILE_TO_BE_LINKED
  43 /// macro to make sure that the implementation of a header file is included
  44 /// into a tool that uses the header.  This is solely
  45 /// to overcome problems linking .a files and not getting the implementation
  46 /// of compilation units we need. This is commonly an issue with the various
  47 /// Passes but also occurs elsewhere in LLVM. We like to use .a files because
  48 /// they link faster and provide the smallest executables. However, sometimes
  49 /// those executables are too small, if the program doesn't reference something
  50 /// that might be needed, especially by a loaded share object. This little class
  51 /// helps to resolve that problem. The basic strategy is to use this class in
  52 /// a header file and pass the address of a variable to the constructor. If the
  53 /// variable is defined in the header file's corresponding .cpp file then all
  54 /// tools/libraries that #include the header file will require the .cpp as well.
  55 /// For example:<br/>
  56 /// <tt>extern int LinkMyCodeStub;</tt><br/>
  57 /// <tt>static IncludeFile LinkMyModule(&LinkMyCodeStub);</tt><br/>
  58 /// @brief Class to ensure linking of corresponding object file.
  59 struct IncludeFile {
  60   IncludeFile(void *);
  61 };
  62
  63 }
  64
  65 #endif