[llvm-commits] CVS: llvm/docs/TestingGuide.html

[Reid Spencer]

Changes in directory llvm/docs:

TestingGuide.html updated: 1.42 -> 1.43
---
Log message:

Describe quoting rules.


---
Diffs of the changes:  (+47 -5)

 TestingGuide.html |   52 +++++++++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 47 insertions(+), 5 deletions(-)


Index: llvm/docs/TestingGuide.html
diff -u llvm/docs/TestingGuide.html:1.42 llvm/docs/TestingGuide.html:1.43
--- llvm/docs/TestingGuide.html:1.42	Sat Apr 14 18:27:06 2007
+++ llvm/docs/TestingGuide.html	Sun Apr 15 03:01:04 2007
@@ -323,6 +323,13 @@
   any process in the pipeline fails, the entire line (and test case) fails too.
   </p>
 
+  <p> Below is an example of legal RUN lines in a <tt>.ll</tt> file:</p>
+  <pre>
+  ; RUN: llvm-as < %s | llvm-dis > %t1
+  ; RUN: llvm-dis < %s.bc-13 > %t2
+  ; RUN: diff %t1 %t2
+  </pre>
+
   <p>As with a Unix shell, the RUN: lines permit pipelines and I/O redirection
   to be used. However, the usage is slightly different than for Bash. To check
   what's legal, see the documentation for the 
@@ -341,12 +348,47 @@
     shouldn't use that here.</li>
   </ul>
 
-  <p> Below is an example of legal RUN lines in a <tt>.ll</tt> file:</p>
+  <p>There are some quoting rules that you must pay attention to when writing
+  your RUN lines. In general nothing needs to be quoted. Tcl won't strip off any
+  ' or " so they will get passed to the invoked program. For example:</p>
   <pre>
-  ; RUN: llvm-as < %s | llvm-dis > %t1
-  ; RUN: llvm-dis < %s.bc-13 > %t2
-  ; RUN: diff %t1 %t2
+     ... | grep 'find this string'
   </pre>
+  <p>This will fail because the ' characters are passed to grep. This would
+  instruction grep to look for <tt>'find</tt> in the files <tt>this</tt> and
+  <tt>string'</tt>. To avoid this use curly braces to tell Tcl that it should
+  treat everything enclosed as one value. So our example would become:</p>
+  <pre>
+     ... | grep {find this string}
+  </pre>
+  <p>Additionally, the characters <tt>[</tt> and <tt>]</tt> are treated 
+  specially by Tcl. They tell Tcl to interpret the content as a command to
+  execute. Since these characters are often used in regular expressions this can
+  have disastrous results and cause the entire test run in a directory to fail.
+  For example, a common idiom is to look for some basicblock number:</p>
+  <pre>
+     ... | grep bb[2-8]
+  </pre>
+  <p>This, however, will cause Tcl to fail because its going to try to execute
+  a program named "2-8". Instead, what you want is this:</p>
+  <pre>
+     ... | grep {bb\[2-8\]}
+  </pre>
+  <p>Finally, if you need to pass the <tt>\</tt> character down to a program,
+  then it must be doubled. This is another Tcl special character. So, suppose
+  you had:
+  <pre>
+     ... | grep 'i32\*'
+  </pre>
+  <p>This will fail to match what you want (a pointer to i32). First, the
+  <tt>'</tt> do not get stripped off. Second, the <tt>\</tt> gets stripped off
+  by Tcl so what grep sees is: <tt>'i32*'</tt>. That's not likely to match
+  anything. To resolve this you must use <tt>\\</tt> and the <tt>{}</tt>, like
+  this:</p>
+  <pre>
+     ... | grep {i32\\*}
+  </pre>
+
 </div>
 
 <!-- _______________________________________________________________________ -->
@@ -774,7 +816,7 @@
 
   John T. Criswell, Reid Spencer, and Tanya Lattner<br>
   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
-  Last modified: $Date: 2007/04/14 23:27:06 $
+  Last modified: $Date: 2007/04/15 08:01:04 $
 </address>
 </body>
 </html>