DOCSEARCHbyAlgolia
Submit Docs

microsoft/xlang

repository·master·Indexed 21 days ago

https://github.com/microsoft/xlang

A hub for tools and infrastructure that enable Windows application development across C++, C#, Rust, and Python. xlang provides metadata processing and API projection for WinRT, Win32, and COM, supporting specialized projects such as C++/WinRT, C#/WinRT, Rust for Windows, and Python/WinRT.

Tokens
37.9K
Snippets
71
Records
171
Agent score
75%

What's inside xlang

  1. Overview of xlang tools and ecosystem

    master

    xlang is a central hub for a constellation of tools designed to enable Windows application development across multiple programming languages. It provides infrastructure for processing metadata and accessing Windows APIs (WinRT, Win32, and COM) from various languages.

    While this repository contains core infrastructure and basic metadata handling, language-specific tooling is primarily maintained in dedicated repositories. Use this repository to track issues that span multiple languages or relate to fundamental metadata processing.

  3. Enable Undocked RegFree WinRT for non-packaged desktop applications

    master

    Undocked RegFree WinRT allows non-packaged desktop applications to leverage user-defined Windows Runtime (WinRT) types via application manifests. This is particularly useful for supporting Windows versions as old as Windows 8.1.

    The package uses the detours library to intercept RoActivateInstance, RoGetActivationFactory, RoGetMetadataFile, and RoResolveNamespace, reimplementing the RegFree WinRT feature that is natively available in Windows 10 (19h1) and above.

    When using the package, winrtact.dll is automatically placed in your build folder alongside your executable.

  4. Use Microsoft.Windows.UndockedRegFreeWinrt to consume WinRT classes registry-free

    master

    The Microsoft.Windows.UndockedRegFreeWinrt NuGet package allows non-packaged desktop applications to use user-defined Windows Runtime (WinRT) types via an application manifest. This is useful for enabling registry-free WinRT activation on older versions of Windows or providing a fallback mechanism.

    How it works

    The package uses the Detours library to detour several WinRT activation functions:

    • RoActivateInstance
    • RoGetActivationFactory
    • RoGetMetadataFile
    • RoResolveNamespace

    It reimplements the RegFree WinRT feature available in Windows 10 (19h1 and above). The package automatically places winrtact.dll in your build folder next to your executable.

    Initialization

    • Native (C++): Initialization is handled automatically via ForceSymbolReferences.
    • Managed (C#): You must manually initialize the detours and load the catalog by calling Microsoft.Windows.UndockedRegFreeWinrt.Initialize();.
    // Managed (C#) initialization
Microsoft.Windows.UndockedRegFreeWinrt.Initialize();

  5. Use the ABI/WinRT language projection

    master

    The ABI/WinRT language projection is a tool that generates header files for consuming WinRT APIs, similar to headers generated from COM .idl files.

    Warning: This tool is intended for legacy codebases. For new development, C++ developers should use cppwinrt instead, as it supports standard C++ and modern language features.

  6. What is a Language Projection?

    master

    A language projection is the mechanism that bridges the gap between a high-level programming language and the xlang Application Binary Interface (ABI).

    • On the caller side: It converts familiar language constructs into calls that conform to the ABI's machine register and stack layout.
    • On the callee side: It converts ABI-compliant calls into calls tailored to the implementation language.

    Example: When calling a C++ implementation from C#, the projection handles the conversion so that a C# System.String is received by the C++ code as a std::string_view.

  7. Overview of xlang Platform Adaptation Layer (/Platform)

    master

    The /platform folder contains the declaration and implementations of the common and minimal C API used to support xlang across different platforms. This is known as the PAL (Platform Adaptation Layer).

    • published/pal.h: Contains the declaration of the PAL surface area.

    Currently, the PAL primarily provides a Windows implementation, with plans to expand to Linux, Android, etc.

  8. What is the Xlang Platform Abstraction Layer (PAL)?

    master

    The Platform Abstraction Layer (PAL) provides language-agnostic functionality required by Xlang language projections. It manages critical tasks such as activating types, allocating shared cross-module memory, and handling strings.

    Because different language projections (C++, C#, Rust, Python, etc.) may use different allocators or runtime heaps, the PAL acts as a centralized, single module to ensure consistent memory management and interop. The C language binding serves as the lingua franca for the ABI underpinning all projections. Note that the PAL currently only supports intra-process shared memory; it does not provide guarantees for cross-process shared memory.

  9. Compare objects for equality

    master

    There are two ways to handle equality in the xlang ABI:

    1. Reference Equality: Since all xlang objects implement IUnknown, you can compare if two references point to the same object by calling QueryInterface on both to get their IUnknown pointers and checking if the resulting pointer values are identical.
    2. Value Equality: IXlangObject provides an Equals(IXlangObject* object) method. This can be used by the type system to implement specific logic for comparing the actual values held by objects.

  10. How xlang achieves language interoperability

    master

    xlang enables components written in one language to be called from another using object-oriented programming constructs. It achieves this by using a combination of four key pillars:

    1. API Metadata: Machine-readable descriptions of interfaces (in ECMA-335 format) that define how APIs are called and how they version/depend on other components.
    2. Application Binary Interface (ABI): A language-agnostic specification of machine state (registers, stack layout, calling conventions, and ownership semantics) used to transfer control between caller and callee.
    3. Language Projections: Translation layers that convert language-specific types and calls into ABI-compliant calls. For example, a C# System.String can be projected to a C++ std::string_view.
    4. Platform Adaptation Layer (Runtime): A shared runtime exposed via flat C APIs that handles system-dependent operations like thread management, object activation, error origination, and cross-language string representation.

    This architecture allows bidirectional control and data flow among any number of programming languages within a single process.

  11. Understand Xlang Runtime Classes and Interfaces

    master

    In Xlang, a Runtime Class is a central entity that must implement one or more interfaces. Unlike traditional OO languages, a class cannot define its own methods, properties, or events directly; instead, it must provide implementations for all members of the interfaces it implements.

    Key Constraints

    • No Direct Members: All functionality must come from interfaces.
    • Visibility: Runtime classes must have public visibility.
    • No Parameterization: Runtime classes cannot be parameterized, though they can implement a specific instance of a parameterized interface (where all type parameters are specified).
    • Interface Exclusivity: A class can only implement interfaces that are either non-exclusive or exclusive to that specific runtime class.
    • Mandatory Interfaces: A class must implement at least one Member Interface or Static Interface to be valid.

  12. The four-phase progression of Design Notes

    master

    While not every project requires all four phases, design notes for a particular topic often follow a natural progression:

    1. Principles and Axioms: Outlines objectives and design axioms (e.g., "our networking stack will provide the simplest TCP/IP implementation to ensure ease of understanding").
    2. Architecture and Abstractions: Describes key abstractions and interfaces (e.g., "the networking stack will be layered with no back-door interfaces between MAC, IP, and TCP").
    3. Implementation: Describes the core implementation details (e.g., "our TCP layer is divided into four classes...").
    4. Usage: Describes how to use the resulting code (e.g., "to install our TCP/IP stack on your system...").

    When to use which phases:

    • If a detail impacts many people, it likely needs a design note.
    • Many projects only require Principles/Axioms and Architecture/Abstractions notes, as implementation details can be understood directly from the code.
    • Tools like interface compilers may require Principles/Axioms and Usage notes, as they are used by many but modified by few.