Polyfill

Used in this repository, a polyfill is when an interface provides a substitute implementation when the desired implementation is not present. For example – assume Project Reunion wants to expose Muffin objects that are first present in Windows 10 RS5 as a platform feature; when Project Reunion app is installed on Windows 10 RS3, Project Reunion provides its own implementation of the Muffin functionality which is close enough.

Language Projections

WinRT is based on Component Object Models (COM) and is designed to be accessed through language projections. A language projection hides the details of COM and provides a more natural programming experience for a given language.

A developer of certain functionality expresses the shape of the API in metadata and then implements the functionality in a binary (typically a DLL). The API that is directly callable from the binary is called "Application Binary Interface" or ABI. It involves the actual invocation of an API in a native language such as C++. A language projection adapts the API into the syntax and semantics of a particular language, e.g. a property on a class that runs a particular type is written in ABI as:

HRESULT MyValue(int* value);

in this case, the "MyValue" property returns an integer and reports its success via HRESULT. This is an odd convention in most languages, which would normally like to call this API in the following manner (this is an example in C#):

var value = myClass.MyValue;

and throw an exception in case of an error condition. The re-shaping of the API call, in this case to its more natural form of the property being a direct return value and the translation of the error condition into an exception illustrates some of the essential jobs of a language projection. Other facilities may make the natural flow of asynchronous programming easier to write, often in the form of await or coroutines.

The Xlang open source project is building three language projections: C++ WinRT (cppwinrt), C# Winrt (cswint), and Rust/WinRT

UWP

Referenced throughout this repo, the term "UWP" references a Universal Windows Platform App - an app running inside an app container, at a lower privilege level, with package identity, delivered via an MSIX. This app's lifecycle from activation through termination is controlled by the platform for best power and resource usage. Its access to the user's resources are gated by a Request model so the user is in control. Windows and views created by the app are positioned by the OS shell. Its UX is either drawn using XAML or Composition objects or a framework that produces XAML or Composition objects.

Framework Packages

Framework packages are ways for apps to share code from a common source, rather than carrying it with themselves. Apps just need to reference the framework package in their manifest. A user's device needs only to carry one Project Reunion Framework package and many apps can reference it. Framework packages are updated faster than apps are e.g. When WinUI ships a new version of their framework package all three apps magically get the new version without themselves having to update (or know how to update some shared copy.) This is much better for security & reliability fixes as well.

The code in a framework package is treated as if it were included in the application package. The framework package can carry DLL's and API definitions (COM & WinRT registrations) but it does not assert any capabilities or privileges. Since it runs in the context of the application, it inherits the capabilities and restrictions of the application that loaded it. When an application references a framework package, the loader will search the framework package as part of the loader's normal search order. Framework packages can also carry their own resources and MRT will discover those resources. Since resources in a framework package share identifier namespace with the application, a convention is to include the framework package name as part of the resource name.