readfirst.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>

<head>
<title>Microsoft Shared Source CLI</title>
<link rel="stylesheet" type="text/css" href="docs/rotor.css">
</head>

<body>

<h2 class="top">Welcome!</h2>
<h3>Contents</h3>
<ul>
  <li><a href="#WhatsNew">What's New in the Microsoft Shared Source CLI 2.0 Release?</a></li>
  <li><a href="#Intro">What is the Microsoft Shared Source CLI?</a></li>
  <li><a href="#GettingStarted">Getting Started</a></li>
  <li><a href="#BuildingandRunningCode">Building and Running Code</a></li>
  <li><a href="#TestingRotor">Testing Rotor</a></li>
  <li><a href="#security">A Note About Security</a></li>
  <li><a href="#licenses">Yet More on Licensing</a></li>
  <li><a href="#DocumentationStyle">A Comment on Documentation Style</a></li>
</ul>
<h2><a name="WhatsNew"></a>What's New in  the 
Microsoft Shared Source CLI 2.0 Release?</h2>
  <p>
      Some interesting new features in the SSCLI 2.0 release include:</p>
<ul>
    <li>Generics</li>
    <li>Lightweight Code Generation (LCG)</li>
    <li>Open static and closed instance Delegates</li>
    <li>Relaxed Delegates</li>
    <li>Loader and System.Reflection re-writes</li>
    <li>Metadata format updates</li>
    <li>New C# features like Anonymous Methods, Anonymous Delegates and Generics support</li>
    <li>Numerous BCL additions</li>
    <li>Stub based dispatch support (in supported callsites)</li>
    <li>Numerous bug fixes</li></ul>
<h2><a name="Intro"></a>What is the Microsoft Shared Source CLI (SSCLI)?</h2>

<p>The Microsoft&reg; Shared Source CLI 2.0 is a working implementation of the
<a href="http://msdn.microsoft.com/net/ecma">ECMA-334 and ECMA-335 standards</a> 
(known to us mortals as the Common Language Infrastructure and the C# 
programming language). The source code in this distribution builds Microsoft® Windows only,
    support for further platforms is planned. Besides the CLI and the C# compiler, this 
distribution contains a JScript compiler written entirely in C#, as well as a 
wide variety of tools, utilities, managed classes, and samples. It is intended 
to be an appealing new platform alternative for people who want to learn, to 
teach, to tinker, or to experiment more formally with computer languages and 
computer language infrastructure.</p>
<p>This is the forth release of the Shared Source CLI, and the first release for the
    2.0 implementation of the runtime and framework. You can find older versions of
    the SSCLI at <a href="http://msdn.microsoft.com/net/sscli/">http://msdn.microsoft.com/net/sscli/</a>. It is for 
non-commercial, experimental use only.&nbsp; The distribution is completely unsupported, although the 
development team will be checking in on the <code>
microsoft.public.shared_source.cli</code> newsgroup.</p>
    <p>
        The Shared Source CLI 2.0 is being distributed as source code under 
a Shared Source license. It is important for you to read through the brief
<a href="license.txt">license</a> that is included with your copy of this 
distribution now, because once you examine the code or use it in any way, you 
will be bound by the terms of this license.&nbsp; For more information about the 
Shared Source program at Microsoft, take a look at the Microsoft Shared Source 
Initiative Web page at 
    <a href="http://www.microsoft.com/resources/sharedsource/default.mspx">http://www.microsoft.com/resources/sharedsource/default.mspx</a><a href="http://www.microsoft.com/sharedsource"></a> or search
<a href="http://www.microsoft.com/">www.microsoft.com</a> for &quot;Shared Source&quot;.
    </p>
