ruby-prof 0.4.1-mswin32 → 0.5.0-mswin32

data/CHANGES

@@ -1,3 +1,33 @@
+0.5.0 (?)
+========================
+
+Features
+--------
+* Added support for 64 bit systems (patch from Diego 'Flameeyes' Petten�)
+* Added suport for outputting data in the format used by
+  KCacheGrind (patch from Carl Shimer)
+* Add filename and line numbers to call tree information (patch from Carl Shimer)
+* Added Visual Studio 2005 project file.
+
+Fixes
+-------
+* Fixes a bug when the type of an attached object (singleton) is inherited
+  from T_OBJECT as opposed to being a T_OBJECT (identified by Francis Cianfrocca)
+
+
+0.4.1 (2006-06-26)
+========================
+
+Features
+--------
+* Added a RubyProf.running? method to indicate whether a profile is in progress.
+* Added tgz and zip archives to release
+
+Fixes
+-------
+* Duplicate method names are now allowed
+* The documentation has been updated to show the correct API usage is RubyProf.stop not RubyProf.end
+
 
 0.4.0 (2006-06-16)
 ========================

data/README

@@ -7,6 +7,7 @@ ruby-prof is a fast code profiler for Ruby.  Its features include:
 * Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
 * Flat Profiles - similar to the reports generated by the standard Ruby profiler
 * Graph profiles - similar to GProf, these show how long a method runs, which methods call it and which methods it calls.
+* Call tree profiles - outputs results in the calltree format suitable for the KCacheGrind profiling tool.
 * Threads - supports profiling multiple threads simultaneously
 * Recursive calls - supports profiling recursive method calls
 * Reports - can generate both text and cross-referenced html reports
@@ -15,7 +16,7 @@ ruby-prof is a fast code profiler for Ruby.  Its features include:
 
 == Requirements
 
-ruby-prof requires Ruby 1.8.2 or higher.
+ruby-prof requires Ruby 1.8.4 or higher.
 
 If you are running Linux or Unix you'll need a C compiler so the extension
 can be compiled when it is installed.
@@ -93,7 +94,12 @@ This method is provided for backwards compatibility.  Using
 
 == Reports
 
-ruby-prof can generate flat profile and graph profile reports.
+ruby-prof can generate a number of different reports:
+
+* Flat Reports
+* Graph Reports
+* HTML Graph Reports
+* Call graphs
 
 Flat profiles show the overall time spent in each method.  They
 are a good of quickly identifying which methods take the most time.
@@ -104,17 +110,34 @@ Graph profiles also show the overall time spent in each method.
 In addition, they also show which methods call the current
 method and which methods its calls.  Thus they are good for
 understanding how methods gets called and provide insight into
-the flow of your program.  Graph profiles can be generated
-in text and html.  Since the html is cross-referenced it is
-easier to work with.  An example text graph profile
-is located at {examples/graph.txt}[link:files/examples/graph_txt.html] while
-an example html graph file is located at 
-{examples/graph.html}[link:files/examples/graph_html.html].
-
-Reports are created by printers.  The current printers include:
+the flow of your program.  An example text graph profile
+is located at {examples/graph.txt}[link:files/examples/graph_txt.html].
+
+HTML Graph profiles are the same as graph profiles, except
+output is generated in hyper-linked HTML. Since graph profiles
+can be quite large, the embedded links make it much easier to
+navigate the results.  An example html graph profile
+is located at {examples/graph.html}[link:files/examples/graph_html.html].
+
+HTML Graph profiles are the same as graph profiles, except
+output is generated in hyper-linked HTML. Since graph profiles
+can be quite large, the embedded links make it much easier to
+navigate the results.  An example html graph profile
+is located at {examples/graph.html}[link:files/examples/graph_html.html].
+
+Call graphs output results in the calltree profile format which is used
+by KCachegrind.  Call graph support was generously donated by Carl Shimer.
+More information about the format can be found at
+the {KCachegrind}[link:http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat] site.
+
+== Printers
+
+Reports are created by printers.  Supported printers include:
+
 * RubyProf::FlatPrinter - Creates a flat report in text format
 * RubyProf::GraphPrinter - Creates a call graph report in text format
 * RubyProf::GraphHtmlPrinter - Creates a call graph report in HTML (separate files per thread)
