A Beginner's Guide to Microsoft's shared Source CLI (Rotor)

Taking things apart (radios, blenders, televisions, an Atari 2600, etc.) as a child in order to see how they were constructed and operated is probably what got me started in computer programming. As an adult my insatiable need to hack a particular technology apart is quenched by Microsoft's Shared Source CLI (Common Language Infrastructure); more commonly known as Rotor.

Brief Overview

The Common Language Infrastructure (CLI) is the ECMA standard that describes the core technologies contained in .NET. Rotor implements this standard. In addition, other projects (Mono and Portable .NET) implement the CLI standard to run on Linux. Microsoft's implementation runs on Windows XP, Mac OS X, and FreeBSD via a Portable Abstraction Layer (PAL). The PAL sits between the operating system and the CLI and maps several dozen function calls between the two.

Rotor allows people (researchers, programmers, teachers, etc.) to view, debug, and analyze .NET source code. Is Rotor's source code the same as the proprietary .NET commercial source code? No. However, both sets of code are from the same early source tree branch. One matured into the commercial version. The other evolved into Rotor. The base virtual hosting techniques of .NET still apply within Rotor: assembly loading, JIT compilation, garbage collecting, IL emitting, compilers (C#, JScript, and a sample LISP how to), security protocols, metadata usage, etc. All conform to the ECMA CLI standard. A full list of features and tools contained in the Rotor download can be found on MSDN (http://msdn.microsoft.com/net/sscli ).

Diving In

The current Rotor tarball is about 18 MB, contains over a million lines of code, and around 14,000 files. Most of the .NET framework class libraries are present except for ADO.NET, Windows Forms, Web Forms, and Web Services. Either you or the Rotor community will have to implement these. On a less painful note, remoting, networking, and XML functionality (and source) are included.

It's a good idea to have a decent computer before installing and building Rotor's code. I chose to perform a "checked" build type.

Build Types:
checked Turns optimizations off, enables debug code, and generates debugging symbols.
fastchecked Turns optimizations on, enables debug code, and generates debugging symbols.
free Turns optimizations on, disables debug code, and generates debugging symbols.

Compiling all of the source code took about 25 minutes on my humble machine.

My Humble Machine:
Processor Dual Pentium II 450 MHz
RAM 512 MB
Disk Space 30 GB
OS Windows XP Professional SP1
.NET Framework Visual Studio .NET 2003 (C#, C++, VB)
Perl ActivePerl 5.8.0 build 806

There are plenty of articles scattered throughout the Internet (and contained in the Rotor tarball) concerning Rotor setup and installation. I will not repeat the self-explanatory instructions. The above system configuration resulted in zero errors and warnings.

After a successful installation, it is important to run "env" correctly or you will end up using Visual Studio's C# complier instead of Rotor's. If you decided to perform the "checked" build, you simply type "env checked". The same parameter applies to "fastchecked" and "free" build types. After entering the appropriate environment your screen should look similar to the following:


Figure 1

Optionally, you should test your build using Rotor's test suite. The "rrun.pl" Perl script is the most comprehensive. A word of warning: it took my humble machine 17 hours to complete!

Compiling, Executing, and Debugging

Using Visual Studio or a basic text editor, generate the following C# file:

// File: HelloWorld.cs
public class HelloWorld
public static void Main()
System.Console.WriteLine("Hello, world!");

Open a command prompt and navigate to Rotor's root directory (probably something like f:\sscli). Execute the appropriate "env" command plus build type parameter to establish the environment to run Rotor. Next, navigate to the directory where the HelloWorld.cs file was saved. Enter the following command to compile:


Figure 2

You use Rotor's "clix" program to run the HelloWorld.exe assembly.


Figure 3

Utilizing Visual Studio .NET 2003 is my preferred way to debug code and observe want is occurring underneath of Rotor. Others like to debug using "cordbg". I am familiar with Visual Studio, find it easier to use, and enjoy the fancy GUI. In order to debug Rotor using Visual Studio .NET type the following at the command prompt:


Figure 4

After Visual Studio initializes, press "F11" and save a default solution. Set breakpoints, step into, and step over the code as you would in any Visual Studio project. Moreover, create several large objects and step through the comutilnative.cpp file to watch garbage collection in action!


Figure 5


Microsoft's Shared Source CLI provides a vast amount of code, design techniques, theory, and documentation to help individuals appreciate what is going on behind the .NET scenes. Most people are content with populating an ArrayList of Employee objects in a VB.NET business application. Others are curious to understand the "how" and "why". Rotor facilitates the answers. Let the hacking begin!