Developer how to¶
Japanese version: https://bugs.ruby-lang.org/projects/ruby/wiki/DeveloperHowtoJa
Bug report¶
coding style¶
- indent
- 4 for C
- 2 for Ruby
- tab/space
- Do not use TABs in ruby codes ruby-dev:19388
- Also for C code, use only spaces (don't use TAB) [Bug #14246]
- Line breaks
- Style of declaration of function
- ANSI C style for 1.9+
- Standard
- C99
- But limited to features that can be built on our Travis/AppVeyor/RubyCI. See https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/C99 for details.
- See also: https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/Assumptions
- C99
- coding style for Ruby codes ruby-dev:19388
- Do not use TABs. 2 spaces.
- RDoc should be written at last.
- camelCase is deprecated for variable/method names.
- PascalStyle for class/module names.
- UNDERSCORE_SEPARATED_UPPER_CASE for other constants.
- naming rule ruby-list:12517
- 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 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¶
- Put your code into $(srcdir)/benchmark.
- 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¶
locked