ruby-vpi 8.2.0 → 9.0.0

data/HEADER

@@ -2,25 +2,6 @@
   <link rel="stylesheet" type="text/css" href="style.css" />
 </head>
 
-h1{text-align: center}. Welcome to Ruby-VPI
-
-Ruby-VPI is a "Ruby interface":http://ruby-lang.org to "Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945. It lets you create complex Verilog test benches easily and wholly in Ruby.
-
-h2. Features
-
-* Prototype and verify designs _quickly_ using "BDD(behavior-driven development)":http://behaviour-driven.org/, "TDD(test-driven development)":http://www.agiledata.org/essays/tdd.html, and more.
-* Reuse the _same_ specification to verify both prototype and design.
-* Specifications are executable _and_ human-readable. (See this <a href="./doc/usage.tutorial.html#fig..counter_rspecTest_spec.rb">example specification</a> and its <a href="./doc/usage.tutorial.html#fig..test-proto.rspec">boss-friendly output</a>.)
-
-
-* Utilize Ruby's power and elegance. ("Why choose Ruby?":http://www.ruby-doc.org/whyruby)
-** Built-in support for unlimited length integers, regular expressions, networking, multi-threading, system calls, _ad infinium_!
-** Easy to use; doesn't get in your way.
-** Makes programming _fun_ again!
-
-* Study, modify, or distribute this is free software, released under the "GNU General Public License":http://www.gnu.org/copyleft/gpl.html, as you see fit.
-
-
 <div class="variablelist">
 <dl>
 

data/HISTORY

@@ -12,12 +12,52 @@ We _strictly_ follow the RubyGems project's "rational versioning policy":http://
 fn1. C. Gross, "Explaining Open Source Version Numbers", [Online document], 2005 Nov 28, [cited 2006 Aug 27], Available HTTP: "http://ablog.apress.com/?p=738":http://ablog.apress.com/?p=738
 
 
+h1. Version 9.0.0 (2006-10-28)
+
+h2. Summary
+
+This release improves the automated test generator and adds new content to the user manual.
+
+h2. Acknowledgments
+
+Thanks to Matt Fischler for helping test and debug the installation of Ruby-VPI on Windows.
+
+h2. Notice
+
+* The command-line options for @generate_test.rb@ have changed. Run the command @generate_test.rb --help@ for details.
+
+h2. Details
+
+* Test runners now attempt to resolve paths in @SIMULATOR_SOURCES@ by searching for them within the directories specified in @SIMULATOR_INCLUDES@.
+
+* Synopsys VCS is now used in a better way (via the @-load@ option).
+** The old PLI table file (@synopsys_vcs.tab@) has been removed.
+** The C extension has been revised accordingly.
+
+** The C extension now compiles without errors in Cygwin.
+
+* The automated test generator now:
+** Only creates output files when necessary.
+** Updates existing output files using "text merging tools":./doc/usage.recommendations.html if possible. (Refer to @MERGER@ in the help information of @generate_test.rb@.)
+** Emits progress information similar to Ruby on Rails.
+
+* The user manual now:
+** Includes instructions for installing on Windows (via Cygwin).
+** Has a recommended software section, with links to text merging tools.
+** Uses the term "xUnit":http://en.wikipedia.org/wiki/XUnit instead of "unit test".
+** Correctly spells "rSpec".
+
+
 h1. Version 8.2.0 (2006-10-24)
 
 h2. Summary
 
 This release simplifies configuration of generated tests.
 
+h2. Acknowledgments
+
+Thanks to "students in CMPE-126":http://www.soe.ucsc.edu/classes/cmpe126/Fall06/ for their constructive criticism.
+
 h2. Notice
 
 * Generated runners now have a @SIMULATOR_INCLUDES@ array, whose entries specify places where Verilog source files, needed by the Verilog design, reside.

data/README

