Published on ONDotNet.com (http://www.ondotnet.com/)
 See this if you're having trouble printing code examples

Get Your Rotor Running

by Brian Jepson

So, you'd like to experiment with Rotor. Given that it's made up of approximately 9,700 files and 1.9 million lines of code, it is definitely a little intimidating. Fortunately, the build process is simple, and when it's done, you're only looking at a handful of tools. So, you don't need to grok all those files and lines of code at once; you can take your time and explore Rotor at your own pace. For a high-level overview of Rotor, you will want to read David Stutz's architectural tour.

Required Software

The first release of Rotor can be compiled on Windows or FreeBSD. Aside from plenty of memory, you'll also need Perl. Most installations of FreeBSD will have Perl, but if not, cd to /usr/ports/lang/perl5 and run make install as root. On Windows, you can download Perl from ActiveState. Windows users will also need Visual Studio .NET. For the first release of Rotor, the .NET Framework SDK will not suffice. So, if you don't own a copy of Visual Studio .NET, FreeBSD is the cheapest way to go. See the O'Reilly Network BSD DevCenter for lots of good information on FreeBSD.

Required Hardware

You will need about 80 megabytes of disk space to extract the Rotor source code. However, Rotor will end up using much more when its compilation is complete (about a gigabyte on FreeBSD, and half that on Windows). You should set aside a bit more to account for temporary files and swap file growth.

To compile Rotor, 512 megabytes of physical memory is recommended, but you can get away with 256. With any less than that, be prepared for a lot of swapping and a long compilation. The next table shows some build times on various platforms:

CPU Front Side Bus Operating System Memory IDE DMA Mode Build Time
1200mhz Athlon Desktop 266mhz FreeBSD 4.5 512 MB UDMA 100 28 minutes
1200mhz Athlon Desktop 266mhz Windows 2000 512 MB UDMA 100 11 minutes
600mhz Pentium III Notebook 100mhz FreeBSD 4.5 256 MB UDMA 33 57 minutes
600mhz Pentium III Notebook 100mhz Windows XP 256 MB UDMA 33 29 minutes
600mhz G3 iBook 100mhz Windows 2000 (running under Virtual PC 5.0.2) 256 MB allocated to Windows 2000 (384 MB installed) UDMA 33 3 hours

Getting Rotor

Comment on this articleTried it out? What are your initial impressions?
Post your comments

To download Rotor, and for support and license information, visit Microsoft's Shared Source CLI Beta page.

Now that you've verified the requirements (and probably upgraded the RAM in your computer), it's time to get started. The first thing you'll need to do is get Rotor.

One of the key considerations that went into the design of the Rotor's shared source license is that a programmer should be able to look at the Rotor source without becoming tainted. Indeed, one of Microsoft's goals for Rotor is to be a guide for anyone who implements the ECMA CLI whether for an open source or proprietary project. Nevertheless, it will be some time before open source project organizers have had a chance to form an opinion about the Rotor's shared source license. So, if you are an active contributor to a project that overlaps with Rotor, you should check with the project organizers before looking at the source code.

Head on over to Microsoft's Shared Source CLI Beta page for the download. The Rotor source is available as an approximately 11.3 megabyte gzipped tar file. Download it to your computer and extract it with tar (note that the actual filename may vary):

$ gzip -dc sscli.tgz | tar xvf - 

If you are on FreeBSD, tar will be available on your system. If you are on Windows, you'll need to get tar and gzip. WinZip supports tar files, and you can download command line versions of tar and gzip for Windows at ftp.gnu.org.

After you've extracted the archive, change directory (cd) into the top-level directory that was created:

$ cd sscli 

Preparing to Build

Before you go any further, be sure to peruse the readmefirst.html file, since it will contain late-breaking news.

To set up your environment under Windows, you must run env.bat. You'll need to run this batch file before you build Rotor, or to use any of the Rotor applications.

C:\src\sscli> env.bat
Setting environment for using Microsoft Visual Studio .NET tools.
(If you also have Visual C++ 6.0 installed and wish to use its tools
from the command line, run vcvars32.bat for Visual C++ 6.0.)
CLR environment (C:\src\sscli\clr\bin\rotorenv.bat)
Building for Operating System - NT32
             Processor Family - x86
                    Processor - i386
            Build Environment = C:\src\sscli\rotorenv
                   Build Type - fastchecked

To set up your environment under FreeBSD, you must source in env.sh (if you are using an sh variant such as bash) :

$ . env.sh
Fastchecked Environment
Use env.csh if your shell is csh (or a csh variant such as tcsh):
% source env.csh
Fastchecked Environment

Building Rotor

Now that you've loaded env.bat, env.sh, or env.csh, your environment is set up to compile Rotor. To compile Rotor, run buildall.cmd on Windows, or ./buildall on FreeBSD (the leading ./ tells your shell to run the buildall command that's in your current directory--most installations of Unix will never have . in the $PATH environment variable).

