home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _bcada8a4a26cb1d31d531446bb541238 < prev    next >
Text File  |  2000-03-23  |  12KB  |  256 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>B::Graph - Perl compiler backend to produce graphs of OP trees</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> B::Graph - Perl compiler backend to produce graphs of OP trees</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#options">OPTIONS</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#text, vcg, dot">-text, -vcg, -dot</A></LI>
  29.         <LI><A HREF="#addrs, no_addrs">-addrs, -no_addrs</A></LI>
  30.         <LI><A HREF="#compile_order, run_order">-compile_order, -run_order</A></LI>
  31.         <LI><A HREF="#svs, no_svs">-SVs, -no_SVs</A></LI>
  32.         <LI><A HREF="#ellipses, rhombs">-ellipses, -rhombs</A></LI>
  33.         <LI><A HREF="#stashes, no_stashes">-stashes, -no_stashes</A></LI>
  34.         <LI><A HREF="#filegvs, no_filegvs">-fileGVs, -no_fileGVs</A></LI>
  35.         <LI><A HREF="#seqs, no_seqs">-SEQs, -no_SEQs</A></LI>
  36.         <LI><A HREF="#types, no_types">-types, -no_types</A></LI>
  37.         <LI><A HREF="#float, no_float">-float, -no_float</A></LI>
  38.         <LI><A HREF="#targlinks, no_targlinks">-targlinks, -no_targlinks</A></LI>
  39.     </UL>
  40.  
  41.     <LI><A HREF="#what does this all mean">WHAT DOES THIS ALL MEAN?</A></LI>
  42.     <UL>
  43.  
  44.         <LI><A HREF="#svflags abbreviations">SvFLAGS abbreviations</A></LI>
  45.         <LI><A HREF="#op_flags abbreviations">op_flags abbreviations</A></LI>
  46.     </UL>
  47.  
  48.     <LI><A HREF="#bugs">BUGS</A></LI>
  49.     <LI><A HREF="#author">AUTHOR</A></LI>
  50.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  51. </UL>
  52. <!-- INDEX END -->
  53.  
  54. <HR>
  55. <P>
  56. <H1><A NAME="name">NAME</A></H1>
  57. <P>B::Graph - Perl compiler backend to produce graphs of OP trees</P>
  58. <P>
  59. <HR>
  60. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  61. <UL>
  62. <LI>Linux</LI>
  63. <LI>Solaris</LI>
  64. <LI>Windows</LI>
  65. </UL>
  66. <HR>
  67. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  68. <PRE>
  69.   perl -MO=Graph,-text prog.pl >graph.txt</PRE>
  70. <PRE>
  71.   perl -MO=Graph,-vcg prog.pl >graph.vcg
  72.   xvcg graph.vcg</PRE>
  73. <PRE>
  74.   perl -MO=Graph,-dot prog.pl | dot -Tps >graph.ps</PRE>
  75. <P>
  76. <HR>
  77. <H1><A NAME="description">DESCRIPTION</A></H1>
  78. <P>This module is a backend to the perl compiler (B::*) which, instead of
  79. outputting bytecode or C based on perl's compiled version of a program,
  80. writes descriptions in graph-description languages specifying graphs that
  81. show the program's structure. It currently generates descriptions for the
  82. VCG tool (<CODE>http://www.cs.uni-sb.de/RW/users/sander/html/gsvcg1.html</CODE>) and
  83. Dot (part of the graph visualization toolkit from AT&T:
  84. <CODE>http://www.research.att.com/sw/tools/graphviz/</CODE>). It also can produce
  85. plain text output (which is more useful for debugging the module itself than
  86. anything else, though you might be able to make cut the nodes out and make
  87. a mobile or something similar).</P>
  88. <P>
  89. <HR>
  90. <H1><A NAME="options">OPTIONS</A></H1>
  91. <P>Like any other compiler backend, this module needs to be invoked using the
  92. <CODE>O</CODE> module to run correctly:</P>
  93. <PRE>
  94.   perl -MO=Graph,-opt,-opt,-opt program.pl
  95.   OR
  96.   perl -MO=Graph,-opt,obj -e 'BEGIN {$obj = ["hi"]}; print $obj'
  97.   OR EVEN
  98.   perl -e 'use O qw(Graph -opt obj obj); print "hi!\n";'</PRE>
  99. <P><CODE>Obj</CODE> is the name of a perl variable whose contents will be examined.
  100. It can't be a <A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my()</CODE></A> variable, and it shouldn't have a prefix symbol
  101. ('$@^*'), though you can specify a package -- the name will be used to
  102. look up a GV, whose various fields will lead to the scalar, array, and
  103. other values that correspond to the named variable. If no object is
  104. specified, the whole main program, including the CV that points to its
  105. pad, will be displayed.</P>
  106. <P>Each of the the <CODE>opt</CODE>s can come from one of the following (each set is
  107. mutually exclusive; case and underscores are insignificant):</P>
  108. <P>
  109. <H2><A NAME="text, vcg, dot">-text, -vcg, -dot</A></H2>
  110. <P>Produce output of the appropriate type. The default is '-text', which isn't
  111. useful for much of anything (it does draw some nice ASCII boxes, though).</P>
  112. <P>
  113. <H2><A NAME="addrs, no_addrs">-addrs, -no_addrs</A></H2>
  114. <P>Each of the nodes on the graph produced corresponds to a C structure that
  115. has an address and includes pointers to other structures. The module uses
  116. these addresses to decide how to draw edges, but it makes the graph more
  117. compact if they aren't printed. The default is '-no_addrs'.</P>
  118. <P>
  119. <H2><A NAME="compile_order, run_order">-compile_order, -run_order</A></H2>
  120. <P>The collection of OPs that perl compiles a script into has two different
  121. layers of structure. It has a tree structure which corresponds roughly
  122. to the synactic nesting of constructs in the source text, and a 
  123. roughly linked-list representation, essentially a postorder traversal
  124. of this tree, which is used at runtime to decide what to do next.
  125. The graph can be drawn to emphasize one structure or the other. The former,
  126. 'compile_order', is the default, as it tends to lead to graphs with aspect
  127. ratios close to those of standard paper.</P>
  128. <P>
  129. <H2><A NAME="svs, no_svs">-SVs, -no_SVs</A></H2>
  130. <P>If OPs represent a program's compiled code, SVs represent its data. This
  131. includes literal numbers and strings (IVs, NVs, PVs, PVIVs, and PVNVs),
  132. regular arrays, hashes, and references (AVs, HVs, and RVs), but also the
  133. structures that correspond to individual variables (special HVs for symbol
  134. tables and GVs to represent values within them, and special AVs that hold
  135. <A HREF="../../../lib/Pod/perlfunc.html#item_my"><CODE>my()</CODE></A> variables (as well as compiler temporaries)), structures that keep
  136. track of code (CVs), and a variety of others. The default is to display
  137. all these too, to give a complete picture, but if you aren't in a holistic
  138. mood, you can make them disappear.</P>
  139. <P>
  140. <H2><A NAME="ellipses, rhombs">-ellipses, -rhombs</A></H2>
  141. <P>The module tries to give the nodes representing SVs a different shape from
  142. those of OPs. OPs are usually rectangular, so two obvious shapes for SVs
  143. are ellipses and rhombuses (stretched diamonds). This option currently only
  144. makes a difference for VCG (ellipse is the default).</P>
  145. <P>
  146. <H2><A NAME="stashes, no_stashes">-stashes, -no_stashes</A></H2>
  147. <P>The hashes that perl uses to represent symbol tables are called 'stashes'.
  148. Since every GV has a pointer back to its stash, it's virtually inevitable
  149. for the links in a graph to lead to the main stash. Unfortunately stashes,
  150. especially the main one, can be quite big, and lead to forests of other
  151. structures -- there's one GV and another SV for each magic variable, plus
  152. all of @INC and %ENV, and so on. To prevent information overload, then,
  153. the display of stashes is disabled by default.</P>
  154. <P>
  155. <H2><A NAME="filegvs, no_filegvs">-fileGVs, -no_fileGVs</A></H2>
  156. <P>Another kind graph element that can be annoying are the pointers from
  157. every GV and COP (a kind of OP that occurs for every statement) to the
  158. GV that represents the file from which that code came (used for error
  159. messages). By default, these links aren't shown, to keep them from
  160. cluttering the graph.</P>
  161. <P>
  162. <H2><A NAME="seqs, no_seqs">-SEQs, -no_SEQs</A></H2>
  163. <P>As it is visited in the peephole optimization phase, each OP gets a
  164. sequence number, which is currently used by anything (except the peephole
  165. optimizer, to avoid visiting OPs twice). If you want to see these, ask
  166. for them. (COPs have their own sequence numbers too, but they're more
  167. generally useful).</P>
  168. <P>
  169. <H2><A NAME="types, no_types">-types, -no_types</A></H2>
  170. <P>B::Graph always gives the type of each OP symbolically ('entersub'), but
  171. it can also print the numeric value of the type field, if you want.
  172. The default is no_types.</P>
  173. <P>
  174. <H2><A NAME="float, no_float">-float, -no_float</A></H2>
  175. <P>Almost every OP has an op_next and an op_sibling pointer, and B::Graph
  176. colors them distinctively (pink and light blue, respectively). Because of
  177. this, it isn't strictly necessary to 'anchor' the arrow on a line in
  178. the OP's box saying 'op_next'. To avoid these extra lines, you can use
  179. the 'float' option. Unlabeled arrows can be confusing, though, so the
  180. default is not to float.</P>
  181. <P>
  182. <H2><A NAME="targlinks, no_targlinks">-targlinks, -no_targlinks</A></H2>
  183. <P>Lexical (my()) variables and temporary values used by individual OPs
  184. are stored in 'pads', per-code arrays linked to the CV. OPs store
  185. indexes into these arrays in the 'op_targ' field, but B::Graph can
  186. often also draw links directly from the OP to the SV that stores the
  187. name of the variable. These links don't correspond to any real pointers,
  188. however, and they can make the graph more complicated, so they are
  189. disabled by default.</P>
  190. <P>
  191. <HR>
  192. <H1><A NAME="what does this all mean">WHAT DOES THIS ALL MEAN?</A></H1>
  193. <P>
  194. <H2><A NAME="svflags abbreviations">SvFLAGS abbreviations</A></H2>
  195. <PRE>
  196.     Pb     SVs_PADBUSY   reserved for tmp or my already
  197.     Pt     SVs_PADTMP    in use as tmp
  198.     Pm     SVs_PADMY     in use a "my" variable
  199.     T      SVs_TEMP      string is stealable?
  200.     O      SVs_OBJECT    is "blessed"
  201.     Mg     SVs_GMG       has magical get method
  202.     Ms     SVs_SMG       has magical set method
  203.     Mr     SVs_RMG       has random magical methods
  204.     I      SVf_IOK       has valid public integer value
  205.     N      SVf_NOK       has valid public numeric (float) value
  206.     P      SVf_POK       has valid public pointer (string) value
  207.     R      SVf_ROK       has a valid reference pointer
  208.     F      SVf_FAKE      glob or lexical is just a copy
  209.     L      SVf_OOK       has valid offset value (mnemonic: lvalue)
  210.     B      SVf_BREAK     refcnt is artificially low
  211.     Ro     SVf_READONLY  may not be modified
  212.     i      SVp_IOK       has valid non-public integer value
  213.     n      SVp_NOK       has valid non-public numeric value
  214.     p      SVp_POK       has valid non-public pointer value
  215.     S      SVp_SCREAM    has been studied?
  216.     V      SVf_AMAGIC    has magical overloaded methods</PRE>
  217. <P>
  218. <H2><A NAME="op_flags abbreviations">op_flags abbreviations</A></H2>
  219. <PRE>
  220.     V      OPf_WANT_VOID    Want nothing (void context)
  221.     S      OPf_WANT_SCALAR  Want single value (scalar context)
  222.     L      OPf_WANT_LIST    Want list of any length (list context)
  223.     K      OPf_KIDS         There is a firstborn child.
  224.     P      OPf_PARENS       This operator was parenthesized.
  225.                              (Or block needs explicit scope entry.)
  226.     R      OPf_REF          Certified reference.
  227.                              (Return container, not containee).
  228.     M      OPf_MOD          Will modify (lvalue).
  229.     T      OPf_STACKED      Some arg is arriving on the stack.
  230.     *      OPf_SPECIAL      Do something weird for this op (see op.h)</PRE>
  231. <P>
  232. <HR>
  233. <H1><A NAME="bugs">BUGS</A></H1>
  234. <P>VCG has a problem with boxes that have more than about 55 arrows
  235. coming out of them, so with large arrays and hashes B::Graph will
  236. stop outputting edges and some boxes may be disconnected.</P>
  237. <P>
  238. <HR>
  239. <H1><A NAME="author">AUTHOR</A></H1>
  240. <P>Stephen McCamant <<A HREF="mailto:alias@mcs.com">alias@mcs.com</A>></P>
  241. <P>
  242. <HR>
  243. <H1><A NAME="see also">SEE ALSO</A></H1>
  244. <P><EM>dot(1)</EM>, <EM>xvcg(1)</EM>, <EM>perl(1)</EM>, <EM>perlguts(1)</EM>.</P>
  245. <P>If you like B::Graph, you might also be interested in Gisle Aas's
  246. PerlGuts Illustrated, at <CODE>http://home.sol.no/~aas/perl/guts/</CODE>.</P>
  247. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  248. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  249. <STRONG><P CLASS=block> B::Graph - Perl compiler backend to produce graphs of OP trees</P></STRONG>
  250. </TD></TR>
  251. </TABLE>
  252.  
  253. </BODY>
  254.  
  255. </HTML>
  256.