Skip to content
This repository has been archived by the owner on Sep 14, 2018. It is now read-only.

Home

Jump to bottom
shri edited this page Sep 13, 2010 · 71 revisions

Welcome to the IronRuby Developer Wiki! Everything here will help you contribute to IronRuby. If you are interested in just using IronRuby, please see the main website at http://ironruby.net.

Getting the latest source
Building (Visual Studio (Profession or Express), command line, Mono)
Debugging with VS
RubySpec
Contributing


h2. Getting the latest source

Installing GIT

This page describes how to install and use GIT

Creating a local GIT repository

You will first need to fork the IronRuby project. Creating a fork is recommended as it will allow you to contribute patches back easily. Click the “Fork” button on http://github.com/ironruby/ironruby/tree/master. This should create your personal fork, with a website like http://github.com/janedoe/ironruby/tree/master (where janedoe is your GIT username).

You can now use the git command-line client with many Linux distributions, Mac OS, Cygwin, and Windows (msysgit) to get the sources onto your local computer using the following commands:

git clone [email protected]:janedoe/ironruby.git

git remote add irmain

git fetch irmain

git checkout —track -b irmain irmain/master

git pull

git checkout master

At a later date, to get the latest updates from the IronRuby project, run the following command in the ironruby directory created above:

git fetch irmain master

Working without a fork

You can skip creating a fork if you only want to browse the sources. In that case, you can clone the project directly as such:

git clone git://github.com/ironruby/ironruby.git

git pull


h2. IronRuby dev environment


h3. Setup

Merlin\Main\Languages\Ruby\Scripts\dev.bat sets up an environment which makes it easy to do builds and run tests. You can run this from a Command Prompt to setup a nice IronRuby environment.

If you do significant IronRuby development work, it is easier to setup a shortcut on the desktop that you can just click. To do this, create a shortcut on the Desktop to cmd.exe looking like this (where c:\github\ironruby is the root of your GIT repo).

Target:



C:\Windows\System32\cmd.exe /k “c:\github\ironruby\Merlin\Main\Languages\Ruby\Scripts\Dev.bat”

Start in: 
c:\github\ironruby\Merlin\Main\Languages\Ruby


h3. Folder layout

This is what the folder structure of the source repo looks like.

  • Root (eg: c:\github\ironruby)
    • Merlin
      • Main [ r ]
        • Languages
          • IronPython
          • Ruby [ rb ] – Contains Ruby.sln
            • Scripts – Contains dev.bat
              • bin – Contains igem.bat, etc
      • External
        • Languages
          • IronRuby
            • mspec [ mspc ]
          • Ruby
            • redist-libs
      • Users
    • ndp – Acronym for .Net Developer Platform. This contains the components that will ship with the .NET Frameworks.
      • fx
        • src
          • Core
            • Microsoft
              • Scripting – Contains Microsoft.Scripting.Core.csproj


h3. Command-line aliases

See Merlin\Main\Scripts\Bat\Alias.txt for the available command-line aliases. A few of the most useful ones are:

  • rb – Go to the Ruby folder
  • brbd – Build Debug
  • rbd – Run ir.exe


h3. Tips and Tricks

http://davesquared.blogspot.com/2009/02/setting-up-diff-and-merge-tools-for-git.html describes how to set configure diffing tools for GIT.


h2. Building


h3. Visual Studio

  1. Open the file Ruby.sln in /Merlin/Main/Languages/Ruby. (Don’t open the IronRuby.sln, it’s deprecated).
  2. You will get two dialog boxes complaining about source control. Press “OK” for both of them.

  3. Type “F6” to build the solution.


h3. Command line (via rake)

  1. Install the latest Ruby with gems enabled (such as the Ruby One-Click Installer v1.8.6-25 or below)
  2. Install required gem. Open a command-prompt and type:
     gem install pathname2

     gem install rake
  3. Open up the Visual Studio 2008 Command prompt or, if using Visual Studio Express, run:
     PATH=%PATH%;c:\Windows\Microsoft.NET\Framework\v3.5\;C:\Program Files\Microsoft Visual Studio 9\SDK\v3.5\Bin
  1. To view a list of all available rake targets, run the following command from the Merlin\Main\Languages\Ruby directory of the source code:
    rake —tasks
  2. Run the following command from the same directory 
     rake compile

Here’s a video of getting the IronRuby source code


h3. Mono

Building the Mono runtime

You can use Mono 2.2 release just fine.

