Building the LeanCLR Runtime

This document describes how to build the LeanCLR runtime library from source.

Prerequisites

Required Tools

Tool	Minimum Version	Purpose
CMake	3.15+	Build system generator
C++ Compiler	C++17 support	Compilation
Visual Studio	2022 (v17)	Windows development (recommended)

Installing Prerequisites

CMake

Download and install from: https://cmake.org/download/

Verify installation:

cmake --version

Visual Studio 2022

Download from: https://visualstudio.microsoft.com/

Ensure the following workloads are installed:

• Desktop development with C++

Build Directory Structure

src/runtime/
├── CMakeLists.txt      # Main CMake configuration
├── build.bat           # Automated build script
├── generate-vs-sln.bat # VS solution generator
├── build/              # Build output directory
│   ├── Debug/          # Debug build output
│   └── Release/        # Release build output
└── [source directories]

Building on Windows

Option 1: Using build.bat (Recommended)

The build.bat script automates the entire build process.

Basic Usage

cd src/runtime
build.bat

This builds a Release x64 configuration by default.

Build Options

Option	Description
Debug	Build with debug symbols
Release	Build optimized release (default)
x86	Build for 32-bit Windows
x64	Build for 64-bit Windows (default)
clean	Clean build directory before building

Examples

# Debug build
build.bat Debug

# Release x86 build
build.bat Release x86

# Clean and rebuild
build.bat clean Release

# Debug x86 with clean
build.bat clean Debug x86

Option 2: Using Visual Studio

1. Generate the Visual Studio solution:

   cd src/runtime
   generate-vs-sln.bat
   

2. Open the generated solution:

   build\leanclr.sln
   

3. Select the desired configuration (Debug/Release) and platform (x64/Win32)

4. Build the solution (Ctrl+Shift+B)

Option 3: Manual CMake

cd src/runtime
mkdir build
cd build
cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release

Building for WebAssembly

For WebAssembly builds, see the lean-wasm sample project.

Quick Steps

1. Install Emscripten SDK:

   git clone https://github.com/emscripten-core/emsdk.git
   cd emsdk
   emsdk install latest
   emsdk activate latest
   

2. Activate environment:

   emsdk_env.bat
   

3. Build:

   cd src/samples/lean-wasm
   build-wasm.bat
   

Build Output

After a successful build, the output files are located at:

Windows

src/runtime/build/<Config>/leanclr.lib

Where <Config> is Debug or Release.

WebAssembly

src/samples/lean-wasm/build-wasm/bin/
├── lean.js
└── lean.wasm

CMake Configuration Options

The LeanCLR CMakeLists.txt provides the following configuration:

Setting	Value	Description
CXX_STANDARD	17	C++17 required
Library Type	STATIC	Builds as static library
Exceptions	Disabled	C++ exceptions disabled for smaller binary

Troubleshooting

Common Issues

1. CMake not found

   • Ensure CMake is installed and added to PATH
   • Restart terminal after installation

2. Visual Studio generator not found

   • Install Visual Studio 2022 with C++ workload
   • If using a different VS version, modify build.bat:

     set VS_VERSION=16 2019  # For VS 2019
     

3. Build fails with C++ standard errors

   • Ensure your compiler supports C++17
   • Update Visual Studio to latest version

4. Emscripten build fails

   • Ensure emsdk_env.bat was run in the current terminal
   • Verify Emscripten installation: emcc --version

Next Steps

After building the runtime, see Embedding LeanCLR to learn how to integrate it into your project.