@@ -1,6 +1,6 @@ -= Actors - Concurrent Rubinius +# Actors - Concurrent Rubinius -== Background +## Background Rubinius is shaping up to be quite a nice platform for networking and distributed computing. The virtual machine uses @@ -11,7 +11,7 @@ the Channel class, an elegant mechanism that comes from the [π-calculus](http://en.wikipedia.org/wiki/Pi-calculus) that serves a number of roles in Rubinius. -== Channel +## Channel First, you can treat a Channel like a thread safe queue that lets you push an item onto the tail from any thread, and then receive the item at the head from @@ -70,7 +70,7 @@ resources between threads it's not so tricky, but for more complex occasions threads can get really tough. Beyond that, if you try to uses multiple threaded libraries you can run into extremely difficult to debug problems. -== Actors +## Actors One answer to this problem is the [actor model](http://en.wikipedia.org/wiki/Actor_model). In this model an actor is a @@ -82,7 +82,7 @@ simplifies the concurrency problems that can arise. Additionally, it makes it easy to run actors in parallel on multi-core machines, or across a network on multiple boxes. -=== Current Status +### Current Status Rubinius has initial support for local actors now, and we are working on building them up to be the foundation for a full fledged distributed computing @@ -90,7 +90,7 @@ framework. This is an outline of the currently envisioned design: ![actors.png](images/actors.png) -== Glossary +## Glossary *Actor* doc/actors.txt @@ -1,12 +1,12 @@ -= Coding Style Guide +# Coding Style Guide -== All Code +## All Code * Configure your editor for soft tabs, not hard tabs * Expand tabs to two spaces * Leave a trailing newline at the end of each file -== C++ Code +## C++ Code * No space between condition and paren. if(1) @@ -23,7 +23,7 @@ *NOT* `person1(char *name)`. -== Ruby Code +## Ruby Code * See `kernel/core/array.rb` for a style reference. * Methods: Try to keep your methods short--one screenful and try to adhere @@ -53,7 +53,7 @@ do_something_with elem end -== Documentation +## Documentation * Use RDoc for documentation in Ruby code. * Use DOxygen for documentation in C++ code. doc/coding_style_guide.txt @@ -1,11 +1,11 @@ -= Common Build Problems and Solutions +# Common Build Problems and Solutions TODO: Imported from Lighthouse wiki. Likely outdated These are typical error messages / scenarios that you may encounter at various stages of building Rubinius, along with the typical causes and solutions. -== Before anything else +## Before anything else *Make certain that you do not have an old version of Rubinius installed somewhere.* Executing new code using the old libraries will end in tears. The @@ -17,13 +17,13 @@ Old .rbc files may be getting in the way. 'rake clean build' should eliminate these problems. -== C Compilation Errors +## C Compilation Errors -=== "undefined reference to '[some symbol]" +### "undefined reference to '[some symbol]" Try `rake distclean build` to make sure the entire C codebase is rebuilt. -=== "error: IN_DONT_FOLLOW not declared" +### "error: IN_DONT_FOLLOW not declared" On Linux at least, the inotify library may be used but for some reason, some distributions' sys/inotify.h does not have the necessary constants. You can @@ -31,12 +31,12 @@ either disable it in the configuration or try to use updated header files at least from [here](http://inotify.aiken.cz/?section=inotify&page=download&lang=en). -=== "Unable to compile [extension].so/dylib/etc." +### "Unable to compile [extension].so/dylib/etc." First, even if an extension fails to build, you should still be OK. Try `shotgun/rubinius -v` to verify that Rubinius itself works. -=== "glibtool: link: cannot build libtool library `librubinius.la' from +### "glibtool: link: cannot build libtool library `librubinius.la' from non-libtool objects: ..." (Mac OS X) Make sure your `glibtool` is at least version 1.5. You may also have multiple @@ -44,26 +44,26 @@ versions installed, use `` `which glibtool` `` to locate the one that is currently being picked up. Typically this problem occurs if you have an outdated version in `/sw/bin/glibtool` and a newer one in `/usr/bin/glibtool`. -=== "MACOSX_DEPLOYMENT_TARGET ..." +### "MACOSX_DEPLOYMENT_TARGET ..." The error message is probably complaining that it is supposedly set to 10.1 or something; you can override this by giving the env explicitly on the command line. The Rubinius code seems to be correct though so it is likely you have that invalid #define in your system headers somewhere. -== Ruby Build Errors +## Ruby Build Errors -=== "... in `initialize': uninitialized constant Mutex::Channel" +### "... in `initialize': uninitialized constant Mutex::Channel" Unset `$RUBYOPT` (usually set for Gems.) -=== "Unable to find [ClassName]" +### "Unable to find [ClassName]" These are caused by some load order dependency not being properly constructed. Determine which file needs which other file and insert a "depends on [file].rb", then `rake build : load_order`. -=== "Unable to find 'kernel/bootstrap/archive.rbc'" -- "Unable to run +### "Unable to find 'kernel/bootstrap/archive.rbc'" -- "Unable to run runtime/stable/bootstrap.rba" Either: doc/common_problems.txt @@ -1,3 +1,5 @@ += Contributing to Rubinius + There are as many ways to help with Rubinius as there are people. The following are just some ideas. Understand that Rubinius is a large, fast-moving project, so you will likely need to coordinate your efforts with @@ -16,34 +18,30 @@ that the next doc writer can be annoying with other questions. ## Write Specs -# Find unspecified behaviors. Be vicious ! Once you found a nice corner-case, write a spec. See "Howto - Write a spec":/projects/5089/howto-write-a-spec -# Fix the specs by running them against MatzRuby. Use <code>rake spec:check</code> OR @bin/mspec -t ruby spec/ruby@ to run all the specs that should pass on MatzRuby -# ... +1. Find unspecified behaviors. Be vicious! Once you found a nice + corner-case, write a spec. See 0Howto - Write a + spec](/howto/write_a_spec.html) +1. Fix the specs by running them against MatzRuby. Use `rake + spec:check` OR `bin/mspec -t ruby spec/ruby` to run all the specs that + should pass on MatzRuby ## Run your code -You code it often more vicious than the specs. Run your pet project under rubinius and report crashes ! See "Howto - Write a ticket":/projects/5089/howto-write-a-ticket. +You code it often more vicious than the specs. Run your pet project under +rubinius and report crashes! See [Howto - Write a +ticket](/howto/write_a_ticket.html) ## Cleanup code -Search for tags like TODO, HACK, FIXME in the code and fix them. Once you're finished, submit a ticket with the [PATCH] tag and a small description. See "Howto - Write a ticket":/projects/5089/howto-write-a-ticket. +Search for tags like TODO, HACK, FIXME in the code and fix them. Once you're +finished, submit a ticket with the [PATCH] tag and a small description. See +[Howto - Write a ticket](/howto/write_a_ticket.html) I use : `grep -re "TODO\|HACK\|FIXME" .` -You can also run failing specs and try to fix them. I use `bin/ci -i` and `rake todo` - -h5. What can I do to help? -# Run the specs and help write code in kernel/ to make the specs pass. -# If you're up on your C skills, ask in the IRC channel about helping work on the VM. -# Tell your friends about the project, get the buzz going. -# Provide moral support for other developers in any form. - -h5. I want to get involved! What is a good place to start? -# A fun way to get in is to pick an application or library that you have written--or one that you frequently use--and try to run it. If it works, great! If, as is still quite possible if not even likely, it does not work, you have a good spot to start from. Try to isolate the source of -the failure and write a spec for it. -# The other popular way is to just either run the specs and see what still fails, or to identify and add missing specs. +You can also run failing specs and try to fix them. I use `bin/ci -i` and +`rake todo` -Either way, once you have a spec to work on, you can see if you can identify where the implementation is wrong and possibly fix it! If it turns out the problem is too tricky for you to solve, you should just move onto a different issue and maybe return to the original later (ed. note: Trust me, it still happens to us all continuously. If you do not know X, someone else will and if someone else does not know Y, you might. Teamwork and communication are paramount! --rue.) ## Ask For Help @@ -52,13 +50,32 @@ too, if possible. We will certainly accept and appreciate simple bug reports, but it is extremely helpful if you can actively help us identify (and maybe even fix) the problem. -h5. It is all so confusing! There is the VM, the kernel, the libraries, the specs, polymorphic caches, pneumatic stegosauruses.. how can I possibly understand all of this? -* You do not need to know or understand everything immediately. You should just have a great time exploring the codebase, not feel like it is some kind of an exam cram. In fact, it is highly recommended that you start off focusing on a narrow area and work your way to how it fits in the big picture. While Rubinius is actually an exceptionally straightforward and elegant VM and language implementation (MatzRuby 1.9, for example, is two orders of magnitude larger), there is still a lot of information to discover and absorb. Ask questions! - -h5. I don't like the style of the specs or the kernel or the vm, can I clean it up and you'll accept the patch? -# No. -# The implementation is pretty straightforward and idiomatic Ruby (or C++.) However, out of necessity many parts of the kernel are implemented using simple constructs and could perhaps be expressed more succintly. There is almost always a good reason for this, ranging from compiler support to maybe not having a certain method or class available yet. If it really bothers you, ask us first, we'll discuss it. - -h5. Will you reject my patch if my style is "more Rubyesque"? -* If the patch works (e.g. does not use features that cannot be guaranteed to exist in all cases), it will not be rejected based on a stylistic qualm. The code is most welcome. But "clever" or obscure code is not. +Q. It is all so confusing! There is the VM, the kernel, the libraries, the + specs, polymorphic caches, pneumatic stegosauruses... How can I possibly + understand all of this? + +A. You do not need to know or understand everything immediately. You should + just have a great time exploring the codebase, not feel like it is some + kind of an exam cram. In fact, it is highly recommended that you start off + focusing on a narrow area and work your way to how it fits in the big + picture. While Rubinius is actually an exceptionally straightforward and + elegant VM and language implementation (MatzRuby 1.9, for example, is two + orders of magnitude larger), there is still a lot of information to + discover and absorb. Ask questions! + +Q. I don't like the style of the specs or the kernel or the vm, can I clean + it up and you'll accept the patch? + +A. That depends. The implementation is pretty straightforward and idiomatic + Ruby (or C++.) However, out of necessity many parts of the kernel are + implemented using simple constructs and could perhaps be expressed more + succintly. There is almost always a good reason for this, ranging from + compiler support to maybe not having a certain method or class available + yet. If it really bothers you, ask us first, we'll discuss it. + +Q. Will you reject my patch if my style is "more Rubyesque"? + +A. If the patch works (e.g. does not use features that cannot be guaranteed + to exist in all cases), it will not be rejected based on a stylistic + qualm. The code is most welcome. But "clever" or obscure code is not. doc/contributing.txt @@ -1,4 +1,4 @@ -= Foreign Function Interface - FFI +# Foreign Function Interface - FFI TODO: Imported from Lighthouse wiki. Likely outdated @@ -6,17 +6,17 @@ TODO: Imported from Lighthouse wiki. Likely outdated This section is highly underdeveloped. -=== Overview +## Overview To do. -=== Usage +## Usage The main interface function to FFI is `Module#attach_foreign.` Extracted documentation on its usage is below: -==== Module#attach_foreign +### Module#attach_foreign Create a wrapper to a function in a C-linked library that exists somewhere in the system. If a specific library is not given, the function is assumed to doc/foreign_function_interface.txt @@ -1,4 +1,4 @@ -= Howto - Add a Builtin Class to the VM +# Howto - Add a Builtin Class to the VM TODO: Imported from Lighthouse wiki. Needs review and update. doc/howto/add_a_builtin_class.txt @@ -1,4 +1,4 @@ -= Howto - Fix a Failing Spec +# Howto - Fix a Failing Spec Make sure you have read: doc/howto/fix_a_failing_spec.txt @@ -1,15 +1,15 @@ -= Howto - Run Rails +# Howto - Run Rails NOTE: Rails runs on the old VM (shotgun). We are still getting it running on the new C++ VM. -== Installing the Rails gems +## Installing the Rails gems Rubinius has gem installed as a sub-command, so: rbx gem install rails -== Testing your Rails app +## Testing your Rails app After that, you can use any gem-installed executable as a rubinius sub-command. For example, to run your rails app's tests: doc/howto/run_rails.txt @@ -1,4 +1,4 @@ -= Howto - Write a Rubinius Spec +# Howto - Write a Rubinius Spec Make sure you have read: doc/howto/write_a_rubinius_spec.txt @@ -1,4 +1,4 @@ -= Howto - Write a Ruby Spec +# Howto - Write a Ruby Spec Make sure you have read: doc/howto/write_a_ruby_spec.txt @@ -1,13 +1,13 @@ -= Howto - Write a Ticket +# Howto - Write a Ticket TODO: Imported from Lighthouse wiki. Needs review. Please follow the guidelines below when submitting a ticket for a problem with Rubinius: -== General procedure for submitting a ticket +## General procedure for submitting a ticket -=== 0. Double-check +### 0. Double-check 1. Do a full rebuild after a `git pull` or fresh checkout. 1. Read [the common problems @@ -16,7 +16,7 @@ Rubinius: 1. Read [Howto - Develop with a separate RubySpec repo](/projects/5089/howto-develop-with-a-separate-rubyspec-repo) -=== 1. Title your ticket appropriately. Use a specific, preferrably short +### 1. Title your ticket appropriately. Use a specific, preferrably short title and prefix it with: * "[TODO]" - for reporting missing parts of Rubinius. For example, a missing @@ -27,13 +27,13 @@ title and prefix it with: attached a solution (and specs if missing) * "[FEATURE]" - for features that you are suggesting be added to Rubinius -=== 2. Use tags +### 2. Use tags Mark the ticket with some tags (the current ones are below the field for reference.) Most importantly, enter any [BUG] tickets with a @bug@ tag also and so on. -=== 3. Give enough detail about the issue +### 3. Give enough detail about the issue * A way to reproduce the issue whether it is a formal spec, a code snippet, a program or library etc. @@ -47,7 +47,7 @@ proposal and the rationale for it. Actual specs and patches to fix the problem are most welcome! -=== Additional instructions for [PATCH] tickets +### Additional instructions for [PATCH] tickets * Can be just a set of specs. * Patches must be accompanied by specs unless the specs already exist. @@ -63,7 +63,7 @@ Unless for some reason impossible, please use `git-format-patch` to create the patchset. It is much easier to apply and it preserves the correct attribution. Otherwise, a unified diff. -== Example of submitting a [PATCH] ticket +## Example of submitting a [PATCH] ticket Suppose the following spec exists and is failing: doc/howto/write_a_ticket.txt @@ -1,4 +1,4 @@ -= Reading List +# Reading List Building virtual machines in general and programming language implementations in particular requires some knowledge. Rubinius' goal is to lower the barrier @@ -9,7 +9,7 @@ This page contains references to books, online lectures, blog posts and any other publications you may find especially useful for work on Rubinius and Shotgun in particular. -== Virtual machine +## Virtual machine * [Smalltalk-80: language and its implementation](http://tinyurl.com/3a2pdq) by Goldberg, Robson, Harrison (aka "The Blue Book"), implementation @@ -19,14 +19,14 @@ Shotgun in particular. [How send sites work](http://tinyurl.com/34c6e8) -== Garbage collection: +## Garbage collection: * [Garbage Collection: Algorithms for Automatic Dynamic Memory Management](http://tinyurl.com/3dygmo) by Richard Jones * [Garbage collection lectures](http://tinyurl.com/2mhek4) -== Primitive methods +## Primitive methods * [Ruby extensions and Smalltalk primitives](http://talklikeaduck.denhaven2.com/articles/2007/06/04/ruby-extensions-vs-smalltalk-primitives) @@ -34,7 +34,7 @@ Shotgun in particular. primitives](http://www.fit.vutbr.cz/study/courses/OMP/public/software/sqcdrom2/Tutorials/SqOnlineBook_(SOB)/englisch/sqk/sqk00083.htm) -== FFI +## FFI * [Implementing File#link using FFI](http://redartisan.com/2007/10/11/rubinius-coding) doc/reading_list.txt @@ -1,4 +1,4 @@ -= Rubinius Specs +# Rubinius Specs TODO: Imported from Lighthouse wiki. Needs review and update. @@ -10,9 +10,40 @@ divided into two parts: 1. And all the other files under the `spec` directory that describe the behavior of _Rubinius_ -TODO: Explain about developing specs with the hybrid repo. - -== Organization +With the release of the [RubySpec](http://github.com/rubyspec/rubyspec) +project, the Rubinius git repository is now a hybrid repository containing +four different elements. + +1. the Rubinius code itself +1. a _copy_ of the [MSpec code](http://github.com/rubyspec/mspec/tree/master) + at $ROOT/mspec +1. a _copy_ of the [RubySpec + specs](ttp://github.com/rubyspec/rubyspec/tree/master) at + $ROOT/spec/frozen +1. the RubySpec specs as a _clone_ at $ROOT/spec/ruby + +The purpose of the copy of the RubySpecs at $ROOT/spec/frozen ("frozen specs") +is to ensure that there are no regressions caused by new Rubinius code. Since +Rubinius does not pass all the RubySpecs, there are a set of tags in +$ROOT/spec/tags/frozen that are synchronized with the frozen specs and exclude +known failures. These tags are used by the <code>rake spec</code>, <code>rake +spec:full</code> (i.e. `bin/mspec ci` and `bin/mspec ci -B full.mspec`) +commands to run the complete set of specs that are expected to pass. + +The clone at $ROOT/spec/ruby is provided _merely for your convenience_. You do +not have to commit to RubySpecs from this clone. There is nothing special +about the clone. It is not part of the Rubinius repository at all. However, +there are several convenience rake tasks to assist you in working with it. + +Note that the Rubinius spec directory has been a hybrid since its inception. +The RubySpecs are describing the behavior of _MatzRuby_. Rubinius is only +matching that behavior. The rest of the specs are describing behavior +_specific to Rubinius_ that may or may not be relevant to matching the +behavior described by the RubySpecs (e.g. $ROOT/spec/compiler or +$ROOT/spec/library/actor). + + +## Organization The Rubinius specs follow the same general organization (although in different directories) and style as the RubySpecs. So, a good place to start is by @@ -25,7 +56,7 @@ reading through the "RubySpec":http://rubyspec.org documentation. * [Runners](http://rubyspec.org/wiki/mspec/Runners) * [Creating files with mkspec](http://rubyspec.org/wiki/mspec/Mkspec) -=== Ruby specs +### Ruby specs The Rubinius repository contains two copies of the RubySpecs. The `spec/frozen` directory is a git submodule of the RubySpec repository. The @@ -41,7 +72,7 @@ The Rubinius repository also contains a _clone_ of the RubySpecs repository in the `spec/ruby` directory. This clone is included for the convenience of making changes to the RubySpec files directly. -===. Rubinius specs +### Rubinius specs All the other directories under the `spec` directory except for `spec/ruby` and `spec/frozen` are for specs _specific to Rubinius_. The directories are @@ -50,7 +81,7 @@ the Rubinius compiler. Three directories could be confusing so those are described in more detail here. -==== spec/core +#### spec/core This directory is for _Rubinius specific_ extensions to MatzRuby core library. For example, Rubinius has a Tuple and ByteArray class. The specs for these are @@ -60,18 +91,18 @@ Rubinius handles coercion of Bignum and other numeric differently. The `spec/core` directory parallels the purpose of the `spec/ruby/1.8/core` directory from the RubySpecs. -h4. spec/language +#### spec/language Again, this directory contains Rubinius specific specs related to the Ruby language. The directory parallels the `spec/ruby/1.8/language` directory. -h4. spec/library +#### spec/library This directory contains Rubinius specific standard library classes (e.g. Actor, VMActor) and Rubinius specific behavior of methods of MatzRuby standard library classes. -h2. Subtend +## Subtend Subtend is the Rubinius component that provides a C API compatible with MRI. Writing specs for the subtend functions involves writing a C extension. Review doc/rubinius_specs.txt @@ -1,8 +1,8 @@ -= Running Gems on Rubinius +# Running Gems on Rubinius TODO: Imported from Lighthouse wiki. Likely outdated -== Main problem areas of Gem support +## Main problem areas of Gem support Many Gems either depend on currently not supported Ruby Standard Library functionality or on not implemented Subtend (the MRI compatibility layer) @@ -11,7 +11,7 @@ functionality. Another problem to Gem support is left-to-right evaluation that is not yet supported in Rubinius, but should be soon. -== Popular Gems +## Popular Gems Here is a list of popular RubyGems that could be used to test Rubinius' compliance: @@ -36,7 +36,7 @@ Here is a list of popular RubyGems that could be used to test Rubinius' complian * Newjs * merb-core -== Ruby/Mysql +## Ruby/Mysql Tested on April 27 (under shotgun, needs to be tested under the new C++ VM). Seems to be stable and usable, no problems with running SQL-Queries (Create, doc/todo/gems.txt @@ -1,4 +1,4 @@ -= Extending Standard Library Specs +# Extending Standard Library Specs TODO: Imported from Lighthouse wiki. Likely outdated @@ -8,7 +8,7 @@ needs and potentially moved to the [RubySpec](http://rubyspec.org) website. Libraries that need to be spec'ed: -== Small or General usage libs +## Small or General usage libs * Abbrev * Complex @@ -38,9 +38,9 @@ Libraries that need to be spec'ed: * WeBrick * XMLRPC -== Used by popular apps/libs +## Used by popular apps/libs -=== Smaller ones +### Smaller ones * Benchmark * Mutex_m @@ -51,7 +51,7 @@ Libraries that need to be spec'ed: * Set * TimeOut -=== Larger ones +### Larger ones * BigDecimal * CGI @@ -69,9 +69,9 @@ Libraries that need to be spec'ed: * ZLib -== Assigned +## Assigned -=== Federico is covering: +### Federico is covering: * <del>REXML</del> * <del>YAML</del> @@ -79,7 +79,7 @@ Libraries that need to be spec'ed: * <del>Socket</del> * <del>IO</del> -=== Arthur is covering: +### Arthur is covering: * <del>CGI</del> * <del>StringIO</del> doc/todo/specs.txt @@ -1,196 +1,263 @@ -= Using Git +# Using Git -The Rubinius project uses the "Git":http://git.or.cz/ SCM. Committers need to use git to commit their code directly to the main repository. -This page contains information on getting Git installed, getting source code with Git, and steps for working with Git. -Also, see these references: "Git - SVN Crash Course":http://git.or.cz/course/svn.html and "Everyday GIT With 20 Commands Or So":http://www.kernel.org/pub/software/scm/git/docs/everyday.html +TODO: Imported from Lighthouse wiki. Needs review and update. -h2. Getting Git for Your System +The Rubinius project uses the [Git](ttp://git.or.cz/) SCM. Committers need to +use git to commit their code directly to the main repository. This page +contains information on getting Git installed, getting source code with Git, +and steps for working with Git. Also, see these references: [Git - SVN Crash +Course](http://git.or.cz/course/svn.html) and [Everyday GIT With 20 Commands Or +So](http://www.kernel.org/pub/software/scm/git/docs/everyday.html). + + +## Getting Git for Your System You *can* use an earlier version, but 1.5.x is definitely recommended. -* MacPorts has 'git-core' -* Debian has 'git-core' (If you're using Etch, you can get a recent Git version from Backports http://backports.org/dokuwiki/doku.php?id=instructions) -* FreeBSD has 'devel/git' *(I had issues with 1.5.3.2 am using source .7 instead --rue)* -* Get the source at http://git.or.cz/ - -h2. Setup - -Configure Git with your proper name and email. This will display when you submit changes to the Rubinius repository. -@@@ -git config --global user.name "My Name" -git config --global user.email "my@email" -@@@ -If you prefer to use different credentials for different projects, you can also configure the above for a single repository only. See the git documentation. - - -h2. Formatting Git Commit Messages - -In general, use an editor to create your commit messages rather than passing them on the command line. The format should be: - -* A hard wrap at 72 characters -* A single, short, summary of the commit -* Followed by a single blank line -* Followed by supporting details - -The supporting details could be a bulleted enumeration or an explanatory paragraph. The single summary line helps folks reviewing commits. An example commit: -@@@ -Fixes for Module#make_my_day return values. - -* Return nil when passed ':(' -* Return true when passed ':)' -* Updated specs for #make_my_day for nil argument case -* Updated CI excludes. -@@@ - -h2. Getting the Code -Getting the code is easy once you have git installed but is slightly different depending on your access. In both cases that exact command will put the repository in a local directory called @code@. You can give it a different name just by appending it to the command. - -h3. New Users and Developers -@@@ -git clone git://github.com/evanphx/rubinius.git # Notice forward-slash -git clone git://github.com/evanphx/rubinius.git rbx # Creates ./rbx instead of ./rubinius -@@@ - -h3. Existing Committers with Commit Bit -@@@ -git clone git@github.com:evanphx/rubinius.git # Notice colon -git clone git@github.com:evanphx/rubinius.git rbx # Creates ./rbx instead of ./rubinius -@@@ - -h2. Commit Rights - -h3. New Committers -The policy is that if you give us one patch that is accepted and committed, you are eligible to get the "commit bit" which allows you to then start committing directly. In order to create that patch file, see instructions after the Workflow section. Once your patch has been committed, contact @evan@ (IRC will be easiest, PST hours) and let him know. You will want to have the commit hash (more on this below) and the ticket ID handy for him in case the person who committed the patch is not available. Once verified, @evan@ needs your public SSH key (~/.ssh/id_rsa.pub) so paste it into one of the "paste":http://pastie.org "sites":http://rafb.net/paste if it is not up on the web already and give the URL to @evan@. - -h3. Existing Committer from SVN Days -If you are an existing committer but have not been set up on git, tell @evan@ your Github username so he can add you to the project. - - -h2. Git Workflow Using Branches - -Working with Git is significantly different that working with SVN. In particular, although similar, <code>git pull</code> is _not_ <code>svn update</code>, <code>git push</code> is _not_ <code>svn commit</code>, and <code>git add</code> is _not_ <code>svn add</code>. If you are a SVN user, be sure to read the man pages for the different git commands. - -The following workflow is recommended by Evan and is the guideline for contributing code to Rubinius. - -<ol> -<li>Create a local working copy of the source code (we did this earlier.) -@@@ -# See above for the exact invocation -@@@ -</li> -<li>Change to the newly created directory that contains the local working copy. (Substitute the directory if you created it with a different name, obviously.) -@@@ -cd code -@@@ -</li> -<li>Create a branch for your work. This will make a copy of the current branch (master) and name it "new_feature". Now you can work in this new branch without breaking the main one. -@@@ -git checkout -b new_feature -@@@ -</li> -<li>Edit the code and test your changes. Then commit to your local working copy -@@@ -git commit -a -@@@ -</li> -<li>When you are ready to send your local changes back to the Rubinius repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the master branch. -@@@ -git checkout master -@@@ -</li> -<li>Update your local copy with changes from the Rubinius repository -@@@ -git pull - OR -git pull --rebase -@@@ -</li> -<li>Switch back to your topic branch and integrate any new changes. The @git rebase@ command will save your changes away, update the topic branch, and then reapply them. -@@@ -git checkout new_feature -git rebase master -@@@ -Warning! If you are sharing a branch, you must use: -@@@ -git merge master -@@@ -Rebase causes the commit layout to change and will confuse anyone you've shared this branch with. -</li> -<li>If there are conflicts applying your changes during the git rebase command, fix them and use the following to finish applying them -@@@ -git rebase --continue -@@@ -</li> -<li>Now, switch back to the master branch and merge your changes from the topic branch -@@@ -git checkout master -git merge new_feature -@@@ -</li> -<li>You might want to check that your commits ended up as you intended. To do so, you can have a look at the log -@@@ -git log -@@@ -</li> -<li>Get your changes in the main repository. If you have commit rights, you can just use the @git push@ command. Otherwise, see the section below for information on creating a set of patches to send. -@@@ -git push -@@@ -</li> -<li>At this point, you can delete the branch if you like. -@@@ -git branch -d new_feature -@@@ -</li> -</ol> - -This workflow enables you to do a lot of experimenting in your branch (and potentially many branches). However, if you want to work without branches, see the following section. - -h2. Git Workflow Using Branches - -<ol> -<li>Create a local working copy of the source code (we did this earlier.) -@@@ -# See above for the exact invocation -@@@ -</li> -<li>Change to the newly created directory that contains the local working copy. (Substitute the directory if you created it with a different name, obviously.) -@@@ -cd code -@@@ -</li> -<li>Edit the code and test your changes. Then commit to your local working copy -@@@ -git commit -a -@@@ -</li> -<li>Update your local copy with changes from the Rubinius repository -@@@ -git pull --rebase -@@@ -Be sure to use <code>--rebase</code> as this will avoid useless "merge" commits that simply clutter up the history. -</li> -<li>Get your changes in the main repository. If you have commit rights, you can just use the @git push@ command. Otherwise, see the section below for information on creating a set of patches to send. -@@@ -git push -@@@ -</li> -<li> -Rinse and repeat. -</li> -</ol> - -h2. Patches: @git-format-patch@ - -If you are a new committer (or want to create a patch instead of directly pushing the code for some other reason) you should create a patch file for your commits. The patch file should be then attached to a ticket on Lighthouse (see "the ticket writing howto for instructions":http://rubinius.lighthouseapp.com/projects/5089/howto-write-a-ticket for more details on that.) You can also send the patch to the mailing list but use the ticket tracker if at all possible. Either way, the patch file(s) should be created using Git. - -First, make your changes as detailed below and then use the @git format-patch@ command to create the patch files. Usually using the command is as simple as specifying the commits you want to create patches for, and that is done in one of two ways: by giving a range of commits or a starting point. As mentioned earlier, each commit is identified by a unique hash ID which you can see, for example, by looking at the @git log@ output. You can generally shorten it -- first 8 should be plenty -- because it is unlikely to conflict (if it does, just use the full ID instead.) In my examples below I just use imaginary IDs. Let us say you created three commits, in this order @my1stcom -> my2ndcom -> my3rdcom@ (and that the patch before those is @notmycom@): - -* Specify a range of revisions. You can use the syntax @git format-patch my1stcom..my3rdcom@ to include the first, the last and any inbetween. Alternatively, you could use @git format-patch my1stcom..HEAD@ and other variants instead. - -* Specify a single revision. This takes all patches following the one given. The only possibly unintuitive part here is that the revision you give is _the last patch you do *not* want to include_. For example, if you do @git format-patch my3rdcom@ or @git format-patch HEAD@ there will be no patches since there have been none since. In our case, you would want one of the following: @git format-patch notmycom@ , @git format-patch my1stcom^@ , @git format-patch HEAD^^^@ or @git format-patch HEAD~3@ (or any of the other possible variations.) - -(In Git terminology, @HEAD@ is the last commit in your current branch. Parent patches can be referenced either by using a caret so that @HEAD^@ is one before @HEAD@ and @HEAD^^@ is one before one before (i.e. two before) @HEAD@ which gets cumbersome after the second or third caret; or by tilde-number: @HEAD~1@ is one before HEAD, @HEAD~5@ is five before @HEAD@ and much easier to use. The caret and tilde can be used for commit hashes as well. For other variants, see the @git-rev-parse@ man page.) - -Whichever way you decide on, a separate patch file is produced for each, named [number]-[first line of commit message].patch. You can then attach these to a ticket (or e-mail them.) +* MacPorts has 'git-core' +* Debian has 'git-core' (If you're using Etch, you can get a recent Git + version from Backports +* http://backports.org/dokuwiki/doku.php?id=instructions) +* FreeBSD has 'devel/git' *(I had issues with 1.5.3.2 am using source .7 + instead --rue)* +* Get the source at http://git.or.cz/ + + +## Setup + +Configure Git with your proper name and email. This will display when you +submit changes to the Rubinius repository. + + git config --global user.name "My Name" + git config --global user.email "my@email" + +If you prefer to use different credentials for different projects, you can +also configure the above for a single repository only. See the git +documentation. + + +## Formatting Git Commit Messages + +In general, use an editor to create your commit messages rather than passing +them on the command line. The format should be: + +* A hard wrap at 72 characters +* A single, short, summary of the commit +* Followed by a single blank line +* Followed by supporting details + +The supporting details could be a bulleted enumeration or an explanatory +paragraph. The single summary line helps folks reviewing commits. An example +commit: + + Fixes for Module#make_my_day return values. + + * Return nil when passed ':(' + * Return true when passed ':)' + * Updated specs for #make_my_day for nil argument case + * Updated CI excludes. + + +## Getting the Code + +Getting the code is easy once you have git installed but is slightly different +depending on your access. In both cases that exact command will put the +repository in a local directory called `code`. You can give it a different +name just by appending it to the command. + +### New Users and Developers + + git clone git://github.com/evanphx/rubinius.git # Notice forward-slash + git clone git://github.com/evanphx/rubinius.git rbx # Creates ./rbx instead of ./rubinius + +### Existing Committers with Commit Bit + + git clone git@github.com:evanphx/rubinius.git # Notice colon + git clone git@github.com:evanphx/rubinius.git rbx # Creates ./rbx instead of ./rubinius + + +## Commit Rights + +### New Committers + +The policy is that if you give us one patch that is accepted and committed, +you are eligible to get the "commit bit" which allows you to then start +committing directly. In order to create that patch file, see instructions +after the Workflow section. Once your patch has been committed, contact `evan` +(IRC will be easiest, PST hours) and let him know your Github username. + +### Existing Committer from SVN Days + +If you are an existing committer but have not been set up on git, tell `evan` +your Github username so he can add you to the project. + + +## Git Workflow Using Branches + +Working with Git is significantly different that working with SVN. In +particular, although similar, `git pull` is _not_ `svn update`, `git push` is +_not_ `svn commit`, and `git add` is _not_ `svn add`. If you are a SVN user, +be sure to read the man pages for the different git commands. + +The following workflow is recommended by Evan and is the guideline for +contributing code to Rubinius. + +1. Create a local working copy of the source code (we did this earlier.) + + # See above for the exact invocation + +1. Change to the newly created directory that contains the local working + copy. (substitute the directory if you created it with a different name, + obviously.) + + cd code + +1. Create a branch for your work. This will make a copy of the current branch + (master) and name it "new_feature". Now you can work in this new branch + without breaking the main one. + + git checkout -b new_feature + +1. Edit the code and test your changes. Then commit to your local working copy + + git commit -a + +1. When you are ready to send your local changes back to the Rubinius + repository, you first need to ensure that your local copy is up-to-date. + First, ensure you have committed your local changes. Then switch from your + topic branch to the master branch. + + git checkout master + +1. Update your local copy with changes from the Rubinius repository + + git pull + OR + git pull --rebase + +1. Switch back to your topic branch and integrate any new changes. The `git + rebase` command will save your changes away, update the topic branch, and + then reapply them. + + git checkout new_feature + git rebase master + + Warning! If you are sharing a branch, you must use: + + git merge master + + Rebase causes the commit layout to change and will confuse anyone you've + shared this branch with. + +1. If there are conflicts applying your changes during the git rebase + command, fix them and use the following to finish applying them + + git rebase --continue + +1. Now, switch back to the master branch and merge your changes from the + topic branch + + git checkout master + git merge new_feature + +1. You might want to check that your commits ended up as you intended. To do + so, you can have a look at the log + + git log + +1. Get your changes in the main repository. If you have commit rights, you + can just use the `git push` command. Otherwise, see the section below for + information on creating a set of patches to send. + + git push + +1. At this point, you can delete the branch if you like. + + git branch -d new_feature + +This workflow enables you to do a lot of experimenting in your branch (and +potentially many branches). However, if you want to work without branches, see +the following section. + + +## Git Workflow *Without* Using Branches + +1. Create a local working copy of the source code (we did this earlier.) + + # See above for the exact invocation + +1. Change to the newly created directory that contains the local working + copy. (Substitute the directory if you created it with a different name, + obviously.) + + cd code + +1. Edit the code and test your changes. Then commit to your local working + copy + + git commit -a + +1. Update your local copy with changes from the Rubinius repository + + git pull --rebase + +1. Be sure to use <code>--rebase</code> as this will avoid useless "merge" + commits that simply clutter up the history. + +1. Get your changes in the main repository. If you have commit rights, you + can just use the `git push` command. Otherwise, see the section below for + information on creating a set of patches to send. + + git push + +1. Rinse and repeat. + + +## Patches: `git-format-patch` + +If you are a new committer (or want to create a patch instead of directly +pushing the code for some other reason) you should create a patch file for +your commits. The patch file should be then attached to a ticket on Lighthouse +(see "the ticket writing howto for +instructions":http://rubinius.lighthouseapp.com/projects/5089/howto-write-a-ticket +for more details on that.) You can also send the patch to the mailing list but +use the ticket tracker if at all possible. Either way, the patch file(s) +should be created using Git. + +First, make your changes as detailed below and then use the `git format-patch` +command to create the patch files. Usually using the command is as simple as +specifying the commits you want to create patches for, and that is done in one +of two ways: by giving a range of commits or a starting point. As mentioned +earlier, each commit is identified by a unique hash ID which you can see, for +example, by looking at the `git log` output. You can generally shorten it -- +first 8 should be plenty -- because it is unlikely to conflict (if it does, +just use the full ID instead.) In my examples below I just use imaginary IDs. +Let us say you created three commits, in this order `my1stcom -> my2ndcom -> +my3rdcom` (and that the patch before those is `notmycom`): + +* Specify a range of revisions. You can use the syntax `git format-patch + my1stcom..my3rdcom` to include the first, the last and any inbetween. + Alternatively, you could use `git format-patch my1stcom..HEAD` and other + variants instead. + +* Specify a single revision. This takes all patches following the one given. + The only possibly unintuitive part here is that the revision you give is + _the last patch you do *not* want to include_. For example, if you do `git + format-patch my3rdcom` or `git format-patch HEAD` there will be no patches + since there have been none since. In our case, you would want one of the + following: `git format-patch notmycom` , `git format-patch my1stcom^` , + `git format-patch HEAD^^^` or `git format-patch HEAD~3` (or any of the + other possible variations.) + +(In Git terminology, `HEAD` is the last commit in your current branch. Parent +patches can be referenced either by using a caret so that `HEAD^` is one +before `HEAD` and `HEAD^^` is one before one before (i.e. two before) `HEAD` +which gets cumbersome after the second or third caret; or by tilde-number: +`HEAD~1` is one before HEAD, `HEAD~5` is five before `HEAD` and much easier to +use. The caret and tilde can be used for commit hashes as well. For other +variants, see the `git-rev-parse` man page.) + +Whichever way you decide on, a separate patch file is produced for each, named +[number]-[first line of commit message].patch. You can then attach these to a +ticket (or e-mail them.) doc/using_git.txt @@ -1,4 +1,4 @@ -= The Rubinius Virtual Machine +# The Rubinius Virtual Machine TODO: Imported from Lighthouse wiki. Outdated. Needs significant revision. @@ -7,7 +7,7 @@ from his earlier VM implemented in Ruby. The VM has several basic parts: parser, CPU, garbage collector. -== Object model +## Object model In Ruby, everything is an object. In the Rubinius C code, these are kept as `OBJECT`, which are `uintptr_t`. @@ -56,7 +56,7 @@ contain the actual array, and `String` uses an ancillary data structure data structure for a different-sized one, the Array/String can change its size and still stay the same object. -== Source Files +## Source Files The basic object model is defined in `include/rubinius.h`. All other C files are in `shotgun/lib`, a prefix which will be elided in the rest of this. @@ -102,7 +102,7 @@ activation records: `heap.c`, `object_memory.c` and `state.c` are the basis for memory management, see below. -== Garbage Collection +## Garbage Collection Garbage Collection is central to the workings of a VM for a modern language like Ruby. Ruby does not provide a way for objects to be deleted; instead, doc/virtual_machine.txt b7b428947961d28fae350230c9394f89e6d18517 Brian Ford bford@engineyard.com http://github.com/evanphx/rubinius/commit/059d6bb008f7629426414df48d6b0505b48203a8 059d6bb008f7629426414df48d6b0505b48203a8

2008-11-22T14:40:57-08:00

A few more docs and RDoc to Markdown conversion. 95dff1afaafaf08da9addbe1b7ca9a4fd03a3e8b Brian Ford bford@engineyard.com