LLVM API Documentation

Debug.cpp
Go to the documentation of this file.
00001 //===-- Debug.cpp - An easy way to add debug output to your code ----------===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file implements a handy way of adding debugging information to your
00011 // code, without it being enabled all of the time, and without having to add
00012 // command line options to enable it.
00013 //
00014 // In particular, just wrap your code with the DEBUG() macro, and it will be
00015 // enabled automatically if you specify '-debug' on the command-line.
00016 // Alternatively, you can also use the SET_DEBUG_TYPE("foo") macro to specify
00017 // that your debug code belongs to class "foo".  Then, on the command line, you
00018 // can specify '-debug-only=foo' to enable JUST the debug information for the
00019 // foo class.
00020 //
00021 // When compiling without assertions, the -debug-* options and all code in
00022 // DEBUG() statements disappears, so it does not affect the runtime of the code.
00023 //
00024 //===----------------------------------------------------------------------===//
00025 
00026 #include "llvm/Support/Debug.h"
00027 #include "llvm/Support/CommandLine.h"
00028 #include "llvm/Support/ManagedStatic.h"
00029 #include "llvm/Support/Signals.h"
00030 #include "llvm/Support/circular_raw_ostream.h"
00031 
00032 #undef isCurrentDebugType
00033 #undef setCurrentDebugType
00034 
00035 using namespace llvm;
00036 
00037 // Even though LLVM might be built with NDEBUG, define symbols that the code
00038 // built without NDEBUG can depend on via the llvm/Support/Debug.h header.
00039 namespace llvm {
00040 /// Exported boolean set by the -debug option.
00041 bool DebugFlag = false;
00042 
00043 static ManagedStatic<std::vector<std::string>> CurrentDebugType;
00044 
00045 /// Return true if the specified string is the debug type
00046 /// specified on the command line, or if none was specified on the command line
00047 /// with the -debug-only=X option.
00048 bool isCurrentDebugType(const char *DebugType) {
00049   if (CurrentDebugType->empty())
00050     return true;
00051   // see if DebugType is in list. Note: do not use find() as that forces us to
00052   // unnecessarily create an std::string instance.
00053   for (auto d : *CurrentDebugType) {
00054     if (d == DebugType)
00055       return true;
00056   }
00057   return false;
00058 }
00059 
00060 /// Set the current debug type, as if the -debug-only=X
00061 /// option were specified.  Note that DebugFlag also needs to be set to true for
00062 /// debug output to be produced.
00063 ///
00064 void setCurrentDebugType(const char *Type) {
00065   CurrentDebugType->clear();
00066   CurrentDebugType->push_back(Type);
00067 }
00068 
00069 } // namespace llvm
00070 
00071 // All Debug.h functionality is a no-op in NDEBUG mode.
00072 #ifndef NDEBUG
00073 
00074 // -debug - Command line option to enable the DEBUG statements in the passes.
00075 // This flag may only be enabled in debug builds.
00076 static cl::opt<bool, true>
00077 Debug("debug", cl::desc("Enable debug output"), cl::Hidden,
00078       cl::location(DebugFlag));
00079 
00080 // -debug-buffer-size - Buffer the last N characters of debug output
00081 //until program termination.
00082 static cl::opt<unsigned>
00083 DebugBufferSize("debug-buffer-size",
00084                 cl::desc("Buffer the last N characters of debug output "
00085                          "until program termination. "
00086                          "[default 0 -- immediate print-out]"),
00087                 cl::Hidden,
00088                 cl::init(0));
00089 
00090 namespace {
00091 
00092 struct DebugOnlyOpt {
00093   void operator=(const std::string &Val) const {
00094     if (Val.empty())
00095       return;
00096     DebugFlag = true;
00097     CurrentDebugType->push_back(Val);
00098   }
00099 };
00100 
00101 }
00102 
00103 static DebugOnlyOpt DebugOnlyOptLoc;
00104 
00105 static cl::opt<DebugOnlyOpt, true, cl::parser<std::string> >
00106 DebugOnly("debug-only", cl::desc("Enable a specific type of debug output"),
00107           cl::Hidden, cl::ZeroOrMore, cl::value_desc("debug string"),
00108           cl::location(DebugOnlyOptLoc), cl::ValueRequired);
00109 
00110 // Signal handlers - dump debug output on termination.
00111 static void debug_user_sig_handler(void *Cookie) {
00112   // This is a bit sneaky.  Since this is under #ifndef NDEBUG, we
00113   // know that debug mode is enabled and dbgs() really is a
00114   // circular_raw_ostream.  If NDEBUG is defined, then dbgs() ==
00115   // errs() but this will never be invoked.
00116   llvm::circular_raw_ostream *dbgout =
00117     static_cast<llvm::circular_raw_ostream *>(&llvm::dbgs());
00118   dbgout->flushBufferWithBanner();
00119 }
00120 
00121 /// dbgs - Return a circular-buffered debug stream.
00122 raw_ostream &llvm::dbgs() {
00123   // Do one-time initialization in a thread-safe way.
00124   static struct dbgstream {
00125     circular_raw_ostream strm;
00126 
00127     dbgstream() :
00128         strm(errs(), "*** Debug Log Output ***\n",
00129              (!EnableDebugBuffering || !DebugFlag) ? 0 : DebugBufferSize) {
00130       if (EnableDebugBuffering && DebugFlag && DebugBufferSize != 0)
00131         // TODO: Add a handler for SIGUSER1-type signals so the user can
00132         // force a debug dump.
00133         sys::AddSignalHandler(&debug_user_sig_handler, nullptr);
00134       // Otherwise we've already set the debug stream buffer size to
00135       // zero, disabling buffering so it will output directly to errs().
00136     }
00137   } thestrm;
00138 
00139   return thestrm.strm;
00140 }
00141 
00142 #else
00143 // Avoid "has no symbols" warning.
00144 namespace llvm {
00145   /// dbgs - Return errs().
00146   raw_ostream &dbgs() {
00147     return errs();
00148   }
00149 }
00150 
00151 #endif
00152 
00153 /// EnableDebugBuffering - Turn on signal handler installation.
00154 ///
00155 bool llvm::EnableDebugBuffering = false;