ruby-prof 0.6.0-x86-mswin32-60

data/CHANGES

@@ -0,0 +1,116 @@
+0.6.0 (2007-02-03)
+========================
+
+ruby-prof 0.6.0 adds support for Ruby 1.9 and memory profiling.
+
+Features
+--------
+* Added support for ruby 1.9 (Shugo Maeda)
+* Added support for outputting printer results to a String, Array or IO
+  object (Michael Granger)
+* Add new memory profiling mode.  Note this mode depends on a
+  patched Ruby interpreter (Alexander Dymo)
+
+Fixes
+-------
+* Improvements to GraphHtmlPrinter including updated documentation,
+  fixes for min_time support, ability to specify templates using
+  strings or filenames, and table layout fixes (Makoto Kuwata)
+* Fixes to scaling factor for calltrees so that precision is not lost
+  due to the conversion to doubles (Sylvain Joyeux) 
+* Changed constant ALLOCATED_OBJECTS to ALLOCATIONS in the C code to
+  match the Ruby code (Sylvain Joyeux)
+* Added support for calltree printer to ruby-prof binary script (Sylvain Joyeux)
+* Fix support for the allocator measure mode to extconf.rb (Sylvain Joyeux)
+* Honor measure mode when specified on the command line (Sylvain Joyeux)
+* Sorting of methods by total time was incorrect (Dan Fitch, Charlie Savage)
+* Fix ruby-prof to work with the latest version of GEMS (Alexander Dymo)
+* Always define MEASURE_CPU_TIME and MEASURE_ALLOCATIONS in Ruby code, but
+  set their values to nil if the functionality is not available.
+   
+
+0.5.2 (2007-07-19)
+========================
+
+ruby-prof 0.5.2 is a bug fix release.
+
+Fixes
+-------
+* Include missing rails plugin
+
+
+0.5.1 (2007-07-18)
+========================
+
+ruby-prof 0.5.1 is a bug fix and performance release.
+
+Performance
+--------
+* Significantly reduced the number of thread lookups by
+  caching the last executed thread.
+
+Fixes
+-------
+* Properly escape method names in HTML reports
+* Fix use of -m and --min-percent command line switches
+* Default source file information to ruby_runtime#0 for c calls
+* Moved rails_plugin to top level so it is more obvious
+* Updated rails_plugin to write reports to the current
+  Rails log directory
+* Added additional tests
+
+
+0.5.0 (2007-07-09)
+========================
+
+Features
+--------
+* Added support for timing multi-threaded applications
+* 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.
+* Added replace-progname switch, als rcov.
+* Added better support for recursive methods
+* Added better support for profiling Rails applications
+
+Fixes
+-------
+* Fixes 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)
+* ruby-prof now works in IRB.
+* Fix sort order in reports.
+* Fixed rdoc compile error.
+* Fix tabs in erb template for graph html report on windows.
+
+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)
+========================
+Features
+--------
+* added support for call graphs
+* added support for printers.  Currently there is a FlatPrinter,
+  GraphPrinter and GraphHtmlPrinter.
+* added support for recursive methods
+* added Windows support
+* now packaged as a RubyGem
+
+Fixes
+-------
+* Fixes bug where RubyProf would crash depending on the
+  way it was invoked - for example, it did not run when
+  used with Arachno Ruby's customized version of Ruby.

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (C) 2005  Shugo Maeda <shugo@ruby-lang.org>
+All rights reserved.
+ *
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+ *
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README