@@ -1,3 +1,21 @@
+h1{text-align: center}. Welcome to Ruby-VPI
+
+Ruby-VPI is a "Ruby interface":http://ruby-lang.org to "Verilog VPI":http://ieeexplore.ieee.org/xpl/standardstoc.jsp?isnumber=33945. It lets you create complex Verilog test benches easily and wholly in Ruby.
+
+h2. Features
+
+* Prototype and verify designs _quickly_ using "BDD(behavior-driven development)":http://behaviour-driven.org/, "TDD(test-driven development)":http://www.agiledata.org/essays/tdd.html, and more.
+* Reuse the _same_ specification to verify both prototype and design.
+* Specifications are executable _and_ human-readable. (See this <a href="./doc/usage.tutorial.html#fig..counter_rspecTest_spec.rb">example specification</a> and its <a href="./doc/usage.tutorial.html#fig..test-proto.rspec">boss-friendly output</a>.)
+
+* Utilize Ruby's power and elegance. ("Why choose Ruby?":http://www.ruby-doc.org/whyruby)
+** Built-in support for unlimited length integers, regular expressions, networking, multi-threading, system calls, _ad infinium_!
+** Easy to use; doesn't get in your way.
+** Makes programming _fun_ again!
+
+* Study, modify, or distribute this free software in accordance with the "GNU General Public License":http://www.gnu.org/copyleft/gpl.html.
+
+
 h1. Getting started
 
 * See the "user manual":./doc to begin using Ruby-VPI.
@@ -9,9 +27,9 @@ h1. Getting started
 * Visit the "project website":http://ruby-vpi.rubyforge.org for additional resources.
 
 
-h1. Compiling from source
+h1. Building release packages
 
-In addition to the "normal requirements":./doc/usage.requirements.html, you need the following software to compile from source:
+In addition to the "normal requirements":./doc/usage.requirements.html, you need the following software to build release packages:
 
 * "DocBook-XML":http://www.docbook.org/
 ** xsltproc

data/Rakefile

@@ -1,3 +1,6 @@
+# = Environment variables
+# CFLAGS:: Arguments to the compiler.
+# LDFLAGS:: Arguments to the linker.
 =begin
   Copyright 2006 Suraj N. Kurapati
 
@@ -18,6 +21,8 @@
   Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 =end
 
+CFLAGS, LDFLAGS = ENV['CFLAGS'], ENV['LDFLAGS']
+
 require 'rake/clean'
 require 'rake/rdoctask'
 require 'rake/gempackagetask'
@@ -25,15 +30,14 @@ require 'rake/gempackagetask'
 require 'tempfile'
 require 'rbconfig'
 
-$:.unshift File.join(File.dirname(__FILE__), 'lib')
+PROJECT_LIBS = File.join(File.dirname(__FILE__), 'lib')
+
+$:.unshift PROJECT_LIBS
+require 'ruby-vpi'
 require 'ruby-vpi/rake'
 
 
-PROJECT_ID = 'ruby-vpi'
-PROJECT_NAME = 'Ruby-VPI'
-PROJECT_URL = "http://#{PROJECT_ID}.rubyforge.org"
-PROJECT_SUMMARY = "Ruby interface to Verilog VPI."
-PROJECT_DETAIL = "#{PROJECT_NAME} is a #{PROJECT_SUMMARY}. It lets you create complex Verilog test benches easily and wholly in Ruby."
+include RubyVpi::Config
 PROJECT_SSH_URL = "snk@rubyforge.org:/var/www/gforge-projects/#{PROJECT_ID}"
 
 File.read('HISTORY') =~ /Version\s+([\d\.]+)\s*\((.*?)\)/
@@ -56,13 +60,18 @@ end
 
 task :default => :build
 
