feat: add --out-dir option

Author: zah

README.md

@@ -6,31 +6,34 @@ A recorder of Ruby programs that produces [CodeTracer](https://github.com/metacr
 > Currently it is in a very early phase: we're welcoming contribution and discussion!
 
 
-### usage
+### Usage
 
 you can currently use it directly with
 
 ```bash
-ruby trace.rb <path to ruby file>
-# produces several trace json files in the current directory
-# or in the folder of `$CODETRACER_DB_TRACE_PATH` if such an env var is defined
+ruby trace.rb [--out-dir DIR] <path to ruby file>
+# produces several trace json files in DIR,
+# or in `$CODETRACER_RUBY_RECORDER_OUT_DIR` if DIR is not provided.
+# Defaults to the current directory.
+# Pass --help to list all options.
 ```
 
 You can also invoke a lightweight CLI that loads the native tracer extension
 directly:
 
 ```bash
-ruby src/native_trace.rb <path to ruby file>
+ruby src/native_trace.rb [--out-dir DIR] <path to ruby file>
+# Uses DIR or `$CODETRACER_RUBY_RECORDER_OUT_DIR` to choose where traces are saved.
 ```
 
 however you probably want to use it in combination with CodeTracer, which would be released soon.
 
-### env variables
+### ENV variables
 
 * if you pass `CODETRACER_RUBY_TRACER_DEBUG=1`, you enables some additional debug-related logging
-* `CODETRACER_DB_TRACE_PATH` can be used to override the path to `trace.json` (it's used internally by codetracer as well)
+* `CODETRACER_RUBY_RECORDER_OUT_DIR` can be used to specify the directory for trace files
 
-## future directions
+## Future directions
 
 The current Ruby support is a prototype. In the future, it may be expanded to function in a way to similar to the more complete implementations, e.g. [Noir](https://github.com/blocksense-network/noir/tree/blocksense/tooling/tracer).
 

ext/native_tracer/README.md

@@ -20,8 +20,9 @@ The produced shared library can be required from Ruby:
 require_relative 'target/release/libcodetracer_ruby_recorder'
 ```
 
-Once loaded, the tracer starts writing a trace to `trace.json` or the
-path specified via the `CODETRACER_DB_TRACE_PATH` environment variable.
+Once loaded, the tracer starts writing a trace to `trace.json` in the
+directory specified via the `CODETRACER_RUBY_RECORDER_OUT_DIR` environment
+variable (defaults to the current directory).
 
 ## Publishing platform-specific gems
 

src/native_trace.rb

@@ -2,11 +2,29 @@
 # SPDX-License-Identifier: MIT
 # Simple utility loading the native tracer extension and executing a program.
 
+require 'optparse'
+
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = "usage: ruby native_trace.rb [options] <program> [args]"
+  opts.on('-o DIR', '--out-dir DIR', 'Directory to write trace files') do |dir|
+    options[:out_dir] = dir
+  end
+  opts.on('-h', '--help', 'Print this help') do
+    puts opts
+    exit
+  end
+end
+parser.order!
+
 if ARGV.empty?
-  $stderr.puts("usage: ruby native_trace.rb <program> [args]")
+  $stderr.puts parser
   exit 1
 end
 
+out_dir = options[:out_dir] || ENV['CODETRACER_RUBY_RECORDER_OUT_DIR'] || Dir.pwd
+ENV['CODETRACER_RUBY_RECORDER_OUT_DIR'] = out_dir
+
 # Path to the compiled native extension
 ext_path = File.expand_path('../ext/native_tracer/target/release/libcodetracer_ruby_recorder', __dir__)
 require ext_path

src/recorder.rb

@@ -42,7 +42,7 @@ def to_data_for_json
     {variable_id: self.variable_id, value: value.to_data_for_json}
   end
 end
- 
+
 
 ValueRecord = Struct.new(:kind, :type_id, :i, :b, :text, :r, :msg, :elements, :is_slice, :field_values, keyword_init: true) do
   def to_data_for_json
@@ -108,7 +108,7 @@ def to_data_for_json
 class TraceRecord
   # part of the final trace
   attr_accessor :steps, :calls, :variables, :events, :types, :flow, :paths
-  
+
   # internal helpers
   attr_accessor :stack, :step_stack, :exprs, :tracing
   attr_accessor :t1, :t2, :t3, :t4 # tracepoints
@@ -166,7 +166,7 @@ def path_id(path)
       path_id
     end
   end
-  
+
   def register_step(path, line)
     step_record = StepRecord.new(self.path_id(path), line)
     @events << [:Step, step_record] # because we convert later to {Step: step-record}: default enum json format in serde/rust
@@ -245,7 +245,7 @@ def load_exprs(path)
     {}
   end
 
-  def serialize(program)
+  def serialize(program, out_dir = nil)
     if ENV["CODETRACER_RUBY_TRACER_DEBUG"] == "1"
       pp @events
     end
@@ -258,22 +258,25 @@ def serialize(program)
       workdir: Dir.pwd
     }
     # pp output
-    
+
     json_output = JSON.pretty_generate(output)
     metadata_json_output = JSON.pretty_generate(metadata_output)
     paths_json_output = JSON.pretty_generate($codetracer_record.paths)
 
-    trace_path = ENV["CODETRACER_DB_TRACE_PATH"] || "trace.json"
-    trace_folder = File.dirname(trace_path)
+    out_dir = out_dir.nil? || out_dir.empty? ?
+      (ENV["CODETRACER_RUBY_RECORDER_OUT_DIR"] || ".") : out_dir
+
+    trace_folder = out_dir
     FileUtils.mkdir_p(trace_folder)
-    trace_metadata_path = File.join(trace_folder , "trace_metadata.json")
-    trace_paths_path = File.join(trace_folder , "trace_paths.json")
-    
+    trace_path = File.join(trace_folder, "trace.json")
+    trace_metadata_path = File.join(trace_folder, "trace_metadata.json")
+    trace_paths_path = File.join(trace_folder, "trace_paths.json")
+
     # p trace_path, json_output
     File.write(trace_path, json_output)
     File.write(trace_metadata_path, metadata_json_output)
     File.write(trace_paths_path, paths_json_output)
-    
+
     $stderr.write("=================================================\n")
     $stderr.write("codetracer ruby tracer: saved trace to #{trace_folder}\n")
   end

src/trace.rb

@@ -3,6 +3,7 @@
 # See LICENSE file in the project root for full license information.
 
 require 'json'
+require 'optparse'
 require_relative 'recorder'
 
 # Warning:
@@ -172,7 +173,7 @@ def record_return(tp)
       old_puts "return"
       return_value = to_value(tp.return_value)
       @record.register_step(tp.path, tp.lineno)
-      # return value support inspired by existing IDE-s/envs like 
+      # return value support inspired by existing IDE-s/envs like
       # Visual Studio/JetBrains IIRC
       # (Nikola Gamzakov showed me some examples)
       @record.register_variable("<return_value>", return_value)
@@ -192,18 +193,18 @@ def record_step(tp)
     def record_event(caller, content)
       # reason/effect are on different steps:
       # reason: before `p` is called;
-      # effect: now, when the args are evaluated 
+      # effect: now, when the args are evaluated
       # which can happen after many calls/steps;
       # maybe add a step for this call?
       begin
         location = caller[0].split[0].split(':')[0..1]
         path, line = location[0], location[1].to_i
         @record.register_step(path, line)
       rescue
-        # ignore for now: we'll just jump to last previous step 
+        # ignore for now: we'll just jump to last previous step
         # which might be from args
       end
-      # start is last step on this level: log for reason: the previous step on this level 
+      # start is last step on this level: log for reason: the previous step on this level
       @record.events << [:Event, RecordEvent.new(EVENT_KIND_WRITE, content, "")]
     end
 
@@ -231,7 +232,7 @@ def deactivate
   end
 
   private
-  
+
   def load_variables(binding)
     if !binding.nil?
       # $stdout.write binding.local_variables
@@ -243,19 +244,31 @@ def load_variables(binding)
     else
       []
     end
-  end  
+  end
 end
 
 
 $tracer = Tracer.new($codetracer_record)
 
 if __FILE__ == $PROGRAM_NAME
-  if ARGV[0].nil?
-    $stderr.puts('ruby trace.rb <program> [<args>]')
-    exit(1)
+  options = {}
+  parser = OptionParser.new do |opts|
+    opts.banner = "usage: ruby trace.rb [options] <program> [args]"
+    opts.on('-o DIR', '--out-dir DIR', 'Directory to write trace files') do |dir|
+      options[:out_dir] = dir
+    end
+    opts.on('-h', '--help', 'Print this help') do
+      puts opts
+      exit
+    end
   end
+  parser.order!
 
-  program = ARGV[0]
+  program = ARGV.shift
+  if program.nil?
+    $stderr.puts parser
+    exit 1
+  end
 
   $tracer.record.register_call('', 1, '<top-level>', [])
   $tracer.ignore('lib/ruby')
@@ -264,8 +277,6 @@ def load_variables(binding)
   $tracer.ignore('<internal:')
   $tracer.ignore('gems/')
 
-  trace_args = ARGV
-  ARGV = ARGV[1..-1]
   $tracer.activate
   begin
     Kernel.load(program)
@@ -278,9 +289,9 @@ def load_variables(binding)
     old_puts '====================='
     old_puts ''
   end
-  ARGV = trace_args
 
   $tracer.stop_tracing
 
-  $tracer.record.serialize(program)
+  out_dir = options[:out_dir] || ENV['CODETRACER_RUBY_RECORDER_OUT_DIR'] || Dir.pwd
+  $tracer.record.serialize(program, out_dir)
 end

test/benchmarks/run_benchmark.rb

@@ -14,13 +14,14 @@
   abort("Unknown benchmark '#{BENCHMARK}'")
 end
 
-PROGRAM = File.expand_path("programs/#{BENCHMARK}.rb", __dir__)
+PROGRAM = File.join('test', 'benchmarks', 'programs', "#{BENCHMARK}.rb")
 FIXTURE = File.expand_path("fixtures/#{BENCHMARK}_trace.json", __dir__)
 TMP_DIR = File.expand_path('tmp', __dir__)
-OUTPUT = File.join(TMP_DIR, "#{BENCHMARK}_trace.json")
+OUTPUT_DIR = File.join(TMP_DIR, BENCHMARK)
 EXPECTED_HASH = HASHES[BENCHMARK]
 
 FileUtils.mkdir_p(TMP_DIR)
+FileUtils.mkdir_p(OUTPUT_DIR)
 
 unless File.exist?(FIXTURE) && Digest::SHA256.file(FIXTURE).hexdigest == EXPECTED_HASH
   warn "Reference trace missing or corrupt. Attempting to fetch via git lfs..."
@@ -31,8 +32,7 @@
 raise 'reference trace hash mismatch' unless Digest::SHA256.file(FIXTURE).hexdigest == EXPECTED_HASH
 
 elapsed = Benchmark.realtime do
-  env = { 'CODETRACER_DB_TRACE_PATH' => OUTPUT }
-  system(env, 'ruby', File.expand_path('../../src/trace.rb', __dir__), PROGRAM)
+  system('ruby', File.expand_path('../../src/trace.rb', __dir__), '--out-dir', OUTPUT_DIR, PROGRAM)
   raise 'trace failed' unless $?.success?
 end
 puts "Benchmark runtime: #{(elapsed * 1000).round} ms"
@@ -43,7 +43,8 @@ def files_identical?(a, b)
   File.binread(a) == File.binread(b)
 end
 
-if files_identical?(FIXTURE, OUTPUT)
+OUTPUT_TRACE = File.join(OUTPUT_DIR, 'trace.json')
+if files_identical?(FIXTURE, OUTPUT_TRACE)
   puts 'Trace matches reference.'
 else
   warn 'Trace differs from reference!'

test/test_tracer.rb

@@ -14,12 +14,12 @@ def run_trace(program_name)
     base = File.basename(program_name, '.rb')
     Dir.chdir(File.expand_path('..', __dir__)) do
       program = File.join('test', 'programs', program_name)
-      output = File.join('test', 'tmp', "#{base}_trace.json")
-      env = { 'CODETRACER_DB_TRACE_PATH' => output }
-      system(env, 'ruby', 'src/trace.rb', program)
+      out_dir = File.join('test', 'tmp', base)
+      FileUtils.mkdir_p(out_dir)
+      system('ruby', 'src/trace.rb', '--out-dir', out_dir, program)
       raise "trace failed" unless $?.success?
+      JSON.parse(File.read(File.join(out_dir, 'trace.json')))
     end
-    JSON.parse(File.read(File.join(TMP_DIR, "#{base}_trace.json")))
   end
 
   def expected_trace(program_name)