CoreCLR Deployment and Usage Guide

1. Prerequisites

Note: This repository is archived and development has moved to dotnet/runtime. The following guide is for historical reference.

• Operating System: Windows, Linux, or macOS
• Tools: Git, CMake, Python 3.6+
• Build Dependencies:
  • Windows: Visual Studio 2019 or later with C++ development tools
  • Linux: GCC or Clang, make
  • macOS: Xcode command line tools
• Runtime: .NET Core SDK 3.1 or later (for building and testing)

2. Installation

Since this repository is archived, you should use the new location:

# Clone the new repository
git clone https://github.com/dotnet/runtime.git
cd runtime

# Checkout CoreCLR specific code
# CoreCLR is located in src/coreclr directory

Historical Installation (for reference only):

# Clone the archived repository
git clone https://github.com/dotnet/coreclr.git
cd coreclr

# Initialize submodules
git submodule update --init --recursive

3. Configuration

Environment Variables:

• CORECLR_SERVER_GC: Set to 1 for server GC mode (default is workstation GC)
• COMPlus_GCName: Specify GC flavor (e.g., "svr", "wks")
• CORE_ROOT: Path to the directory containing coreclr binaries

Configuration Files:

• src/coreclr/pal/prebuilt/inc/pal_mstypes.h: Platform-specific type definitions
• src/coreclr/pal/prebuilt/inc/pal_xxx.h: Platform abstraction layer headers

4. Build & Run

Building CoreCLR:

# From the runtime repository root
cd src/coreclr

# Windows (using Visual Studio)
.\build.cmd x64 Release

# Linux/macOS
./build.sh x64 Release

Running Tests:

# Run the test suite
cd src/tests
./run.sh -arch x64 -configuration Release

Development Workflow:

# Build and run a specific test
cd src/tests
./run.sh -arch x64 -configuration Debug -test "TestName"

5. Deployment

Note: CoreCLR is a runtime component, not a standalone application. It's typically deployed as part of .NET Core applications.

Deployment Scenarios:

1. Self-contained Deployment:

   # Publish your .NET Core app with CoreCLR included
   dotnet publish -c Release -r linux-x64 --self-contained true
   

2. Framework-dependent Deployment:

   # Publish app assuming CoreCLR is installed on target system
   dotnet publish -c Release
   

3. Docker Deployment:

   # Use official .NET Core runtime image
   FROM mcr.microsoft.com/dotnet/runtime:3.1
   COPY bin/Release/netcoreapp3.1/publish/ App/
   WORKDIR /App
   ENTRYPOINT ["dotnet", "YourApp.dll"]
   

6. Troubleshooting

Common Issues and Solutions:

1. Build Failures on Windows:

   Error: Unable to find MSBuild
   Solution: Ensure Visual Studio 2019 or later is installed with C++ development tools
   

2. Missing Dependencies on Linux:

   Error: libunwind not found
   Solution: Install required libraries
   sudo apt-get install libunwind8 libunwind8-dev
   

3. Test Failures:

   Error: TestHost not found
   Solution: Ensure CORE_ROOT environment variable points to correct directory
   export CORE_ROOT=/path/to/coreclr/bin/x64/Release
   

4. Performance Issues:

   Problem: High memory usage
   Solution: Adjust GC settings
   export COMPlus_GCName=svr
   export COMPlus_GCHeapHardLimit=8589934592 # 8GB limit
   

5. Cross-compilation Issues:

   Error: Cannot compile for target architecture
   Solution: Ensure cross-compilation tools are installed
   # For ARM64 on x64
   sudo apt-get install g++-aarch64-linux-gnu
   

Additional Resources:

• dotnet/runtime repository
• CoreCLR Documentation
• Building .NET Core