Building the Shared Source CLI 2.0 and C# 2.0 Source Tree

Contents

• QuickStart
• Build option changes in SSCLI 2.0
• Overview of the Shared Source CLI 2.0 Build Process
• Shared Source CLI 2.0 Build Details and Scenarios
  • Primary Bootstrap
  • Secondary Bootstrap
  • Shared Source CLI Core CLI, C# Compiler, Base Class Libraries, and Supporting Tools
  • FX Class Libraries
  • Managed Class Libraries
  • Managed Compilers
• Using Build Logs to Troubleshoot Build Problems
• Notes, Hints, and Tips
  • Autogenerated Files
  • Faster Rebuilds
  • File Preprocessing

QuickStart

The following steps represent the quickest and most reliable way to build the Microsoft® Shared Source CLI 2.0 (SSCLI) implementation:

On the Microsoft® Windows® operating system:

1. Change directories into the root of the SSCLI source tree.
2. Run the env.bat batch file.
3. Run the buildall.cmd batch file.

Build option changes in SSCLI 2.0

There are a few major changes to the buildall arguments to specify a SSCLI build flavor. The table below specifies the old SSCLI version 1.0 options and what they correspond to in SSCLI version 2.0.

SSCLI 1.0 Build Option	Corresponding SSCLI 2.0 Build Option
checked	debug
fastchecked	checked
free	free

Overview of the Shared Source CLI  2.0 (SSCLI) Build Process

The SSCLI build process is designed in a modular manner.  You can build all of the SSCLI or only parts of the SSCLI; however, there are strict sequential dependencies between elements of the source tree.  In all cases, the build process requires that your environment variables be set correctly before building. For more information on correctly configuring your environment prior to building, see env.html.

Note that the path to and directory name of the location where the SSCLI is installed cannot contain spaces. Some tools that the build process depends on do not work correctly on paths containing spaces.

Elements of the SSCLI implementation depend on other elements in a strict sequential order. The best way to start modifying elements of the source tree is to build the entire tree using the buildall batch file or script that will build the required dependencies in the correct order and have them available in the path. After that it is possible to selectively rebuild specific elements of the source tree.

The SSCLI 2.0 source tree has the following major elements:

1. Primary bootstrap elements: the PAL and unmanaged bootstrap build tools.
2. Secondary bootstrap elements: the remaining tools and support infrastructure.
3. The core CLI implementation, base class libraries, the C# compiler, and supporting tools.
4. The FX class libraries and supporting tools.
5. Other assemblies.
6. Managed compilers.

In general each major element depends on the preceding element having been built and the output of the build in the path. There are more complicated dependencies within each of the major elements.  The dependency order of the major elements can be determined by reading buildall.bat or the buildall script. Dependency orders within large elements such as the CLI, C#, and base class libraries or the FX class libraries can be determined by reading the order of the files in the dirs file at the root of the relevant source tree. 

SSCLI 2.0 Build Details and Scenarios

You should always use buildall.cmd or the buildall script to build the entire source tree before attempting to work with separate elements. The scenarios below describe the necessary procedures for modifying and building specific portions of the SSCLI source tree.

The SSCLI build process works off of relative path location. You must switch to the correct directory where the sources files or makefiles are and then execute the required command.

Available build options for the build utility are specified in buildutility.html.  Builds that use make.cmd support only the -c (clean) option to indicate that existing object files are to be deleted.

Primary Bootstrap

The primary bootstrap element of the SSCLI source tree uses makefiles during the initial build rather than the build utility, because this utility and the other supporting build tools have not been built yet.  On Windows, the build process uses make.cmd batch files which then invoke the Microsoft Program Maintenance Utility (nmake.exe provided in the path by Microsoft® Visual Studio® 2005) to process the required makefiles. 

The primary build bootstrap subelements are:

• The Platform Adaptation Layer (PAL). The PAL is used by build and other tools so it must be built first.
• The nmake makefile tool (the version built during the build process is only used on UNIX system-based platforms).
• The Build Output Manager tool.
• The build utility.

The PAL must be built before any other builds are attempted. 

Secondary Bootstrap

In the secondary bootstrap portion of the source tree it is assumed that the build tools are sufficiently complete to enable using them to build. This means that the build directives are specified in a sources file (see buildutility.html) and not in a makefile or make.cmd file.