+* RubyProf::CallTreePrinter - Creates a call tree report compatible with KCachegrind.
 
 To use a printer:
 
@@ -124,14 +147,20 @@ To use a printer:
 
 The first parameter is any writable IO object such as STDOUT or a file.
 The second parameter, which has a default value of 0, specifies 
-the minimum percentage a method must take to be printed.  For more
+the minimum percentage a method must take to be printed.  Percentages
+should be specified as integers in the range 0 to 100.  For more
 information please see the documentation for the different printers.
 
 
-== Timing Data
+== Measurements
+
+Depending on the mode and platform, ruby-prof can measure various
+aspects of a Ruby program.  Supported measurements include:
 
-Depending on the mode and platform, ruby-prof can measure time in 
-three ways - process time, wall time and cpu time.
+* process time
+* wall time
+* cpu time
+* object allocations
 
 Process time measures the time used by a process between any two moments.
 It is unaffected by other processes concurrently running 
@@ -147,21 +176,29 @@ CPU time uses the CPU clock counter to measure time.  The returned
 values are dependent on the correctly setting the CPU's frequency.
 This mode is only supported on Pentium or PowerPC platforms.
 
-To set the clock_mode:
+Object allocations report which methods allocate objects in a running
+program.  This support was generously donated by Sylvain Joyeux. 
+This mode requires a patched Ruby interpreter.  For more
+information, see:
+http://rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700
+
+To set the measurement:
 
-	RubyProf.clock_mode = RubyProf::PROCESS_TIME
-	RubyProf.clock_mode = RubyProf::WALL_TIME
-	RubyProf.clock_mode = RubyProf::CPU_TIME
+* RubyProf.measure_mode = RubyProf::PROCESS_TIME
+* RubyProf.measure_mode = RubyProf::WALL_TIME
+* RubyProf.measure_mode = RubyProf::CPU_TIME
+* RubyProf.measure_mode = RubyProf::ALLOCATIONS
 
-This default value is PROCESS_TIME.
+The default value is RubyProf::PROCESS_TIME.
 
-You may also specify the clock_mode by using the RUBY_PROF_CLOCK_MODE
+You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
 environment variable:
 
-	export RUBY_PROF_CLOCK_MODE=process
-	export RUBY_PROF_CLOCK_MODE=wall
-	export RUBY_PROF_CLOCK_MODE=cpu
-	
+* export RUBY_PROF_MEASURE_MODE=process
+*	export RUBY_PROF_MEASURE_MODE=wall
+* export RUBY_PROF_MEASURE_MODE=cpu
+* export RUBY_PROF_MEASURE_MODE=allocations
+  
 Note that these values have changed since ruby-prof-0.3.0.	
 
 On Linux, process time is measured using the clock method provided 
@@ -212,7 +249,10 @@ high end its can around 80%.
 
 == Windows Binary
 
-The Windows binary is built with the latest version of MinGW.
+The Windows binary is built with the latest version of MinGW.  The source
+repository also includes a Microsoft VC++ 2005 solution.  If you wish to run
+a debug version of ruby-prof on Windows, then it is highly recommended
+you use VC++.
 
 
 == License

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/rdoctask'
 SO_NAME = "ruby_prof.so"
 
 # ------- Default Package ----------