@@ -0,0 +1,307 @@
+= ruby-prof
+
+== Overview
+
+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.
+* Modes - Ruby prof can measure a number of different parameters, including
+          call times, memory usage and object allocations. 
+* Reports - can generate text and cross-referenced html reports
+  - 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
+
+
+== Requirements
+
+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.
+
+If you are running Windows, then install the Windows specific RubyGem which
+includes an already built extension.
+
+
+== Install
+
+The easiest way to install ruby-prof is by using Ruby Gems.  To install:
+
+<tt>gem install ruby-prof</tt>
+
+If you are running Windows, make sure to install the Win32 RubyGem which 
+includes a pre-built binary.
+
+ruby-prof is also available as a tarred gzip archive and zip archive. 
+
+== Usage
+
+There are three ways of running ruby-prof.
+
+=== ruby-prof executable
+
+The first is to use ruby-prof to run the Ruby program
+you want to profile.  For more information refer to
+the ruby-prof documentation[link:files/bin/ruby-prof.html].
+
+=== ruby-prof API
+
+The second way is to use the ruby-prof API to profile
+particular segments of code.  
+
+  require 'ruby-prof'
+  
+  # Profile the code
+  RubyProf.start
+  ...
+  [code to profile]
+  ...
+  result = RubyProf.stop
+  
+  # Print a flat profile to text
+  printer = RubyProf::FlatPrinter.new(result)
+  printer.print(STDOUT, 0)
+  
+Alternatively, you can use a block to tell ruby-prof what
+to profile:
+
+  require 'ruby-prof'
+  
+  # Profile the code
+  result = RubyProf.profile do
+    ...
+    [code to profile]
+    ...
+  end
+  
+  # Print a graph profile to text
+  printer = RubyProf::GraphPrinter.new(result)
+  printer.print(STDOUT, 0)
+
+  
+=== require unprof
+
+The third way of using ruby-prof is by requiring unprof.rb:
+
+  require 'unprof'
+
+This will start profiling immediately and will output the results
+using a flat profile report.
+
+This method is provided for backwards compatibility.  Using
+{ruby-prof}[link:files/bin/ruby-prof.html] provides more flexibility.
+  
+
+== 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.
+An example of a flat profile and an explanation can be found in
+{examples/flat.txt}[link:files/examples/flat_txt.html].
+
+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.  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:
+
+  result = RubyProf.end
+  printer = RubyProf::GraphPrinter.new(result)
+  printer.print(STDOUT, 0)
+
+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.  Percentages
+should be specified as integers in the range 0 to 100.  For more
+information please see the documentation for the different printers.
+
+
+== Measurements
+
+Depending on the mode and platform, ruby-prof can measure various
+aspects of a Ruby program.  Supported measurements include:
+
+* process time
+* wall time
+* cpu time
+* object allocations
+* memory usage
+
+Process time measures the time used by a process between any two moments.
+It is unaffected by other processes concurrently running 
+on the system. Note that Windows does not support measuring process
+times - therefore, all measurements on Windows use wall time.
+
+Wall time measures the real-world time elapsed between any two moments.
+If there are other processes concurrently running on the system
+that use significant CPU or disk time during a profiling run
+then the reported results will be too large.
+
+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.
+
+Object allocation reports show how many objects each method in
+a program allocates.  This support was added by Sylvain Joyeux
+and requires a patched Ruby interpreter.  For more information, see:
+http://rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700
+
+Memory usage reports show how much memory each method in a program
+uses.  This support was added by Alexander Dymo and requires a
+patched Ruby interpreter.  For more information, see:
+http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062.
+
+
+To set the measurement:
+
+* RubyProf.measure_mode = RubyProf::PROCESS_TIME
+* RubyProf.measure_mode = RubyProf::WALL_TIME
+* RubyProf.measure_mode = RubyProf::CPU_TIME
+* RubyProf.measure_mode = RubyProf::ALLOCATIONS
+* RubyProf.measure_mode = RubyProf::MEMORY
+
+The default value is RubyProf::PROCESS_TIME.
+
+You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
+environment variable:
+
+* 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 
+by the C runtime library. Note that the clock method does not
+report time spent in the kernel or child processes and therefore
+does not measure time spent in methods such as Kernel.sleep method.
+If you need to measure these values, then use wall time.  Wall time
+is measured using the gettimeofday kernel method.
+
+On Windows, timings are always wall times.  If you set the clock 
+mode to PROCESS_TIME, then timing are read using the clock method
+provided by the C runtime library.  Note though, these values are
+wall times on Windows and not process times like on Linux.
+Wall time is measured using the GetLocalTime API.
+
+If you use wall time, the results will be affected by other
+processes running on your computer, network delays, disk access,
+etc.  As result, for the best results, try to make sure your
+computer is only performing your profiling run and is 
+otherwise quiescent.
+
+On both platforms, cpu time is measured using the RDTSC assembly
+function provided by the Pentium and PowerPC platforms. CPU time
+is dependent on the cpu's frequency.  On Linux, ruby-prof attempts 
+to read this value from "/proc/cpuinfo."  On Windows, you must
+specify the clock frequency.  This can be done using the
+RUBY_PROF_CPU_FREQUENCY environment variable:
+
+  export RUBY_PROF_CPU_FREQUENCY=<value>
+  
+You can also directly set the cpu frequency by calling:
+
+  RubyProf.cpu_frequency = <value> 
+
+
+== Recursive Calls
+
+Recursive calls occur when method A calls method A and cycles
+occur when method A calls method B calls method C calls method A.
+ruby-prof detects both direct recursive calls and cycles.  Both
+are indicated in reports by a dash and number following a method
+name.  For example, here is a flat profile from the test method
+RecursiveTest#test_recursive:
+
+
+%self     total     self     wait    child    calls  name
+100.00      2.00     2.00     0.00     0.00        2  Kernel#sleep
+  0.00      2.00     0.00     0.00     2.00        0  RecursiveTest#test_cycle
+  0.00      0.00     0.00     0.00     0.00        2  Fixnum#==
+  0.00      0.00     0.00     0.00     0.00        2  Fixnum#-
+  0.00      1.00     0.00     0.00     1.00        1  Object#sub_cycle-1
+  0.00      2.00     0.00     0.00     2.00        1  Object#sub_cycle
+  0.00      2.00     0.00     0.00     2.00        1  Object#cycle
+  0.00      1.00     0.00     0.00     1.00        1  Object#cycle-1
+
+Notice the presence of Object#cycle and Object#cycle-1.  The -1 means
+the method was either recursively called (directly or indirectly).
+
+However, the self time values for recursive calls should always 
+be accurate.  It is also believed that the total times are
+accurate, but these should be carefully analyzed to verify their veracity.
+
+== Multi-threaded Applications
+
+Unfortunately, Ruby does not provide an internal api
+for detecting thread context switches.  As a result, the
+timings ruby-prof reports for each thread may be slightly
+inaccurate.  In particular, this will happen for newly 
+spanned threads that immediately go to sleep.  For instance,
+if you use Ruby's timeout library to wait for 2 seconds,
+the 2 seconds will be assigned to the foreground thread
+and not the newly created background thread.  These errors
+can largely be avoided if the background thread performs an
+operation before going to sleeep. 
+
+
+== Performance
+
+Significant effort has been put into reducing ruby-prof's overhead
+as much as possible.  Our tests show that the overhead associated
+with profiling code varies considerably with the code being
+profiled.  Most programs will run approximately twice as slow
+while highly recursive programs (like the fibonacci series test)
+will run three times slower.
+
+== Windows Binary
+
+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
+
+See LICENSE for license information.