Subelements of the primary bootstrap are:

• The resource compiler.
• The PAL runtime (PAL RT). The PAL RT supports some higher-level functionality shared across platforms by the SSCLI implementation and supporting tools.

For the following tools and the PAL RT, all the primary bootstrap utilities and the PAL must be built, functional, and in the path.

For all the following build scenarios the build commands are:

cd <source_location>

build [options]

For more details on the build utility options see buildutility.html.  The most common options are -c for clean build and -z to skip calculating dependencies.

SSCLI Core, C# Compiler, Base Class Libraries, and Supporting Tools

After the primary and secondary bootstrap elements are built, it is possible to proceed with building the core SSCLI implementation, C# compiler, and base class libraries.  This section of the build is very complex due to interdependencies between the core CLI code, C#, and the base class libraries.  When making changes across subelements of this tree, you should rebuild the entire tree starting at %ROTOR_DIR%\clr\src. 

Some critical subelements of this tree are:

• utilcode
  • Common shared C++ utility code.
• vm
  • A large portion of the CLI implementation.
• fusion
  • Assembly searching and binding.
• dlls
  • Unmanaged CLI support libraries.
• ilasm
  • The ilasm assembler tool.
• ildasm
  • The ildasm disassembly tool.
• fjit
  • The just-in-time (JIT) compiler implementation.
• tools
  • Supporting tools and utilities.
• bcl
  • The base class libraries.  These are the most fundamental managed code assemblies. .
• toolbox
  • Some additional managed tools.

FX Class Libraries

The FX class libraries provide basic runtime class library support.  Important sub-elements include:

• The System assembly.
• The System.Xml assembly.

To build the FX class libraries, switch to the source location directory and run the build utility.

Managed Class Libraries

Additional managed class libraries:

• System.Runtime.Serialization.Formatters.Soap assembly
• System.Runtime.Remoting assembly

To build the managed class libraries switch to the source location directory and run the build utility.

Managed Compilers

The Microsoft JScript® compiler is implemented as a managed application.  It also builds managed applications.

To build the managed compilers, switch to the source location directory and run the build utility.

Using Build Logs to Troubleshoot Build Problems

When you build the SSCLI, a large volume of information is sent to the console window during the build. Many people assume that this is important build log output but it is not the complete build log output and is useful mostly for the final summary content which indicates whether there were build errors or warnings. The build utility emits its useful information to build log files. 

Build log file names are annotated with the type of build and have an extension that indicates whether they contain error, warning, or general log information. Log file names are annotated to prevent build logs of one build type from overwriting the logs of another build type.  Subsequent build runs with the same build type will overwrite the previous log file.

Build log file names are annotated using the value of the BUILD_ALT_DIR environment variable.  The extension of the log file will be .log for the complete log output, .err for a build error output subset, and .wrn for a build warning output subset.

Build Log File Names

Build log files will be generated at the root directory where the build utility finds a dirs file and begins recursively building the source tree.  When you execute the buildall script or batch file several different builds are sequentially performed. 

If you explicitly switch to a directory and run build, log files will be generated in that directory. For the build utility to work you must be in a directory with either a dirs or sources file.

If you encounter an error during build, you should look for build error log files (such as buildc.err) to obtain more information.  However, the build error log files will often only contain incomplete error output resulting from a previous error that did not get sent to the error log file.  For example, many errors that occur when building managed code using the SSCLI C# compiler are not emitted correctly to the error log file.  For complete diagnostics you should read the full build log file.  This will show the initial build error that might have cascaded into subsequent output in the build error log file.

Notes, Hints, and Tips

Autogenerated Files

Note that some files in the SSCLI source tree are autogenerated before being placed in the SSCLI source tree, due to the requirement to interoperate with other build environments within Microsoft and the decision not to port some internal Microsoft tools to run on top of the SSCLI PAL.  For example:

• Some .h include files are generated by the Microsoft MIDL compiler from .idl files.  Only the .h files are included in the SSCLI source tree.
• Parseasm.cpp is generated by means of an internal YACC-like tool.  Only the resulting output file is included in the SSCLI source tree.
• All .nlp files are generated by internal Microsoft tools. Only the resulting .nlp output files are included.

Faster Rebuilds

If you want to do a quick rebuild after changing a C/C++ file, use:

build -z

The -z option skips recalculations of file dependencies.