-RUBY_PROF_VERSION = "0.4.1"
+RUBY_PROF_VERSION = "0.5.0"
 
 FILES = FileList[
   'Rakefile',
@@ -49,8 +49,8 @@ EOF
   spec.test_files = Dir["test/test_*.rb"]
   
 
-  spec.required_ruby_version = '>= 1.8.2'
-	spec.date = DateTime.now
+  spec.required_ruby_version = '>= 1.8.4'
+  spec.date = DateTime.now
   spec.rubyforge_project = 'ruby-prof'
   
   # rdoc
@@ -61,12 +61,12 @@ EOF
   # Make the readme file the start page for the generated html
   spec.rdoc_options << '--main' << 'README'
   spec.extra_rdoc_files = ['bin/ruby-prof',
+                           'ext/ruby_prof.c',
                            'examples/flat.txt',
-  											   'examples/graph.txt',
-  											   'examples/graph.html',
-    											 'ext/ruby_prof.c',
-    											 'README',
-    											 'LICENSE']
+                           'examples/graph.txt',
+                           'examples/graph.html',
+                           'README',
+                           'LICENSE']
 
 end
 
@@ -74,7 +74,7 @@ end
 # Rake task to build the default package
 Rake::GemPackageTask.new(default_spec) do |pkg|
   pkg.need_tar = true
-  pkg.need_tar = true
+  pkg.need_zip = true
 end
 
 
@@ -89,21 +89,23 @@ win_spec.files += ["lib/#{SO_NAME}"]
 
 desc "Create Windows Gem"
 task :create_win32_gem do
-  # Copy the win32 extension the top level directory
+  # Copy the win32 extension built by MingW - easier to install
+  # since there are no dependencies of msvcr80.dll
   current_dir = File.expand_path(File.dirname(__FILE__))
-  source = File.join(current_dir, "ext", "win32", SO_NAME)
+  source = File.join(current_dir, "mingw", SO_NAME)
   target = File.join(current_dir, "lib", SO_NAME)
   cp(source, target)
 
   # Create the gem, then move it to pkg
-	Gem::Builder.new(win_spec).build
-	gem_file = "#{win_spec.name}-#{win_spec.version}-#{win_spec.platform}.gem"
+  Gem::Builder.new(win_spec).build
+  gem_file = "#{win_spec.name}-#{win_spec.version}-#{win_spec.platform}.gem"
   mv(gem_file, "pkg/#{gem_file}")
 
-  # Remove win extension fro top level directory	
-	rm(target)
+  # Remove win extension from top level directory  
+  rm(target)
 end
 
+
 task :package => :create_win32_gem
 
 # ---------  RDoc Documentation ------
@@ -115,27 +117,26 @@ Rake::RDocTask.new("rdoc") do |rdoc|
   rdoc.options << "--inline-source" << "--line-numbers"
   # Make the readme file the start page for the generated html
   rdoc.options << '--main' << 'README'
-  rdoc.rdoc_files.include('bin/**/*',
-  											  'doc/*.rdoc',
-  											  'examples/flat.txt',
-  											  'examples/graph.txt',
-  											  'examples/graph.html',
-                          'lib/**/*.rb',
-    											'ext/**/ruby_prof.c',
-    											'README',
-    											'LICENSE')
-end
-
+  rdoc.rdoc_files.include('bin/**/*',
+                          'doc/*.rdoc',
+                          'examples/flat.txt',
+                          'examples/graph.txt',
+                          'examples/graph.html',
+                          'lib/**/*.rb',
+                          'ext/**/ruby_prof.c',
+                          'README',
+                          'LICENSE')
+end
 
 
 # ---------  Publish to RubyForge  ----------------
 desc "Publish ruby-prof to RubyForge."
 task :publish do 
-	require 'rake/contrib/sshpublisher'
-	
-	# Get ruby-prof path
-	ruby_prof_path = File.expand_path(File.dirname(__FILE__))
+  require 'rake/contrib/sshpublisher'
+  
+  # Get ruby-prof path
+  ruby_prof_path = File.expand_path(File.dirname(__FILE__))
 
-	publisher = Rake::SshDirPublisher.new("cfis@rubyforge.org",
-				"/var/www/gforge-projects/ruby-prof", ruby_prof_path)
+  publisher = Rake::SshDirPublisher.new("cfis@rubyforge.org",
+        "/var/www/gforge-projects/ruby-prof", ruby_prof_path)
 end