<p>By default, the build scripts in this distribution produce an optimized debug 
build of the tools and runtime. This is because we believe that most of you are 
programmers, and that you will want to be spelunking around in the debugger but 
you still want reasonable execution performance.&nbsp; If you want maximum 
source debugging support you should choose a checked build which will turn off 
optimizations and allow better source-level debugging.&nbsp; If you want to get 
more performance, you can build a free build, which will execute code 
considerably faster. For instructions, see the detailed build instructions in
<a href="docs/buildtools/building_sscli.html">building_sscli.html</a>. </p>
<p>Colloquially, we refer to this project as Rotor, and this 2.0 release as Rotor Whidbey.&nbsp;Why? Well, you'll find 
the following definitions for the word Rotor:
</p>
<ul>
  <li>An altocumulus cloud found in the lee of large mountain barriers, that 
  circulates around its horizontal axis.</li>
  <li>An important part of a cryptographic encoding or decoding device.</li>
  <li>A quantity having magnitude, direction, and position.</li>
  <li>The rotating part of a dynamo, turbine, distributor, compressor, 
  centrifuge, blower, or motor.</li>
  <li>A device that propels a ship forward in a cross-wind, exploiting the 
  Magnus effect.</li>
  <li>The rotating airfoil assembly on rotary-wing aircraft.</li>
</ul>
<p>It's obvious! Rotor is all of these <i>and more</i>... </p>
<p></p>
<h2><a name="GettingStarted"></a>Getting Started</h2>
<p>Please read the <a href="license.txt">license</a> before you begin.</p>
<p>OK, having taken care of that, Rotor has been built and tested on
<a href="http://www.microsoft.com/windowsxp">Windows XP only</a>. If you want to build and run 
the source code, you'll need some additional software.&nbsp; 
The Rotor build process uses Perl in several ways, both to run the test harness 
and as a way to autogenerate some utility code. You will need 
Microsoft Visual Studio&reg; 2005
    as well as Perl. (The Rotor development team 
currently uses ActivePerl 5.8.7.813,
    from <a href="http://www.activestate.com">
ActiveState</a>, but <a href="http://www.perl.org">perl.org</a> is always a good 
bet as well.)</p>
<p>As far as hardware goes, we really recommend having 512M of memory in your 
computer. While we've heard of success in building on machines with less, it can 
be mighty slow (and the swap thrashing can be horrific). As far as disk space goes, 100 megabytes should be sufficient if all you 
will be doing is viewing the source, but if you are doing active development 
(especially running the test suites) you will need at least a gigabyte of free 
disk space.</p>
<p>Please note that the Rotor distribution was only tested on operating systems 
using English locales.</p>
<h4>Summary of System Requirements</h4>
<p>Windows</p>
<ul>
  <li>We've tested the distribution on Windows XP and Windows 2000. We recommend 
  Windows XP.</li>
  <li>Microsoft Visual Studio 2005 Standard edition or above installed.&nbsp; You must, at a minimum, install the 
  Microsoft Visual C++ 2005 product.</li>
  <li>Perl installed and in the path.</li>
  <li>256 MB of memory (suggested minimum).</li>
  <li>100 MB of free disk space to expand the archive.</li>
  <li>One gigabyte of free disk space to build the distribution.</li>
    <li>Tk installed if you want to run all the samples. &nbsp;&nbsp;</li>
