manual.doc in ruby-vpi-12.1.0

- old
+ new

@@ -240,10 +240,11 @@
 
 <% tip "Add support for your Verilog simulator" do %>
 Write a "support request":http://rubyforge.org/tracker/?group_id=1339 for your simulator, while providing a sample transcript of the commands you use to run a test with your simulator, and we will add support for your simulator in the next release!
 <% end %>
 
+
 * *make*
   - any distribution should be acceptable.
 
 * C compiler
   - the "GNU Compiler Collection (GCC)":http://www.gnu.org/software/gcc/ is preferred, but any C compiler should be acceptable.
@@ -273,11 +274,11 @@
 ** "*imediff2*":http://elonen.iki.fi/code/imediff/ is a textual, fullscreen two-way merging tool. It is very useful when you are working remotely via SSH.
 
 
 h2(#setup.installation). Installation
 
-Once you have satisfied the "necessary requirements":#setup.reqs, you can install Ruby-VPI by running the <pre>gem install ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a "gems" subdirectory which contains the Ruby-VPI installation, as illustrated below.
+Once you have satisfied the "necessary requirements":#setup.reqs, you can install Ruby-VPI by running the <pre>gem install -y ruby-vpi</pre> command. RubyGems will install Ruby-VPI into the system gem directory, whose path can be determined by running the <pre>gem env gemdir</pre> command. Within this directory, there is a <tt>gems/</tt> subdirectory which contains the Ruby-VPI installation, as illustrated below.
 
 <pre>
 $ gem env gemdir
 /usr/lib/ruby/gems/1.8
 
@@ -582,21 +583,82 @@
 </pre>
 <% end %>
 
 In these examples, the @PROTOTYPE@ environment variable is _not_ specified while running the test, so that our design, instead of our prototype, is verified against our specification. You can also achieve this effect by assigning an empty value to @PROTOTYPE@, or by using your shell's *unset* command. Finally, the "GPL Cver simulator":#setup.reqs, denoted by _cver_, is used to run the simulation.
 
+
+h2(#usage.test-runner). Test runner
+
+A test runner is a file, generated by the "automated test generator":#usage.tools.generate-test, whose name ends with <tt>.rake</tt>. It helps you run generated tests -- you can think of it as a _makefile_ if you are familiar with C programming in a UNIX environment.
+
+<% example "Seeing what a test runner can do" do %>
+When you invoke a test runner without any arguments, it will show you a list of available tasks:
+<pre>$ rake -f some_test_runner.rake
+
+<%= `rake -f ../samp/counter/counter_rspec_runner.rake` %></pre>
+<% end %>
+
 <% tip "Running multiple tests at once." do %>
 Create a file named <tt>Rakefile</tt> containing the following line.
 
 bq. @require 'ruby-vpi/runner_proxy'@
 
 Now you can invoke all test runners in the current directory simply by executing <pre>rake cver</pre> (where _cver_ denotes the "GPL Cver simulator":#setup.reqs).
 <% end %>
 
 
-h2(#usage.examples). Examples
+h3(#usage.test-runner.env-vars). Environment variables
 
-The <tt>samp</tt> directory contains several example tests which illustrate how Ruby-VPI can be used. Each example has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
+Test runners support the following _environment_ variables, which allow you to easily change the behavior of the test runner.
+
+* @COVERAGE@ enables code coverage analysis and generation of code coverage reports.
+* @DEBUG@ enables the "interactive debugger":#usage.debugger in its "post-mortem debugging mode":http://www.datanoise.com/articles/2006/12/20/post-mortem-debugging.
+* @PROTOTYPE@ enables the Ruby prototype for the design under test.
+
+To activate these variables, simply assign a non-empty value to them. For example, @DEBUG=1@ and @DEBUG=yes@ and @DEBUG=foo_bar_baz@ all activate the @DEBUG@ variable.
+
+To deactivate these variables, simply assign an _empty_ value to them, *unset* them in your shell, or do not specify them as command-line arguments to rake. For example, both @DEBUG=@ dectivates the @DEBUG@ variable.
+
+In addition, you can specify variable assignments as arguments to the *rake* command. For example, <pre>rake DEBUG=1</pre> is equivalent to <pre>
+$ DEBUG=1
+$ export DEBUG
+$ rake
+</pre> in Bourne shell or <pre>
+% setenv DEBUG 1
+% rake
+</pre> in C shell.
+
+<% example "Running a test with environment variables" do %>
+
+Here we enable the prototype and code coverage analysis:
+<pre>rake -f some_test_runner.rake PROTOTYPE=1 COVERAGE=1</pre>
+
+Here we _disable_ the prototype and enable the code coverage analysis. Note that both of these invocations are equivalent:
+<pre>rake -f some_test_runner.rake PROTOTYPE= COVERAGE=1</pre>
+<pre>rake -f some_test_runner.rake COVERAGE=1</pre>
+<% end %>
+
+
+h2(#usage.debugger). Interactive debugger
+
+The "ruby-debug project":http://www.datanoise.com/articles/category/ruby-debug serves as the interactive debugger for Ruby-VPI.
+
+# Enable the debugger by activating the @DEBUG@ environment variable (see <xref #usage.test-runner> for details).
+# Put the @debugger@ command in your code -- anywhere you wish to activate an interactive debugging session. These commands are automatically ignored when the debugger is disabled; so you can safely leave them in your code, if you wish.
+
+
+h3(#usage.debugger.init). Advanced initialization
+
+By default, Ruby-VPI enables the debugger by invoking the @Debugger.start@ method. If you wish to perform more advanced initialization, such as having the debugger accept remote network connections for interfacing with a remote debugging session or perhaps with an IDE (see "the ruby-debug documentation":http://www.datanoise.com/articles/category/ruby-debug for details), then:
+
+# Deactivate the @DEBUG@ environment variable.
+# Put your own code, which initializes the debugger, above the @RubyVpi.init_bench@ line in your generated <tt>spec.rb</tt> file.
+
+
+
+h2(#usage.examples). Sample tests
+
+The <tt>samp</tt> directory contains several sample tests which illustrate how Ruby-VPI can be used. Each sample has an associated <tt>Rakefile</tt> which simplifies the process of running it. Therefore, simply navigate into an example directory and run the <pre>rake</pre> command to get started.
 
 
 h1(#hacking). Hacking
 
 h2(#hacking.release-packages). Building release packages