data/bin/ruby-prof

@@ -13,12 +13,16 @@
 #                                        flat - Prints a flat profile as text (default).
 #                                        graph - Prints a graph profile as text.
 #                                        graph_html - Prints a graph profile as html.
+#                                        call_tree - format for KCacheGrind
 #     -f, --file=path                  Output results to a file instead of standard out.
-#     -c, --clock-mode=clock_mode      Select a clock mode:
+#     -m, --measure-mode=measure_mode  Select a measurement mode:
 #                                        process - Use process time (default).
 #                                        wall - Use wall time.
 #                                        cpu - Use the CPU clock counter
 #                                              (only supported on Pentium and PowerPCs).
+#                                        allocations - Tracks object allocations
+#                                              (requires a patched Ruby interpreter).
+#         --replace-progname           Replace $0 when loading the .rb files.
 #     -h, --help                       Show help message
 #         --version                    Show version
 # 
@@ -26,85 +30,95 @@
 # See also: {flat profiles}[link:files/examples/flat_txt.html], {graph profiles}[link:files/examples/graph_txt.html], {html graph profiles}[link:files/examples/graph_html.html]
 #
 
-
 require 'ostruct'
 require 'optparse'
 require 'ruby-prof'
 
 options = OpenStruct.new
-options.clock_mode = RubyProf::PROCESS_TIME
+options.measure_mode = RubyProf::PROCESS_TIME
 options.printer = RubyProf::FlatPrinter
 options.min_percent = 0
 options.file = nil
+options.replace_prog_name = false
 
 opts = OptionParser.new do |opts|
-	opts.banner = "ruby_prof #{RubyProf::VERSION}\n" +
-	              "Usage: ruby_prof [options] <script.rb> [--extra-options-for-script]"
+  opts.banner = "ruby_prof #{RubyProf::VERSION}\n" +
+                "Usage: ruby_prof [options] <script.rb> [--extra-options-for-script]"
  