The Windows Build

When buildall starts on Windows, this is what you'll see:

C:\src\sscli> buildall

--- Building the PAL ---

Build successful.

--- Building the binplace tool ---
followed by a whole bunch of other stuff for the next half hour or so. When it is finished, you should see something similar to the following (the exact output may differ):
Compiling - grep\@objdf\rotor_x86\csc.rsp for all platforms
Binplacing - grep\objdf\rotor_x86\ngrep.exe for all platforms
Binplacing - grep\grep\objdf\rotor_x86\ngrep.exe for all platforms

    6 files binplaced

The FreeBSD Build

When buildall starts on FreeBSD, this is what you'll see:

% ./buildall
creating cache ./config.cache
checking whether make sets ${MAKE}... yes
checking for gcc... gcc
checking whether the C compiler (gcc  ) works... yes
checking whether the C compiler (gcc  ) is a cross-compiler... no

and so forth. When it's finished, you should see something similar to (the exact output may differ):

Compiling - grep/@objdf/rotor_x86/csc.rsp for all platforms
Binplacing - grep/objdf/rotor_x86/ngrep.exe for all platforms
Binplacing - grep/grep/objdf/rotor_x86/ngrep.exe for all platforms

    6 files binplaced

Running Tests

Rotor comes with a comprehensive test suite. To run the tests, cd to the sscli/tests directory, and run the command perl rrun.pl:

% perl rrun.pl
Rotor Test Driver - Version 1.0
Microsoft Corp. - All Rights Reserved

RRUN: Run Started Tue Mar 19 12:06:50 2002

By default, rrun.pl executes every test. Examine the source code for rrun.pl for other options (look for the comment block titled "Feature Notes").

Rebuilding Rotor

If you decide to change one of the source files after compiling Rotor, you can rebuild Rotor by running build -z in the directory above where you made modifications:

% cd sscli/clr/src/vm/
% touch util.cpp
% cd ..
% build -z
BUILD: Object root set to: ==> objdf
BUILD: Compile and Link for rotor_x86
BUILD: Examining /usr/home/bjepson/src/sscli/clr/src directory tree for
files to compile.

This will take care of most cases where you have modified the source code, but consult the document sscli/docs/buildtools/building_rotor.html for all the gory details.

Dave Stutz is coauthoring O'Reilly's upcoming book on Rotor, Shared Source CLI Essentials. This book will provide a roadmap for anyone trying to navigate or manipulate the Shared Source CLI code, and will include a CD-ROM that contains all the source code and files.

Using Rotor

Now that you've compiled Rotor, you are ready to compile applications and test them out. After the build completes, it puts executables and libraries into the sscli/build/v1.x86fstchk.rotor/ directory and its sdk/bin and int_tools subdirectories. The env.(csh|bat|sh) script puts these in your PATH for you and sets up other important variables, so you'll need to run it each time you log in.

You should poke around in these directories. If you're familiar with the .NET Framework SDK directory layout (%SystemRoot%\Microsoft.NET\Framework\VERSION\), you'll see some familiar applications and libraries.

Compiling "Hello, World"

Here's a simple "Hello, World" program you can create using your favorite editor, and save as Hello.cs. I suggest that you create this outside of the Rotor source tree so you don't introduce any cruft.

