1//===- llvm/Support/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_SUPPORT_INCLUDEFILE_H
16#define LLVM_SUPPORT_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#ifdef __GNUC__
30// If the `used' attribute is available, use it to create a variable
31// with an initializer that will force the linking of the defining file.
32#define FORCE_DEFINING_FILE_TO_BE_LINKED(name) \
33  namespace llvm { \
34    extern const char name ## LinkVar; \
35    __attribute__((used)) static const char *const name ## LinkObj = \
36      &name ## LinkVar; \
37  }
38#else
39// Otherwise use a constructor call.
40#define FORCE_DEFINING_FILE_TO_BE_LINKED(name) \
41  namespace llvm { \
42    extern const char name ## LinkVar; \
43    static const IncludeFile name ## LinkObj ( &name ## LinkVar ); \
44  }
45#endif
46
47/// This macro is the counterpart to FORCE_DEFINING_FILE_TO_BE_LINKED. It should
48/// be used in a .cpp file to define the name referenced in a header file that
49/// will cause linkage of the .cpp file. It should only be used at extern level.
50#define DEFINING_FILE_FOR(name) \
51  namespace llvm { const char name ## LinkVar = 0; }
52
53namespace llvm {
54
55/// This class is used in the implementation of FORCE_DEFINING_FILE_TO_BE_LINKED
56/// macro to make sure that the implementation of a header file is included
57/// into a tool that uses the header.  This is solely
58/// to overcome problems linking .a files and not getting the implementation
59/// of compilation units we need. This is commonly an issue with the various
60/// Passes but also occurs elsewhere in LLVM. We like to use .a files because
61/// they link faster and provide the smallest executables. However, sometimes
62/// those executables are too small, if the program doesn't reference something
63/// that might be needed, especially by a loaded share object. This little class
64/// helps to resolve that problem. The basic strategy is to use this class in
65/// a header file and pass the address of a variable to the constructor. If the
66/// variable is defined in the header file's corresponding .cpp file then all
67/// tools/libraries that \#include the header file will require the .cpp as
68/// well.
69/// For example:<br/>
70/// <tt>extern int LinkMyCodeStub;</tt><br/>
71/// <tt>static IncludeFile LinkMyModule(&LinkMyCodeStub);</tt><br/>
72/// @brief Class to ensure linking of corresponding object file.
73struct IncludeFile {
74  explicit IncludeFile(const void *);
75};
76
77}
78
79#endif
80