Previously, you had to build Mono from SVN. Instruction is still provided below in case it is needed again. (Reference: http://www.mono-project.com/AnonSVN)

svn co svn://anonsvn.mono-project.com/source/trunk/mono 
svn co svn://anonsvn.mono-project.com/source/trunk/mcs 
cd mono
./configure
make
make install

If you built Mono from source, make sure pkg-config can find the built Mono. For example: 

export PKG_CONFIG_PATH=“/opt/mono/lib/pkgconfig”

Build IronRuby

The branch at http://github.com/mletterle/ironruby is likely to work better with Mono as it has continuous integration for Mono.

git clone git://github.com/mletterle/ironruby.git
cd ironruby
git checkout -b linux
git pull origin linux

Check the status of the continuous integration to see if there are any known build issues. The steps for the build are:

cd ironruby 
rake compile mono=1

Alternatively you can use the build command that is included in that linux branch. That command will compile IronRuby and deploy it to ~/bin. If you then add ~/bin to your PATH environment variable you can run ironruby files by invoking the command ir my_file.rb. Also the iirb, igem, … commands are deployed to the ~/bin.

cd ironruby
chmod +x build
./build

And then you can run it with Mono



mono build/mono_debug/ir.cmd


h3. Tips

  • Make sure that csc.exe is in your PATH environment variable. Default location is:
     c:\Windows\Microsoft.NET\Framework\v2.0.50727
  • Make sure that resgen.exe is in your PATH environment variable. Default location is:
     c:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin


h3. Debugging with Visual Studio

Using Visual Studio allows you to use an IDE to set breakpoints, step into code, etc. This works very well for debugging the IronRuby runtime. Debugging Ruby code is a work in progress.

Debugging C# code

In the Debug tab of the Project properties for Ruby.Console.csproj, set the fields as follows:

  • Start Action:
    For Ruby.Console.csproj, “Start project” should be enabled.

For any other project, “Start external program:” should be enabled and set to “c:\vsl\Merlin\Main\Bin\Debug\ir.exe”

  • Start Options:
    You can leave “Command line arguments” empty to get the REPL loop, or set it to the path to some .rb file to run the .rb file. Hitting F5 should now run the .rb file under VS, and allows you to set breakpoints as you would expect in IronRuby.dll and IronRuby.Libraries.dll (ie. in C# source code).

Debugging Ruby code

If you want to put breakpoints in Ruby code, make sure to remove the -X:Interpret option and instead add the -D option (which will cause IronRuby to use the debuggable System.Reflection.Emit.AssemblyBuilder instead of the non-debuggable System.Reflection.Emit.DynamicMethod).

If you want to have a ruby-debug-like-debugger method to insert a VS breakpoint via Ruby code


h4. Debugging a single RubySpec example

The most common way of running a rubyspec is to use the “rake mspec” task. Unfortunately this runs “mspec ci”, which spawns a new process to run the actual specs – this allows mspec can be run under one ruby implementation, while the rubyspec in question is executed by another. This makes it difficult to debug because the VS debugger attaches to the initial “mspec ci” process rather than the one that is actually executing the spec.

It is possible to pause the execution of the rubyspec, by modifying its code (with a call to gets for example) and then attaching the VS debugger to the spawned rubyspec process.

A better solution is to use the mspec-run command, since this does not spawn new processes. Despite this the mspec-run command still needs to know the location of a ruby implementation since it reuses code from the standard mspec command. (This is inside the mspec/lib/mspec/helpers/ruby_exe.rb file if you are interested). This file tries to ascertain under which ruby implementation we are running the rubyspec. The code that does this is not very IronRuby friendly (although it tries to be). The easiest way to ensure that mspec can find the ir.exe executable is to create an environment variable:

SET RUBY_EXE=/path/to/your/ir.exe

If you are running ir.exe with options e.g. -X:Interpret, you also need to set another variable:

 SET RUBY_FLAGS="-options"

I haven’t checked but I am pretty sure RUBY_EXE will be happier if you use forward slashes.

Once you have done this you can test whether mspec-run is going to work…

c:/path/to/mspec/bin:>/path/to/ir.exe mspec-run

If all is well you will get a usage message from mspec. If not then you will get a message saying that it could not find a suitable ruby executable.

Finally set up VS to run the mspec-run command as follows:

“Command line arguments” should be set to the following for running the “supports /i for ignoring case” example of string\gsub_spec.rb:

-v -X:Interpret

/path/to/mspec/bin/mspec-run

-e “supports /i for ignoring case” -fs -V -B 

/path/to/default.mspec

/path/to/rubyspec/core/string/gsub_spec.rb

Hitting F5 should now run the single RubySpec example under VS.

Clone this wiki locally