LLVM API Documentation
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