using System;
class Hello 
  public static void Main() 
    // Create an array of strings.
    string[] greeting = new string[] {"Hello", ", ", "World", "!"};

    // Display each element.
    foreach(string s in greeting) 

    // Display a newline.

Hello.cs prints the familiar "Hello, World" message the hard way (but in a way that's interesting if you run it under a debugger).

To compile this program, run the command csc /debug Hello.cs Here is what you should see on FreeBSD:

% csc /debug Hello.cs
Microsoft (R) Visual C# .NET Compiler version 
for Microsoft (R) .NET Framework version ---
Copyright (C) Microsoft Corporation 2001. All rights reserved.

If you are on Windows, please supply an explicit path to the csc executable, so you can be absolutely sure you're not running the csc that comes with Visual Studio:

C:\> sscli\build\v1.x86fstchk.rotor\csc /debug Hello.cs
Microsoft (R) Visual C# .NET Compiler version
for Microsoft (R) .NET Framework version ---
Copyright (C) Microsoft Corporation 2001. All rights reserved.

FreeBSD Users: If you can't execute a Rotor program even after you've sourced in the env.(csh|sh) script, type hash (under shells from the Bourne family) or rehash (under csh or tcsh). This will rebuild the hashtable used to locate executables. The only time you'll need to do this is when executables are added after you've sourced in the shell script (such as the first time you compile Rotor).

Running and Debugging "Hello, World"

After you compile Hello.cs, you're left with Hello.exe. On Windows, this is a valid .NET executable: if you run Hello.exe from the command-line, it will run under the .NET Framework SDK.

To run Hello.exe under Rotor, use the clix executable:

% clix Hello
Hello, World!

To debug Hello.exe, you can load it up using the cordbg executable. If you are on Windows, please use an explicit path for cordbg to distinguish it from the cordbg that comes with the .NET Framework SDK. Here is a sample session with cordbg:

C:\> sscli\build\v1.x86fstchk.rotor\sdk\bin\cordbg Hello
Microsoft (R) Common Language Runtime 
Test Debugger Shell Version 1.0.3705.0
Copyright (C) Microsoft Corporation 1998-2002. 
All rights reserved.

(cordbg) run Hello
Process 1024/0x400 created.
Warning: couldn't load symbols for
[thread 0x0] Thread created.

007:     string[] greeting = new string[] {"Hello", ", ", "World", "!"};
(cordbg) so

010:     foreach(string s in greeting)
(cordbg) so

011:       Console.Write(s);
(cordbg) print s
s=(0x00a805e4) "Hello"
(cordbg) so
010:     foreach(string s in greeting)

Related Articles

An Architectural Tour of Rotor

You Can Hack .NET Without Buying Visual Studio .NET

Uncovering Rotor -- A Shared Source CLI

The run Hello command is automatically added by cordbg when you specify Hello on the command line. The so command executes each line of code without stepping into any function calls (such as Console.Write), and the print command displays a variable. For an in-depth cordbg tutorial, see my article, "You Can Hack .NET Without Buying Visual Studio .NET.".

Where to Go From Here

Rotor is a big piece of code, and there's a lot to look at. It's best if you explore it slowly, and with whatever help you can find. To that end, work is under way to establish a Rotor community site where you can collaborate with other Rotor users. Also, DevelopMentor has created the DOTNET-ROTOR mailing list, which should attract many Rotor enthusiasts. And keep your eyes out for O'Reilly's Shared Source CLI Essentials, which will provide a roadmap to Rotor's many million lines of code. If you combine the book, the mailing list and community site, you will be in good hands!

Brian Jepson is an O'Reilly editor, programmer, and co-author of Mac OS X Panther for Unix Geeks and Learning Unix for Mac OS X Panther. He's also a volunteer system administrator and all-around geek for AS220, a non-profit arts center in Providence, Rhode Island. AS220 gives Rhode Island artists uncensored and unjuried forums for their work. These forums include galleries, performance space, and publications. Brian sees to it that technology, especially free software, supports that mission. You can follow Brian's blog here.

Return to the .NET DevCenter.

Copyright © 2009 O'Reilly Media, Inc.