mirror of
https://github.com/SSCLI/sscli_20021101
synced 2026-06-08 12:28:57 +00:00
yallie
269 lines
15 KiB
HTML
269 lines
15 KiB
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 1.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>
|
|
</ul>
|
|
<h2><a name="WhatsNew"></a>What's New in the
|
|
Microsoft Shared Source CLI 1.0 Release?</h2>
|
|
<ul>
|
|
<li>The Shared Source CLI now builds and runs on Mac® OS X.</li>
|
|
<li>A wealth of new samples have been added in the <a href="samples">samples
|
|
directory</a>.</li>
|
|
<li>Additional documentation and tutorials have been added. </li>
|
|
<li>A number of improvements have been added to the Platform Adaptation Layer
|
|
(PAL).</li>
|
|
<li>The just-in-time (JIT) compilation system has been restructured and improved to support the Mac OS X port.</li>
|
|
<li>A wealth of new test cases have been added for the JScript language, cordbg, and the garbage collector (GC).</li>
|
|
<li>Numerous bug fixes.</li>
|
|
</ul>
|
|
<h2><a name="Intro"></a>What is the Microsoft Shared Source CLI?</h2>
|
|
</a>
|
|
<p>The Microsoft® Shared Source CLI 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 on FreeBSD,
|
|
|
|
Mac OS X, and Microsoft® Windows. (There are instructions on how to do this, as
|
|
well as hardware requirements, below.) 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 copy of the Shared Source CLI 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. 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/sharedsource">
|
|
www.microsoft.com/licensing/sharedsource</a> or search
|
|
<a href="http://www.microsoft.com/">www.microsoft.com</a> for "Shared Source".</p>
|
|
<p>This is the third release of the Shared Source CLI, and it is for
|
|
non-commercial, experimental use only. Microsoft will be updating this distribution
|
|
periodically. 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>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. If you want maximum
|
|
source debugging support you should choose a checked build which will turn off
|
|
optimizations and allow better source-level debugging. 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. Why? Well, you'll find
|
|
the following definitions for the word: </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</a>,
|
|
<a href="http://www.freebsd.org">FreeBSD</a>, and
|
|
<a href="http://www.apple.com/macosx/">Mac OS X</a>. If you want to build and run
|
|
the source code, you'll need some additional software depending upon your OS.
|
|
The Rotor build process uses Perl in several ways, both to run the test harness
|
|
and as a way to autogenerate some utility code. On Windows you will need
|
|
Microsoft Visual Studio® .NET as well as Perl. (The Rotor development team
|
|
currently uses ActivePerl 5.6.1.630, 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.) On FreeBSD, the only thing that you will need in addition to a
|
|
FreeBSD developer distribution is Perl. (We are currently using 5.005_03).
|
|
There are several samples that uses the Tk 8.4.0 widget set; if you choose to
|
|
build this, Tk is available from <a href="http://www.scriptics.com">
|
|
www.scriptics.com</a>. </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) Truth be told, using the
|
|
Windows compilers, 256M seems to work pretty well, but gcc seems to use more
|
|
resources and you'll see more performance degradation on FreeBSD and Mac OS X because of
|
|
this. 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. There are known problems with attempting to build
|
|
and execute Rotor on other locales. If you avoid using locale-specific
|
|
characters in the path to the source code, you may be able to use Rotor on
|
|
operating systems using other 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 .NET installed. You must, at a minimum, install the
|
|
Microsoft Visual C++ .NET product.</li>
|
|
<li>Perl installed and in the path.</li>
|
|
<li>Tk installed if you want to run all the samples.</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>
|
|
</ul>
|
|
<p>FreeBSD</p>
|
|
<ul>
|
|
<li>We have tested the distribution on FreeBSD 4.5, 4.6, and 4.7. We recommend
|
|
FreeBSD 4.7. </li>
|
|
<li>Developer distribution (which will include the gcc compiler and other
|
|
build tools)</li>
|
|
<li>Tk package installed if you want to run all the samples.</li>
|
|
<li>512 MB of memory.
|
|
<ul>
|
|
<li>If you do choose to use less memory then make sure your swap space is at
|
|
least four times your memory size.</li>
|
|
</ul>
|
|
</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>
|
|
</ul>
|
|
<p>Mac OS X</p>
|
|
<ul>
|
|
<li>Mac OS X 10.2.</li>
|
|
<li>Apple Developer Tools.</li>
|
|
<li>Tk package installed if you want to run all the samples.</li>
|
|
<li>256 MB of memory: 512 MB recommended.</li>
|
|
<li>Ensure the BSD subsystem is installed. (This is the default
|
|
installation.)</li>
|
|
<li>Stuffit™ Expander 7.0 will unpack the archive. Otherwise use gnutar and
|
|
not the default tar.</li>
|
|
<li>One gigabyte of free disk space to build the distribution.</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.
|
|
We recommend that you also have either Visual Studio .NET 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.
|
|
</p>
|
|
<p><b><u>On FreeBSD</u></b>: Once you have extracted the contents of the
|
|
tarball (<code>tar xvfz</code> will work), you should <code>source</code> the
|
|
contents of either <code>env.sh</code> or of <code>env.csh</code> in the root of
|
|
the distribution, depending upon which shell you are using. For example, in csh
|
|
you might type the following command: <code>source env.csh</code> Once this
|
|
script has run, type <code>./buildall</code> in the same instance of the shell,
|
|
which will initiate the build process. </p>
|
|
<p><b><u>On </u></b><u><b>Mac OS X</b></u>: Once you have extracted the contents of the
|
|
tarball (StuffIt 7.0 or gnutar), in a console window you should <code>source</code> the
|
|
contents of either <code>env.sh</code> or of <code>env.csh</code> in the root of
|
|
the distribution, depending upon which shell you are using. For example, in csh
|
|
you might type the following command: <code>source env.csh</code> Once this
|
|
script has run, type <code>./buildall</code> in the same instance of the shell,
|
|
which will initiate the build process. </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 sscli (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. After this, in the
|
|
same window, type <code>buildall</code>, which will initiate the build process.
|
|
In order to be useful on both systems based on UNIX systems and Windows, text files in the archive are
|
|
linefeed terminated. 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 "hello world" 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 "Hello World!" 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 "Hello
|
|
World!" 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 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. 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. 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>HAVE FUN!</h2>
|
|
<hr>
|
|
<p><i>Copyright (c) 2002 Microsoft Corporation. All rights reserved.</i></p>
|
|
|
|
</body>
|
|
|
|
</html>
|
|
|
|
</body>
|
|
|
|
</html> |