-	opts.separator ""
-	opts.separator "Options:"
-
-		
-	opts.on('-p printer', '--printer=printer', [:flat, :graph, :graph_html],
-					'Select a printer:',
-					'  flat - Prints a flat profile as text (default).',
-					'  graph - Prints a graph profile as text.',
-					'  graph_html - Prints a graph profile as html.') do |printer|
-					
-		case printer
-			when :flat
-				options.printer = RubyProf::FlatPrinter
-			when :graph
-				options.printer = RubyProf::GraphPrinter
-			when :graph_html
-				options.printer = RubyProf::GraphHtmlPrinter
-		end
-	end
-		
-	opts.on('-m min_percent', '--min_percent=min_percent', Float,
-					'The minimum percent a method must take before ',
-					'  being included in output reports') do |min_percent|
-		options.min_percent = min_percent
-	end
-
-	opts.on('-f path', '--file=path',
-				'Output results to a file instead of standard out.') do |file|
-		options.file = file
-	end
-		
-	opts.on('-c clock_mode', '--clock-mode=clock_mode',
-			[:process, :wall, :cpu],
-			'Select a clock mode:',
-			'  process - Use process time (default).',
-			'  wall - Use wall time.',
-			'  cpu - Use the CPU clock counter',
-			'        (only supported on Pentium and PowerPCs).') do |clock_mode|
-			
-			case
-			when :process
-				options.clock_mode = RubyProf::PROCESS_TIME			
-			when :wall
-				options.clock_mode = RubyProf::WALL_TIME			
-			when :cpu
-				options.clock_mode = RubyProf::CPU_TIME
-			end
-	end
-		
-	opts.on_tail("-h", "--help", "Show help message") do
-			puts opts
-			exit
-	end
-	opts.on_tail("-v", "--version", "Show version") do
-			puts "ruby_prof " + RubyProf::VERSION
-			exit
-	end
+  opts.separator ""
+  opts.separator "Options:"
+
+    
+  opts.on('-p printer', '--printer=printer', [:flat, :graph, :graph_html, :call_tree],
+          'Select a printer:',
+          '  flat - Prints a flat profile as text (default).',
+          '  graph - Prints a graph profile as text.',
+          '  graph_html - Prints a graph profile as html.',
+          '  call_tree - format for KCacheGrind' ) do |printer|
+
+          
+    case printer
+      when :flat
+        options.printer = RubyProf::FlatPrinter
+      when :graph
+        options.printer = RubyProf::GraphPrinter
+      when :graph_html
+        options.printer = RubyProf::GraphHtmlPrinter
+    end
+  end
+    
+  opts.on('-m min_percent', '--min_percent=min_percent', Float,
+          'The minimum percent a method must take before ',
+          '  being included in output reports.',
+                                        '  this option is not supported for call tree.') do |min_percent|
+    options.min_percent = min_percent
+  end
+
+  opts.on('-f path', '--file=path',
+        'Output results to a file instead of standard out.') do |file|
+    options.file = file
+  end
+    
+  opts.on('-m measure_mode', '--measure-mode=measure_mode',
+      [:process, :wall, :cpu, :allocations],
+      'Select what ruby-prof should measure:',
+      '  process - Process time (default).',
+      '  wall - Wall time.',
+      '  cpu - CPU time',
+      '        (only supported on Pentium and PowerPCs).',
+      '  allocations - O3bject allocations (required patched Ruby interpreter).') do |measure_mode|
+      
+      case measure_mode
+      when :process
+        options.measure_mode = RubyProf::PROCESS_TIME     
+      when :wall
+        options.measure_mode = RubyProf::WALL_TIME      
+      when :cpu
+        options.measure_mode = RubyProf::CPU_TIME
+      when :allocations
+        options.measure_mode = RubyProf::ALLOCATIONS
+      end
+  end
+        
+        opts.on("--replace-progname", "Replace $0 when loading the .rb files.") do
+                options.replace_prog_name = true
+        end
+    
+  opts.on_tail("-h", "--help", "Show help message") do
+      puts opts
+      exit
+  end
+  opts.on_tail("-v", "--version", "Show version") do
+      puts "ruby_prof " + RubyProf::VERSION
+      exit
+  end
 end
 
 begin
-	opts.parse! ARGV
+  opts.parse! ARGV
 rescue OptionParser::InvalidOption, OptionParser::InvalidArgument,
        OptionParser::MissingArgument => e
-	puts opts
+  puts opts
   puts
   puts e.message
   exit(-1)
@@ -112,9 +126,9 @@ end
 
 # Make sure the user specified at least one file
 if ARGV.length < 1
-	puts opts
-	puts ""
-	puts "Must specify a script to run"
+  puts opts
+  puts ""
+  puts "Must specify a script to run"
   exit(-1)
 end
 
@@ -125,27 +139,30 @@ end
 
 at_exit {
   # Stop profiling
-	result = RubyProf.stop
-
-	# Create a printer
-	printer = options.printer.new(result)
-
-	# Get output
-	if options.file
-		File.open(options.file, 'w') do |file|
-			printer.print(file, options.min_percent)
-		end
-	else
-		# Print out results	
-		printer.print(STDOUT, options.min_percent)
-	end
+  result = RubyProf.stop
+
+  # Create a printer
+  printer = options.printer.new(result)
+
+  # Get output
+  if options.file
+    File.open(options.file, 'w') do |file|
+      printer.print(file, options.min_percent)
+    end
+  else
+    # Print out results 
+    printer.print(STDOUT, options.min_percent)
+  end
 }
 
-# Now set clock mode
-RubyProf.clock_mode = options.clock_mode
+# Now set measure mode
+RubyProf.measure_mode = options.measure_mode
 
 # Get the script we will execute
 script = ARGV.shift
+if options.replace_prog_name
+        $0 = File.basename(File.expand_path(script))
+end
 
 # Start profiling
 RubyProf.start