</ul>
<p>For more information you might want to peruse the documentation
<a href="docs/index.html">index</a> for more links into the documentation set.&nbsp; 
We recommend that you also have either Visual Studio 2005 or the .NET Frameworks 
SDK as secondary documentation to the ECMA specifications.</p>
<h2><a name="BuildingandRunningCode"></a>Building and Running Code</h2>
<p>We've included a detailed document about
<a href="docs/buildtools/building_sscli.html">building Rotor</a>, but if you are 
impatient, here are very brief instructions to get you up and running quickly.&nbsp;
</p>
<p><b><u>On Windows</u></b>: Once you have extracted the contents of the 
tarball using your favorite archiving utility, open a command window and run the
<code>env.bat</code> script from the sscli20 (root) directory of the distribution. 
You need to run the script from this directory because it uses the current 
directory to set up subsequent environment variables.&nbsp; After this, in the 
same window, type <code>buildall</code>, which will initiate the build process. 
In order to be useful on multiple platforms and systems, text files in the archive are 
linefeed terminated.&nbsp; If you are running Windows, you'll want to view these 
files in an editor that handles this case automatically (many do, including 
WordPad and the Visual Studio editor), or else use a utility program to remove 
the convert the linefeeds to Windows-style carriage-return/linefeed termination.
</p>
<p>Once the build has successfully finished, you should be able to compile and 
execute the simple &quot;hello world&quot; test program by changing to the samples\hello 
directory (samples/hello on UNIX systems based platforms), and then typing: </p>
<pre>csc hello.cs
clix hello.exe
</pre>
<p>This will churn for a while (loading takes less time on the free build), and 
then print out &quot;Hello World!&quot;&nbsp; The program <a href="docs/tools/clix.html">
clix</a> is a program loader for managed executables. The first line uses the C# 
compiler to produce hello.exe from hello.cs, a tiny program that prints &quot;Hello 
World!&quot; to the system console.</p>
<p></p>
<p>Assuming that hello.exe works, you are now able to compile C# sources using
<a href="docs/compilers/csharp.html">csc</a> (the C# compiler), and JScript 
sources using the <a href="docs/compilers/jsc.html">jsc</a> compiler. Remember 
to always run Rotor 2.0 programs in a shell that has been set up using the
<a href="docs/buildtools/env.html">env</a> scripts as described above. Also 
remember that managed executables need to be launched using clix in order to run 
under Rotor.&nbsp; For example, the JScript compiler must be run in this way.
</p>
<p>You are almost certain to find that the <a href="docs/map.html">map of the 
source code</a> to very useful in navigating around the distribution. The 
document on <a href="docs/buildtools/building_sscli.html">building rotor</a> 
will also be very helpful if you are modifying code; its scenario-based 
descriptions can be time-saving. </p>
<h2><a name="TestingRotor"></a>Testing Rotor</h2>
<p>Rotor comes with a number of test suites covering various aspects of its 
implementation: </p>
<p></p>
<ul>
  <li> The <a href="tests/palsuite">PAL Test Suite</a>: This test suite and its 
  test driver was developed to be a quality suite for the Platform Adaptation 
  Layer on UNIX systems based platforms. It can be used to smoke out bugs in your PAL modifications, 
  and will run against either the Windows PAL or the FreeBSD PAL.</li>
  <li>The <a href="tests/bvt">Base Verification Tests</a> (BVT) and the
  <a href="tests/il_bvt">IL BVTs</a>: These tests and their driver (rrun.pl) are 
  used to confirm basic CLI functionality. They are used as check-in test suites 
  by the development team.&nbsp; Use them whenever you want to test a change.</li>
  <li>The <a href="tests/security/verifier">Verifier Tests</a>: This collections 
  of tests is used to check JIT verification. Use them if you are modifying the 
  JIT process or IL.</li>
  <li>The <a href="tests/bcl">Base Class Library</a> (BCL) Tests: Use these 
  tests when making modifications to the base class libraries.</li>
</ul>
<p>For more information refer to the <a href="docs/testing_overview.html">
testing_overview.html</a> document in the sscli/docs directory.</p>
<p></p>
<h2><a name="security"></a>A Note About Security</h2>
<p>The Shared Source CLI runtime is not intended for use as a secure 
environment, although its source code does provide a very good example of how a 
secure execution environment might be built. By default, strongname verification 
is turned off for several important public keys - see the
<a href="docs/relnotes.html">release notes</a> for details as to how strongnames 
work in this distribution. </p>
<p>The implementation of Rotor's global assembly cache and strongname 
verification system is completely separate from the implementation used by the 
commercial Microsoft .NET Framework, and because of this, there should be no 
interaction between the two. Turning off verification in Rotor will not impact 
the Microsoft .NET Framework on Windows in any way. </p>
<h2><a name="licenses"></a>Yet More on Licensing</h2>
<p>There are a small number of files in this distribution that carry their own 
licenses which are compatible with the Microsoft Shared Source CLI, C#, and 
JScript License. Anyone building modified versions of this code should be aware 
of and comply with these license terms. </p>
    
        <h2><a name="DocumentationStyle"></a>A Comment on Documentation Style</h2>
    
    <p>
        To prevent repetativeness (and less typing on the authors behalf), we have used
        the word SSCLI to mean SSCLI 2.0 throughout the documentation. SSCLI v1 will
        be used to make explicit reference to the original release of Rotor, the SSCLI Version
        1.0.</p>
<h2>HAVE FUN!</h2>
<hr>
<p><i>Copyright (c) 2006 Microsoft Corporation. All rights reserved.</i></p>

</body>

</html>