Setting Up SSCLI Build and Debug Environment

The SSCLI downloaded from Microsoft’s website is a 15MB archive. This article covers how to compile, run, debug SSCLI and examine its code.

SSCLI is cross-platform, running on Windows, FreeBSD, and Mac OS. Some experts have reportedly run it on Linux too. I’ll focus on Windows.

Prerequisites:

• OS: Microsoft Windows XP
• Visual Studio .NET 2003 Professional (at minimum VC++.NET)
• Active Perl (for the build scripts)
• Source Insight (code navigation with symbol jumping)
• Windbg (Microsoft debugger, for debugging SSCLI)

Building SSCLI:

1. Extract the archive to a drive root, e.g. F:\sscli
2. Open cmd.exe and CD to F:\sscli
3. Run: env.bat checked
   • Three build variants: checked (no optimization, debuggable), fastchecked (optimized + debuggable), free (fully optimized, release). Use checked for easiest debugging.
4. Run: buildall
   • Six build stages: PAL + unmanaged tools, other unmanaged tools, SSCLI runtime + C# compiler, trimmed .NET Framework class libraries, serialization/remoting assemblies, managed compilers (JScript compiler etc.)
   • After ~30 minutes if all goes well. Check buildd.log, buildd.wrn, buildd.err in subdirectories if errors occur.
5. Test: CD to the build directory and run csc /?. You should see:
   Microsoft (R) Visual C# Shared Source CLI Compiler version 1.0.0003 for Microsoft (R) Shared Source CLI version 1.0.0 Copyright (C) Microsoft Corporation 2002. All rights reserved.

Running and Debugging Your First Program:

Create Hello.cs:

using System; class Hello { static void Main(string[] args) { int x = 10; System.Console.WriteLine("Hello World, x is {0}", x); } }

Copy to F:\sscli\build\v1.x86chk.rotor and compile:

csc /debug+ /t:exe Hello.cs

This produces Hello.exe and Hello.ildb (debug symbols). To run purely through SSCLI (not the system .NET Framework), use:

clix Hello.exe

Output: Hello World, x is 10

Debugging with cordbg:

SSCLI includes cordbg (in sdk\bin), a command-line managed code debugger.

> sdk\bin\cordbg.exe (cordbg) run Hello.exe

The debugger stops at the first line. Use g to go, ? for help.

Debugging SSCLI’s Own (Unmanaged) Code:

Since cordbg can’t debug unmanaged code, use Windbg for the CLI execution engine (GC, metadata, etc.).

Create a batch file:

F: cd F:\sscli\build\v1.x86chk.rotor call F:\debug\windbg clix Hello.exe

In Windbg:

0:000> bp main 0:000> g

Code Walkthrough of clix.exe:

The Launch function in clix maps Hello.exe as a memory-mapped file, validates PE headers, loads sscoree.dll, and calls _CorExeMain2. Setting a breakpoint at Launch and stepping into _CorExeMain2 takes you into F:\sscli\clr\src\vm\ceemain.cpp — welcome to the .NET virtual machine.

Tracing SSCLI Dynamic Execution:

SSCLI provides powerful logging via environment variables. For example:

> set COMPlus_JitTrace=1 > clix Hello.exe

This outputs all JIT-compiled methods. See \docs\techinfo\logging.html for complete documentation.

With tools and environment set up, we’re ready to explore SSCLI’s depths.