data/Rakefile

@@ -0,0 +1,141 @@
+require 'rubygems'
+require 'date'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'date'
+
+SO_NAME = "ruby_prof.so"
+
+# ------- Default Package ----------
+RUBY_PROF_VERSION = "0.6.0"
+
+FILES = FileList[
+  'Rakefile',
+  'README',
+  'LICENSE',
+  'CHANGES',
+  'bin/*',
+  'lib/**/*',
+  'rails_plugin/**/*',
+  'examples/*',
+  'ext/*',
+  'doc/**/*',
+  'test/*'
+]
+
+# Default GEM Specification
+default_spec = Gem::Specification.new do |spec|
+  spec.name = "ruby-prof"
+  
+  spec.homepage = "http://rubyforge.org/projects/ruby-prof/"
+  spec.summary = "Fast Ruby profiler"
+  spec.description = <<-EOF
+ruby-prof is a fast code profiler for Ruby. It is a C extension and
+therefore is many times faster than the standard Ruby profiler. It
+supports both flat and graph profiles.  For each method, graph profiles
+show how long the method ran, which methods called it and which 
+methods it called. RubyProf generate both text and html and can output
+it to standard out or to a file.
+EOF
+
+  spec.version = RUBY_PROF_VERSION
+
+  spec.author = "Shugo Maeda and Charlie Savage"
+  spec.email = "shugo@ruby-lang.org and cfis@savagexi.com"
+  spec.platform = Gem::Platform::RUBY
+  spec.require_path = "lib" 
+  spec.bindir = "bin"
+  spec.executables = ["ruby-prof"]
+  spec.extensions = ["ext/extconf.rb"]
+  spec.files = FILES.to_a
+  spec.test_files = Dir["test/test_*.rb"]
+  
+
+  spec.required_ruby_version = '>= 1.8.4'
+  spec.date = DateTime.now
+  spec.rubyforge_project = 'ruby-prof'
+  
+  # rdoc
+  spec.has_rdoc = true
+  spec.rdoc_options << "--title" << "ruby-prof"
+  # Show source inline with line numbers
+  spec.rdoc_options << "--inline-source" << "--line-numbers"
+  # 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',
+                           'README',
+                           'LICENSE']
+
+end
+
+# Rake task to build the default package
+Rake::GemPackageTask.new(default_spec) do |pkg|
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
+
+# ------- Windows Package ----------
+# Windows specification
+win_spec = default_spec.clone
+win_spec.extensions = []
+win_spec.platform = Gem::Platform::CURRENT
+win_spec.files += ["lib/#{SO_NAME}"]
+
+desc "Create Windows Gem"
+task :create_win32_gem do
+  # 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, "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"
+  mv(gem_file, "pkg/#{gem_file}")
+
+  # Remove win extension from top level directory  
+  rm(target)
+end
+
+
+task :package => :create_win32_gem
+
+# ---------  RDoc Documentation ------
+desc "Generate rdoc documentation"
+Rake::RDocTask.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "ruby-prof"
+  # Show source inline with line numbers
+  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
+
+
+# ---------  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__))
+
+  publisher = Rake::SshDirPublisher.new("cfis@rubyforge.org",
+        "/var/www/gforge-projects/ruby-prof", ruby_prof_path)
+end