Project

General

Profile

Developer how to

Japanese version: https://bugs.ruby-lang.org/projects/ruby/wiki/DeveloperHowtoJa

Bug report

coding style

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 expandtab
au FileType ruby setl nowrap tabstop=8 tw=0 sw=2 expandtab

Or, use mrkn/vim-cruby.

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 1.9+ is prerequisite in order to build Ruby from the repository.

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:

  • NDBM/QDBM
  • GDBM
  • OpenSSL
  • readline/editline(libedit)
  • zlib
  • libffi
  • libyaml
  • libexecinfo (FreeBSD)

Procuring machines

Linux on pa-risc
see ruby-dev:36732

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

UNIX compatible systems

$ git clone https://github.com/ruby/ruby /path/to/source/directory
$ cd /path/to/source/directory
$ autoconf
$ cd /path/to/build/directory
$ /path/to/source/directory/configure
$ make

If you are a Ruby committer, Please use the canonical repository instead of the GitHub repository.

$ git clone git@git.ruby-lang.org:ruby.git /path/to/source/directory

mswin systems (VC)

> git clone https://github.com/ruby/ruby drv:\path\to\source\directory
> cd drv:\path\to\build\directory
> drv:\path\to\source\directory\win32\configure
> nmake

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.
    • Its version may be different from one of Ruby being built.
    • Current Ruby requires BASERUBY to be 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 use -j for parallel test-all, see also test/lib/test/unit.rb
  • 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 TESTRUN_SCRIPT=path/to/script.rb.
runruby
executes $(srcdir)/test.rb by RUNRUBY. You 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 "git pull" and regenerates revision.h.
love
execute up, all, test, install and test-all.
dist
retrieves a snapshot from 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 with benchmark_driver.gem

For more details, see benchmark/README.md. https://github.com/ruby/ruby/blob/trunk/benchmark/README.md

Communication

  • You should subscribe mailing lists - ruby-core, ruby-cvs and ruby-dev(Japanese).
  • 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