From bbae4542478a79a2607e01a8aaa491f70832b4fa Mon Sep 17 00:00:00 2001 From: Mike Battista <13860912+mikebattista@users.noreply.github.com> Date: Wed, 2 Dec 2020 18:05:06 -0800 Subject: [PATCH] Added docs dedicated to projections. --- README.md | 2 +- docs/faq.md | 2 +- docs/projections.md | 15 +++++++++++++++ 3 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 docs/projections.md diff --git a/README.md b/README.md index 0612d281..9b5d684e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Historically, this has required manually [redefining the APIs](http://pinvoke.ne This project aims to provide metadata for Win32 APIs such that idiomatic projections and projects like the ones above can be generated for all languages and frameworks in a more automated way and with more complete API coverage. -See the [roadmap](./docs/roadmap.md) and [FAQ](./docs/faq.md) for more details. +See the [roadmap](./docs/roadmap.md) and [FAQ](./docs/faq.md) for more details and [projections](./docs/projections.md) for how to consume Win32 APIs from various languages. # Architecture diff --git a/docs/faq.md b/docs/faq.md index 0ad57bff..cfe47963 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -4,7 +4,7 @@ A. Producing metadata for Win32 APIs enables programmatic generation of language projections with maximum API coverage and minimal maintenance. Language projections produced from this metadata will make Win32 APIs more accessible from more languages with improved API coverage and a better developer experience. **Q. How do I use the metadata to call Win32 APIs from my preferred language?**
-A. Most developers will not consume the metadata directly and will instead use language projections that themselves consume the metadata and project the APIs into the idiomatic patterns of the languages. We intend to support [C#](https://github.com/microsoft/CsWin32), C++, and Rust projections initially with plans to coordinate with the community to support additional language projections based on demand. Language projections will be developed independently of the metadata tooling and will live in their own repos. +A. Most developers will not consume the metadata directly and will instead use [language projections](projections.md) that themselves consume the metadata and project the APIs into the idiomatic patterns of the languages. We intend to support [C#](https://github.com/microsoft/CsWin32), C++, and Rust projections initially with plans to coordinate with the community to support additional language projections based on demand. Language projections will be developed independently of the metadata tooling and will live in their own repos. **Q. Can .NET code reference the metadata binary and call its APIs directly?**
A. No. While the metadata binary is compiled based on the ECMA-335 spec, it does not contain the same attributes that the .NET runtime requires to successfully P/Invoke into the functions exported by Windows. .NET code should use an appropriate language projection like [C#/Win32](https://github.com/microsoft/CsWin32). diff --git a/docs/projections.md b/docs/projections.md new file mode 100644 index 00000000..c0987769 --- /dev/null +++ b/docs/projections.md @@ -0,0 +1,15 @@ +# Projections + +Language projections built on top of Win32 metadata are what developers should use to call Win32 APIs from various languages. + +## Principles + +Below are some principles that all language projections should follow: + +* Language projections should provide maximum API coverage +* Language projections should provide friendly adaptations of APIs and types where appropriate +* Language projections should provide Intellisense sourced from official documentation +* Language projections should enable developers to target a specific set of APIs and link or include only the artifacts necessary to provide support for those APIs + +## Projections +* C# - https://github.com/microsoft/CsWin32 \ No newline at end of file