LLVM API Documentation

GraphWriter.h

Go to the documentation of this file.
00001 //===-- llvm/Support/GraphWriter.h - Write graph to a .dot file -*- C++ -*-===//
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 defines a simple interface that can be used to print out generic
00011 // LLVM graphs to ".dot" files.  "dot" is a tool that is part of the AT&T
00012 // graphviz package (http://www.research.att.com/sw/tools/graphviz/) which can
00013 // be used to turn the files output by this interface into a variety of
00014 // different graphics formats.
00015 //
00016 // Graphs do not need to implement any interface past what is already required
00017 // by the GraphTraits template, but they can choose to implement specializations
00018 // of the DOTGraphTraits template if they want to customize the graphs output in
00019 // any way.
00020 //
00021 //===----------------------------------------------------------------------===//
00022 
00023 #ifndef LLVM_SUPPORT_GRAPHWRITER_H
00024 #define LLVM_SUPPORT_GRAPHWRITER_H
00025 
00026 #include "llvm/Support/DOTGraphTraits.h"
00027 #include "llvm/Support/Streams.h"
00028 #include "llvm/ADT/GraphTraits.h"
00029 #include "llvm/System/Path.h"
00030 #include <fstream>
00031 #include <vector>
00032 #include <cassert>
00033 
00034 namespace llvm {
00035 
00036 namespace DOT {  // Private functions...
00037   inline std::string EscapeString(const std::string &Label) {
00038     std::string Str(Label);
00039     for (unsigned i = 0; i != Str.length(); ++i)
00040       switch (Str[i]) {
00041       case '\n':
00042         Str.insert(Str.begin()+i, '\\');  // Escape character...
00043         ++i;
00044         Str[i] = 'n';
00045         break;
00046       case '\t':
00047         Str.insert(Str.begin()+i, ' ');  // Convert to two spaces
00048         ++i;
00049         Str[i] = ' ';
00050         break;
00051       case '\\':
00052         if (i+1 != Str.length())
00053           switch (Str[i+1]) {
00054             case 'l': continue; // don't disturb \l
00055             case '|': case '{': case '}':
00056                Str.erase(Str.begin()+i); continue;
00057             default: break;
00058           }
00059       case '{': case '}':
00060       case '<': case '>':
00061       case '|': case '"':
00062         Str.insert(Str.begin()+i, '\\');  // Escape character...
00063         ++i;  // don't infinite loop
00064         break;
00065       }
00066     return Str;
00067   }
00068 }
00069 
00070 namespace GraphProgram {
00071    enum Name {
00072       DOT,
00073       FDP,
00074       NEATO,
00075       TWOPI,
00076       CIRCO
00077    };
00078 }
00079    
00080 void DisplayGraph(const sys::Path& Filename, bool wait=true, GraphProgram::Name program = GraphProgram::DOT);
00081 
00082 template<typename GraphType>
00083 class GraphWriter {
00084   std::ostream &O;
00085   const GraphType &G;
00086   bool ShortNames;
00087 
00088   typedef DOTGraphTraits<GraphType>           DOTTraits;
00089   typedef GraphTraits<GraphType>              GTraits;
00090   typedef typename GTraits::NodeType          NodeType;
00091   typedef typename GTraits::nodes_iterator    node_iterator;
00092   typedef typename GTraits::ChildIteratorType child_iterator;
00093 public:
00094   GraphWriter(std::ostream &o, const GraphType &g, bool SN) :
00095     O(o), G(g), ShortNames(SN) {}
00096 
00097   void writeHeader(const std::string &Name) {
00098     std::string GraphName = DOTTraits::getGraphName(G);
00099 
00100     if (!Name.empty())
00101       O << "digraph \"" << DOT::EscapeString(Name) << "\" {\n";
00102     else if (!GraphName.empty())
00103       O << "digraph \"" << DOT::EscapeString(GraphName) << "\" {\n";
00104     else
00105       O << "digraph unnamed {\n";
00106 
00107     if (DOTTraits::renderGraphFromBottomUp())
00108       O << "\trankdir=\"BT\";\n";
00109 
00110     if (!Name.empty())
00111       O << "\tlabel=\"" << DOT::EscapeString(Name) << "\";\n";
00112     else if (!GraphName.empty())
00113       O << "\tlabel=\"" << DOT::EscapeString(GraphName) << "\";\n";
00114     O << DOTTraits::getGraphProperties(G);
00115     O << "\n";
00116   }
00117 
00118   void writeFooter() {
00119     // Finish off the graph
00120     O << "}\n";
00121   }
00122 
00123   void writeNodes() {
00124     // Loop over the graph, printing it out...
00125     for (node_iterator I = GTraits::nodes_begin(G), E = GTraits::nodes_end(G);
00126          I != E; ++I)
00127       writeNode(*I);
00128   }
00129 
00130   void writeNode(NodeType& Node) {
00131     writeNode(&Node);
00132   }
00133 
00134   void writeNode(NodeType *const *Node) {
00135     writeNode(*Node);
00136   }
00137 
00138   void writeNode(NodeType *Node) {
00139     std::string NodeAttributes = DOTTraits::getNodeAttributes(Node, G);
00140 
00141     O << "\tNode" << static_cast<const void*>(Node) << " [shape=record,";
00142     if (!NodeAttributes.empty()) O << NodeAttributes << ",";
00143     O << "label=\"{";
00144 
00145     if (!DOTTraits::renderGraphFromBottomUp()) {
00146       O << DOT::EscapeString(DOTTraits::getNodeLabel(Node, G, ShortNames));
00147 
00148       // If we should include the address of the node in the label, do so now.
00149       if (DOTTraits::hasNodeAddressLabel(Node, G))
00150         O << "|" << (void*)Node;
00151     }
00152 
00153     // Print out the fields of the current node...
00154     child_iterator EI = GTraits::child_begin(Node);
00155     child_iterator EE = GTraits::child_end(Node);
00156     if (EI != EE) {
00157       if (!DOTTraits::renderGraphFromBottomUp()) O << "|";
00158       O << "{";
00159 
00160       for (unsigned i = 0; EI != EE && i != 64; ++EI, ++i) {
00161         if (i) O << "|";
00162         O << "<s" << i << ">" << DOTTraits::getEdgeSourceLabel(Node, EI);
00163       }
00164 
00165       if (EI != EE)
00166         O << "|<s64>truncated...";
00167       O << "}";
00168       if (DOTTraits::renderGraphFromBottomUp()) O << "|";
00169     }
00170 
00171     if (DOTTraits::renderGraphFromBottomUp()) {
00172       O << DOT::EscapeString(DOTTraits::getNodeLabel(Node, G, ShortNames));
00173 
00174       // If we should include the address of the node in the label, do so now.
00175       if (DOTTraits::hasNodeAddressLabel(Node, G))
00176         O << "|" << (void*)Node;
00177     }
00178 
00179     if (DOTTraits::hasEdgeDestLabels()) {
00180       O << "|{";
00181 
00182       unsigned i = 0, e = DOTTraits::numEdgeDestLabels(Node);
00183       for (; i != e && i != 64; ++i) {
00184         if (i) O << "|";
00185         O << "<d" << i << ">" << DOTTraits::getEdgeDestLabel(Node, i);
00186       }
00187 
00188       if (i != e)
00189         O << "|<d64>truncated...";
00190       O << "}";
00191     }
00192 
00193     O << "}\"];\n";   // Finish printing the "node" line
00194 
00195     // Output all of the edges now
00196     EI = GTraits::child_begin(Node);
00197     for (unsigned i = 0; EI != EE && i != 64; ++EI, ++i)
00198       writeEdge(Node, i, EI);
00199     for (; EI != EE; ++EI)
00200       writeEdge(Node, 64, EI);
00201   }
00202 
00203   void writeEdge(NodeType *Node, unsigned edgeidx, child_iterator EI) {
00204     if (NodeType *TargetNode = *EI) {
00205       int DestPort = -1;
00206       if (DOTTraits::edgeTargetsEdgeSource(Node, EI)) {
00207         child_iterator TargetIt = DOTTraits::getEdgeTarget(Node, EI);
00208 
00209         // Figure out which edge this targets...
00210         unsigned Offset =
00211           (unsigned)std::distance(GTraits::child_begin(TargetNode), TargetIt);
00212         DestPort = static_cast<int>(Offset);
00213       }
00214 
00215       emitEdge(static_cast<const void*>(Node), edgeidx,
00216                static_cast<const void*>(TargetNode), DestPort,
00217                DOTTraits::getEdgeAttributes(Node, EI));
00218     }
00219   }
00220 
00221   /// emitSimpleNode - Outputs a simple (non-record) node
00222   void emitSimpleNode(const void *ID, const std::string &Attr,
00223                       const std::string &Label, unsigned NumEdgeSources = 0,
00224                       const std::vector<std::string> *EdgeSourceLabels = 0) {
00225     O << "\tNode" << ID << "[ ";
00226     if (!Attr.empty())
00227       O << Attr << ",";
00228     O << " label =\"";
00229     if (NumEdgeSources) O << "{";
00230     O << DOT::EscapeString(Label);
00231     if (NumEdgeSources) {
00232       O << "|{";
00233 
00234       for (unsigned i = 0; i != NumEdgeSources; ++i) {
00235         if (i) O << "|";
00236         O << "<s" << i << ">";
00237         if (EdgeSourceLabels) O << (*EdgeSourceLabels)[i];
00238       }
00239       O << "}}";
00240     }
00241     O << "\"];\n";
00242   }
00243 
00244   /// emitEdge - Output an edge from a simple node into the graph...
00245   void emitEdge(const void *SrcNodeID, int SrcNodePort,
00246                 const void *DestNodeID, int DestNodePort,
00247                 const std::string &Attrs) {
00248     if (SrcNodePort  > 64) return;             // Eminating from truncated part?
00249     if (DestNodePort > 64) DestNodePort = 64;  // Targetting the truncated part?
00250 
00251     O << "\tNode" << SrcNodeID;
00252     if (SrcNodePort >= 0)
00253       O << ":s" << SrcNodePort;
00254     O << " -> Node" << DestNodeID;
00255     if (DestNodePort >= 0) {
00256       if (DOTTraits::hasEdgeDestLabels())
00257   O << ":d" << DestNodePort;
00258       else
00259   O << ":s" << DestNodePort;
00260     }
00261 
00262     if (!Attrs.empty())
00263       O << "[" << Attrs << "]";
00264     O << ";\n";
00265   }
00266 };
00267 
00268 template<typename GraphType>
00269 std::ostream &WriteGraph(std::ostream &O, const GraphType &G,
00270                          bool ShortNames = false,
00271                          const std::string &Name = "",
00272                          const std::string &Title = "") {
00273   // Start the graph emission process...
00274   GraphWriter<GraphType> W(O, G, ShortNames);
00275 
00276   // Output the header for the graph...
00277   W.writeHeader(Title);
00278 
00279   // Emit all of the nodes in the graph...
00280   W.writeNodes();
00281 
00282   // Output any customizations on the graph
00283   DOTGraphTraits<GraphType>::addCustomGraphFeatures(G, W);
00284 
00285   // Output the end of the graph
00286   W.writeFooter();
00287   return O;
00288 }
00289 
00290 template<typename GraphType>
00291 sys::Path WriteGraph(const GraphType &G,
00292                      const std::string& Name,
00293                      bool ShortNames = false,
00294                      const std::string& Title = "") {
00295   std::string ErrMsg;
00296   sys::Path Filename = sys::Path::GetTemporaryDirectory(&ErrMsg);
00297   if (Filename.isEmpty()) {
00298     cerr << "Error: " << ErrMsg << "\n";
00299     return Filename;
00300   }
00301   Filename.appendComponent(Name + ".dot");
00302   if (Filename.makeUnique(true,&ErrMsg)) {
00303     cerr << "Error: " << ErrMsg << "\n";
00304     return sys::Path();
00305   }
00306 
00307   cerr << "Writing '" << Filename << "'... ";
00308 
00309   std::ofstream O(Filename.c_str());
00310 
00311   if (O.good()) {
00312     WriteGraph(O, G, ShortNames, Name, Title);
00313     cerr << " done. \n";
00314 
00315     O.close();
00316   } else {
00317     cerr << "error opening file for writing!\n";
00318     Filename.clear();
00319   }
00320 
00321   return Filename;
00322 }
00323 
00324 /// ViewGraph - Emit a dot graph, run 'dot', run gv on the postscript file,
00325 /// then cleanup.  For use from the debugger.
00326 ///
00327 template<typename GraphType>
00328 void ViewGraph(const GraphType& G,
00329                const std::string& Name,
00330                bool ShortNames = false,
00331                const std::string& Title = "",
00332                GraphProgram::Name Program = GraphProgram::DOT) {
00333   sys::Path Filename =  WriteGraph(G, Name, ShortNames, Title);
00334 
00335   if (Filename.isEmpty()) {
00336     return;
00337   }
00338 
00339   DisplayGraph(Filename, true, Program);
00340 }
00341 
00342 } // End llvm namespace
00343 
00344 #endif