-task :clobber do |t|
-  files = FileList['**/Rakefile'].exclude('_darcs')
-  files.shift # avoid infinite loop on _this_ file
+[:clean, :clobber].each do |t|
+  task t do
+    files = FileList['**/Rakefile'].exclude('_darcs')
+    files.shift # avoid infinite loop on _this_ file
+
+    # allows propogation to lower levels when gem not installed
+    ENV['RUBYLIB'] = PROJECT_LIBS
 
-  files.each do |f|
-    cd File.dirname(f) do
-      sh 'rake', t.name
+    files.each do |f|
+      cd File.dirname(f) do
+        sh 'rake', t.to_s
+      end
     end
   end
 end
@@ -74,46 +83,33 @@ end
 desc "Builds object files for all simulators."
 task :build
 
-DEFAULT_SHARED_OBJ = "#{PROJECT_ID}.so"
-DEFAULT_NORMAL_OBJ = "#{PROJECT_ID}.o"
-
 directory 'obj'
 CLOBBER.include 'obj'
 
-{
-  :cver => ['-DPRAGMATIC_CVER', '-export-dynamic'],
-  :ivl => ['-DICARUS_VERILOG'],
-  :vcs => ['-DSYNOPSYS_VCS'],
-  :vsim => ['-DMENTOR_MODELSIM'],
-}.each_pair do |target, (cflags, ldflags)|
 
