Developer how to

Bug report

coding style

  • indent
    • 4 for C
    • 2 for Ruby
  • tab/space
    • Do not use TABs in ruby codes []
    • Use TAB instead of 8 SPs in C. (Emacs's default style)
  • Line breaks
  • Style of declaration of function
    • K&R style for 1.8, ANSI C style for 1.9
  • Standard
    • C90 (not C99)
  • coding style for Ruby codes []
    • Do not use TABs. 2 spaces.
    • RDoc should be written at last.
    • camelCase is deprecated for variable/method names.
    • PascalStyle for class/module names.
    • UNDERSCORESEPARATEDUPPER_CASE for other constants.
  • naming rule []
    • Capitalize words.
    • ABBRs should be all upper case.
  • Do as others do

For Emacs

Use misc/ruby-style.el and misc/ruby-mode.el

For Vim

Add following to .vimrc

au FileType c setl ts=8 sw=4 noexpandtab
au FileType ruby setl nowrap tabstop=8 tw=0 sw=2 expandtab
let $TZ='japan'
let g:changelogdateformat = "%c"
let g:changelog
timeformat = "%c"
let g:changelog_username = "FOO, Bar foobar@ruby-lang.org"

how to build

prerequisite

  • C compiler
  • autoconf (2.60 or later, without VC++ environment)
  • bison (2.2 or later)
  • (gperf - for generating lex.c)
  • ruby - Ruby itself is prerequisite in order to build Ruby 1.9. It can be 1.8.

Note that on cross compiling BASERUBY should be the same version of the building ruby.Even if BASERUBY is the same version but can't build because of platform dependency, it is a bug and please report it.

If you use debian, you can do this to install all necessary dependencies:

aptitude build-dep ruby1.9.1

Otherwise you should also install:

  • Tcl/Tk
  • NDBM/QDBM
  • GDBM
  • Ncurses (or something)
  • OpenSSL
  • readline/editline(libedit)
  • zlib
  • libffi
  • libyaml
  • libexecinfo (FreeBSD)

Procuring machines

Linux on pa-risc
see []

  • Ask Debian Project whether we can borrow a machine to run and test ruby as above.

UNIX compatible systems

$ cd /path/to/source/directory
$ svn co http://svn.ruby-lang.org/repos/ruby/trunk .
$ autoconf
$ cd /path/to/build/directory
$ /path/to/source/directory/configure
$ make

mswin systems (VC)

> cd drv:\path\to\source\directory

svn co http://svn.ruby-lang.org/repos/ruby/trunk .
cd drv:\path\to\build\directory
drv:\path\to\source\directory\win32\configure
nmake

mingw system (GCC)

> cd drv:\path\to\source\directory

svn co http://svn.ruby-lang.org/repos/ruby/trunk .
cd drv:\path\to\build\directory
autoconf
bash -c './configure'
make && make install

build directory

Of course you can specify paths in relative form.

Make targets

TERMINOLOGY: various ruby interpreters

Some different versions of ruby processor are used in build process.

BASERUBY
Uses ruby command which is installed in your system. It's version may be different from one of Ruby being built.

  • e.g.: BASERUBY is 1.8.7, on building Ruby 1.9. MINIRUBY * Uses miniruby
    • miniruby will be built in build process.
    • You can pass arguments to miniruby via variable MINIRUBYOPT. % make loadpath ./miniruby -I../../lib -I.ext/common -I./- -r../../ext/purelib.rb -e 'p $:' ["/Users/yugui/src/ruby/mri/lib", "/Users/yugui/src/ruby/mri/tmp/array/.ext/common", "."] % make loadpath MINIRUBYOPT=-v ./miniruby -I../../lib -I.ext/common -I./- -r../../ext/purelib.rb -v -e 'p $:' ruby 1.9.0 (2008-10-09 revision 0) [i386-darwin9.5.0] ["/Users/yugui/src/ruby/mri/lib", "/Users/yugui/src/ruby/mri/tmp/array/.ext/common", "."] RUNRUBY * Uses the ruby just built. Mainly we uses it for tests or benchmarks.
  • It will be spawned by $(srcdir)/runruby.rb.
    • You can pass arguments to runruby.rb via variable RUNRUBYOPT. % make test-all RUNRUBYOPT=--debugger This executes test-all using Ruby under gdb's control.

Build

Building interpreters

all
(default) builds ruby
golf
builds goruby
miniruby
builds miniruby, which is the minimal interpreter, does not contain extension libraries/encoding classes.

Components

prereq
executes srcs, incs, and preludes.
srcs
generates some C source codes from definition files.
preludes
generates C source codes from *prelude.rb.
incs
generates some C source fragments and headers, which are in short something #included.Mainly it means YARV and transcode.

incs-enc
generates translators from codepoint mapping tables.
encs
builds encoding classes.
exts
builds extension libraries.

Documents

rdoc
processing rdocs and generates documents

Installation

install
installs the ruby you built.
install-nodoc
ditto, but not documents.
install-ext
installs only extension libraries.
install-lib
installs only libraries.
install-doc
installs only documents.
install-man
installs only manual pages.

Clean

clean
deletes some outputs, mainly object files. Generated source codes still remain.

clean-local
cleans only ruby and miniruby.
clean-ext
cleans only extension libraries.
clean-enc
cleans only encoding classes and transcode related matters.
clean-golf
cleans only goruby related matters.
distclean
In addition to clean, deletes outputs of the configure script, automatically generated source codes which depend on the configure script, and Makefile.

distclean-local
distclean-ext
distclean-enc
distclean-golf
realclean
In addition to distclean, deletes all of automatically generated source codes.

realclean-local
realclean-ext
realclean-enc
realclean-golf

Test

test
executes test scripts.

btest-ruby
see bellow.
test-sample
executes and checks sample/*.rb with MINIRUBY
test-knownbug
executes KNOWNBUGS.rb with MINIRUBY
test-all
tests more with RUNRUBY.

  • all tests should work without make install'ing before.
    • But some tests might need make install in practice.
  • You can pass arguments to test/runner.rb via variable TESTS. e.g. You can get detail of test progress as % make test-all TESTS=-v And you can test a test case you want as % make test-all TESTS=test_foo check executes both of test and test-all. btest executes the lightweight tests by MINIRUBY. This is useful when the unittest library does not work correctly.

You can pas arguments to bootstraptest/runner.rb via variable OPTS.
btest-ruby
executes btest by ruby.

Analysys, trial and error.

run
executes $(srcdir)/test.rb by MINIRUBY.You can specify another script as TESTRUNSCRIPT=path/to/script.rb.
runruby
executes $(srcdir)/test.rb by RUNRUBYYou can specify another script as TESTRUN
SCRIPT=path/to/script.rb.
gdb
executes $(srcdir)/test.rb by miniruby under gdb.You can specify another script as TESTRUN_SCRIPT=path/to/script.rb.

You can define breakpoints in $(srcdir)/breakpoints.gdb.
gdb-ruby
executes $(srcdir)/test.rb by ruby under gdb.You can specify another script as TESTRUN_SCRIPT=path/to/script.rb.

You can define breakpoints in $(srcdir)/breakpoints.gdb.
parse
parses $(srcdir)/test.rb by miniruby, and dumps disassembled YARV opcodes.You can specify another script as TESTRUN_SCRIPT=path/to/script.rb.
benchmark
executes benchmarks. YOu can pass arguments to benchmark/driver.rb via variable OPTS.

RubySpec

update-rubyspec
updates specs which RubySpecs team wrote.
test-rubyspec
verifies if the interpreter conforms specs.

Misc.

up
updates your working copy. This does "svn up" (or "git pull") and regenerates revision.h.
love
execute up, all, test, install and test-all.
dist
retrieves a snapshot from optimizare seo the repository and generates tarballs.
help
prints a summary of make targets

How to write a benchmark

  1. Put your code into $(srcdir)/benchmark.
  2. Run it by ruby benchmark/driver.rb [OPTIONS].

For more detail, see ruby benchmark/driver.rb --help.

vm1, vm2

Benchmark driver iterates your script

  • 300000 times for bmvm1*.rb.
  • 600000 times for bmvm2*.rb.

Communication

  • You should subscribe mailing lists - ruby-core, ruby-cvs and ruby-dev(Japanese).
  • We often talks on irc.
    • #ruby-core @ freenode (English)
    • #ruby:*.jp @ IRCnet (Japanese) - For joining, you need to connect *.jp server of IRCnet.
    • #ruby-ja @ IRCnet (Japanese) - This channel link building service doesn't need to connect .jp server. Recently this channel is used often than #ruby:.jp . This channel's log is able to publish.
  • Sometimes we takes offline meetings in Japan.

Resources

Ruby Hacking Guide (Japanese)
explanation which is based on Ruby 1.7. Little old but useful.English version
RHG strikes back (in Japanese)
Reading the implementation of Ruby 1.9.

See also