feat: add out dir option

Author: zah

README.md

@@ -11,16 +11,19 @@ A recorder of Ruby programs that produces [CodeTracer](https://github.com/metacr
 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.
@@ -34,7 +37,8 @@ The same environment is configured for GitHub Codespaces via devcontainer config
 ### 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
+(used internally by codetracer as well; defaults to the current directory)
 
 ## future directions
 

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

@@ -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
@@ -263,11 +263,14 @@ def serialize(program)
     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)

src/trace.rb

@@ -3,14 +3,27 @@
 # See LICENSE file in the project root for full license information.
 
 require 'json'
+require 'optparse'
 require_relative 'recorder'
 
-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
 
 # Warning:
 # probably related to our development env:
@@ -265,8 +278,7 @@ def load_variables(binding)
 $tracer.ignore('gems/')
 
 
-trace_args = ARGV
-ARGV = ARGV[1..-1]
+trace_args = [program] + ARGV
 $tracer.activate
 begin
   Kernel.load(program)
@@ -289,4 +301,5 @@ def load_variables(binding)
 
 $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)

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)