-  # object files that are needed to be built
-  objFiles = [DEFAULT_NORMAL_OBJ, DEFAULT_SHARED_OBJ].inject({}) do |memo, src|
-    dstName = src.sub(/#{File.extname src}$/, ".#{target}\\&")
-    dst = File.expand_path(File.join('obj', dstName))
+SIMULATORS.each do |sim|
+  taskName = "build_#{sim.id}"
 
-    memo[src] = dst
-    memo
-  end
+  desc "Builds object files for #{sim.name} simulator."
+  task taskName => ['obj', 'ext'] do
+    src = "#{PROJECT_ID}.so"
+    dst = "#{PROJECT_ID}.#{sim.id}.so"
 
-  # task to build the object files
-  targetTask = "build_#{target}"
+    dst = File.expand_path(File.join('obj', dst))
 
-  desc "Builds object files for #{target} simulator."
-  task targetTask => ['obj', 'ext'] do |t|
-    unless objFiles.values.reject {|f| File.exist? f}.empty?
-      cd t.prerequisites[1] do
-        ENV['CFLAGS'], ENV['LDFLAGS'] = cflags, ldflags
-        sh %w(rake clean default)
+    unless File.exist? dst
+      cd 'ext' do
+        ENV['CFLAGS'] = "#{CFLAGS} #{sim.compiler_args}"
+        ENV['LDFLAGS'] = "#{LDFLAGS} #{sim.linker_args}"
 
-        objFiles.each_pair do |src, dst|
-          mv src, dst
-        end
+        sh 'rake'
+        mv src, dst
+        sh 'rake clean'
       end
     end
   end
 
-  task :build => targetTask
+  task :build => taskName
 end
 
 
@@ -192,7 +188,7 @@ task :dist_info => distDocs
 
 desc "Prepare for distribution."
 task :dist => ['ext', :doc, :dist_info] do |t|
-  cd t.prerequisites[0] do
+  cd 'ext' do
     sh 'rake swig'
   end
 end
@@ -274,7 +270,7 @@ end
 desc "Ensure that examples work with $SIMULATOR"
 task :test => :build do
   # ensures that current sources are tested instead of the installed gem
-  ENV['RUBYLIB'] = File.join(File.dirname(__FILE__), 'lib')
+  ENV['RUBYLIB'] = PROJECT_LIBS
 
   FileList['samp/*/'].each do |s|
     cd s do

data/bin/generate_test.rb

@@ -1,8 +1,18 @@
 #!/usr/bin/ruby -w
 # Generates Ruby-VPI tests from Verilog 2001 module declarations.
-# * If no input files are specified, then the standard input stream is assumed to be the input.
+# * The standard input stream is read if no input files are specified.
 # * The first input signal in a module's declaration is assumed to be the clocking signal.
-# * Existing output files will be backed-up before being over-written. A backed-up file has a tilde (~) appended to its name.
+#
+# = Progress indicators
+# As this tool performs its duties, it notifies you of important information using the following indicators.
+#
+# create:: Output file does not exist. It will be created.
+# skip:: Output file exists and is up to date.
+# update:: Output file exists and is out of date. A backup copy will be made (with a ".old" suffix) before this output file is updated. Use a text merging tool or manually transfer any necessary information from the backup copy to the updated output file.
+#
+# = Environment variables
+# MERGER:: A command for invoking a text merging tool with two arguments: old file, new file. The tool should save its output to the new file.
+
 
 =begin
   Copyright 2006 Suraj N. Kurapati
@@ -25,24 +35,39 @@
 =end
 
 require 'ruby-vpi/verilog_parser'
+require 'fileutils'
+require 'digest/md5'
 
 
-require 'fileutils'
+# Notify the user about some action being performed.
+def notify *args
+  printf "%8s  %s\n", *args
+end
 
-# Writes the given contents to the file at the given path. If the given path already exists, then a backup is created before proceeding.
+# Writes the given contents to the file at the given path. If the given path already exists, then a backup is created before invoking the merging tool.
 def write_file aPath, aContent
-  # create a backup
-    if File.exist? aPath
-      backupPath = aPath.dup
+  if File.exist? aPath
+    oldDigest = Digest::MD5.digest(File.read(aPath))
+    newDigest = Digest::MD5.digest(aContent)
 
-      while File.exist? backupPath
-        backupPath << '~'
-      end
+    if oldDigest == newDigest
+      notify :skip, aPath
+    else
+      notify :update, aPath
 
-      FileUtils.cp aPath, backupPath, :preserve => true
-    end
+      old, new = "#{aPath}.old", aPath
 
-  File.open(aPath, 'w') {|f| f << aContent}
+      FileUtils.cp aPath, old, :preserve => true
+      File.open(new, 'w') {|f| f << aContent}
+
+      if m = ENV['MERGER']
+        system "#{m} #{old.inspect} #{new.inspect}"
+      end
+    end
+  else
+    notify :create, aPath
+    File.open(aPath, 'w') {|f| f << aContent}
+  end
 end
 
 
@@ -65,7 +90,7 @@ class OutputInfo
   VERILOG_EXT = '.v'
   RUNNER_EXT = '.rake'
 
-  SPEC_FORMATS = [:RSpec, :UnitTest, :Generic]
+  SPEC_FORMATS = [:rSpec, :xUnit, :generic]
 
   attr_reader :verilogBenchName, :verilogBenchPath, :rubyBenchName, :rubyBenchPath, :designName, :designClassName, :designPath, :specName, :specClassName, :specFormat, :specPath, :rubyVpiPath, :runnerName, :runnerPath, :protoName, :protoPath, :protoClassName
 
@@ -124,7 +149,7 @@ if File.basename($0) == File.basename(__FILE__)
   # parse command-line options
     require 'optparse'
 
-    optSpecFmt = :Generic
+    optSpecFmt = :generic
     optTestName = 'test'
 
     opts = OptionParser.new
@@ -138,12 +163,12 @@ if File.basename($0) == File.basename(__FILE__)
       exit
     end
 
-    opts.on '-u', '--unit', 'use Test::Unit specification format' do |val|
-      optSpecFmt = :UnitTest if val
+    opts.on '-u', '--xunit', 'use xUnit specification format' do |val|
+      optSpecFmt = :xUnit if val
     end
 
-    opts.on '-r', '--rspec', 'use RSpec specification format' do |val|
-      optSpecFmt = :RSpec if val
+    opts.on '-s', '--rspec', 'use rSpec specification format' do |val|
+      optSpecFmt = :rSpec if val
     end
 
     opts.on '-n', '--name NAME', 'attach NAME indentifier to generated test' do |val|
@@ -152,36 +177,26 @@ if File.basename($0) == File.basename(__FILE__)
 
     opts.parse! ARGV
 
-  puts "Using name #{optTestName.inspect} for generated test."
-  puts "Using #{optSpecFmt} specification format."
+    notify :name, optTestName
+    notify :format, optSpecFmt
 
 
   v = VerilogParser.new(ARGF.read)
 
   v.modules.each do |m|
-    puts '', "Parsed module: #{m.name}"
+    puts
+    notify :module, m.name
 
-    o = OutputInfo.new(m.name, optSpecFmt, optTestName, File.dirname(File.dirname(__FILE__))).freeze
+    o = OutputInfo.new(m.name, optSpecFmt, optTestName, File.dirname(File.dirname(__FILE__)))
 
     # generate output
-      aParseInfo, aModuleInfo, aOutputInfo = v, m, o
+      aParseInfo, aModuleInfo, aOutputInfo = v.freeze, m.freeze, o.freeze
 
       write_file o.runnerPath, RUNNER_TEMPLATE.result(binding)
-      puts "- Generated runner:           #{o.runnerPath}"
-
       write_file o.verilogBenchPath, VERILOG_BENCH_TEMPLATE.result(binding)
-      puts "- Generated bench:            #{o.verilogBenchPath}"
-
       write_file o.rubyBenchPath, RUBY_BENCH_TEMPLATE.result(binding)
-      puts "- Generated bench:            #{o.rubyBenchPath}"
-
       write_file o.designPath, DESIGN_TEMPLATE.result(binding)
-      puts "- Generated design:           #{o.designPath}"
-
       write_file o.protoPath, PROTO_TEMPLATE.result(binding)
-      puts "- Generated prototype:        #{o.protoPath}"
-
       write_file o.specPath, SPEC_TEMPLATE.result(binding)
-      puts "- Generated specification:    #{o.specPath}"
   end
 end

data/bin/generate_test_tpl/bench.rb

@@ -3,11 +3,11 @@
 require 'ruby-vpi'
 <%
   case aOutputInfo.specFormat
-    when :UnitTest
+    when :xUnit
 %>
 require 'test/unit'
 <%
-    when :RSpec
+    when :rSpec
 %>
 require 'ruby-vpi/rspec'
 <%
@@ -19,7 +19,7 @@ RubyVpi.init_bench '<%= aModuleInfo.name + aOutputInfo.suffix %>', :<%= aOutputI
 # service the $ruby_relay callback
 <%
   case aOutputInfo.specFormat
-    when :UnitTest, :RSpec
+    when :xUnit, :rSpec
 %>
   # The <%= aOutputInfo.specFormat %> library will take control henceforth.
 <%

data/bin/generate_test_tpl/bench.v

@@ -35,7 +35,7 @@ module <%= aOutputInfo.verilogBenchName %>;
     initial begin
       <%= clockSignal %> = 0;
       $ruby_init("ruby", "-w", "-rubygems", "<%= aOutputInfo.rubyBenchPath %>"<%=
-        %{, "-f", "s"} if aOutputInfo.specFormat == :RSpec
+        %{, "-f", "s"} if aOutputInfo.specFormat == :rSpec
       %>);
     end
 

data/bin/generate_test_tpl/runner.rake

@@ -1,11 +1,12 @@
 ## This file builds and runs the test.
 
-# These are source files that are to be simulated.
+# These are source files that are to be compiled.
 SIMULATOR_SOURCES = [
   '<%= aOutputInfo.verilogBenchPath %>',
 ]
 
-# These are paths to directories which contain dependencies for the sources listed above.
+# These are paths to directories which contain the
+# sources listed above, their dependencies, or both.
 SIMULATOR_INCLUDES = []
 
 # This specifies the "top module" that is to be simulated.