-
Notifications
You must be signed in to change notification settings - Fork 104
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Repo source code directory restructure (#558)
* authoring, samples, tests reorg * update paths * update structure and move structure/usage to docs * move nuget spec to docs * update sln * move back nuget readme, move nuget to root and update structure.md * update path to nuget readme * fix package path * fix readme usage/structure paths * update authoring shim path * merge conflict build.cmd
- Loading branch information
1 parent
2a0058e
commit cfbc973
Showing
274 changed files
with
12,112 additions
and
12,087 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes
File renamed without changes
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,45 +1,55 @@ | ||
| # Repository Structure | ||
|
|
||
| ## The [`cswinrt`](/cswinrt) folder | ||
|
|
||
| Contains the sources and cswinrt.vcxproj project file for building the C#/WinRT compiler, cswinrt.exe. The projection's base library is contained in /cswinrt/strings/WinRT.cs, which is processed by /strings.props to generate string literals contained in the compiler. | ||
|
|
||
| The compiler uses the [WinMD NuGet package](http://aka.ms/winmd/nuget) for parsing [ECMA-335 metadata](http://www.ecma-international.org/publications/standards/Ecma-335.htm) files. The WinMD github repo includes a [winmd.natvis](https://github.com/microsoft/winmd/blob/master/vs/winmd.natvis) script for debugging metadata parsing. A symlink can be used to install the script: | ||
| > for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\winmd.natvis" "c:\git\winmd\vs\winmd.natvis" | ||
| The C#/WinRT project also contains a cswinrt.natvis script for debugging the C# projection writing, which can also be installed with a symlink: | ||
| > for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\cswinrt.natvis" "c:\git\cswinrt\cswinrt\cswinrt.natvis" | ||
| See also [Deploying .natvis files](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2015#BKMK_natvis_location). | ||
|
|
||
| ## The [`WinRT.Runtime`](/WinRT.Runtime) folder | ||
|
|
||
| Contains the WinRT.Runtime project for building the C#/WinRT runtime assembly, winrt.runtime.dll. There are two versions of this assembly, providing an abstraction layer over both .NET Standard 2.0 and .NET 5 runtimes. While all code generated by cswinrt.exe is compatible with .NET Standard 2.0, there are runtime differences which must be addressed. The primary difference is that the .NET 5 winrt.runtime.dll provides Xaml reference tracking support, which is necessary for WinUI 3 applications to manage memory correctly. Future performance enhancements, such as function pointer support, may also be limited to the .NET 5 winrt.runtime.dll. | ||
|
|
||
| ## The [`nuget`](/nuget) folder | ||
|
|
||
| Contains source files for producing a C#/WinRT NuGet package, which is regularly built, signed, and published to nuget.org by Microsoft. The C#/WinRT NuGet package contains the cswinrt.exe compiler, and both versions of the winrt.runtime.dll. | ||
|
|
||
| ## [`TestWinRT`](https://github.com/microsoft/TestWinRT/) | ||
|
|
||
| C#/WinRT makes use of the standalone [TestWinRT](https://github.com/microsoft/TestWinRT/) repository for general language projection test coverage. This repo should be cloned into the root of the C#/WinRT repo, via **get_testwinrt.cmd**, so that the cswinrt.sln can resolve its reference to TestComponent.vcxproj. The resulting TestComponent.dll and TestComponent.winmd files are consumed by the UnitTest project above. | ||
|
|
||
| ## The [`TestComponentCSharp`](/TestComponentCSharp) folder | ||
|
|
||
| Contains an implementation of a WinRT test component, defined in class.idl and used by the UnitTest project. To complement the general TestComponent above, the TestComponentCSharp tests scenarios specific to the C#/WinRT language projection. | ||
|
|
||
| ## The [`Projections`](/Projections) folder | ||
|
|
||
| Contains several projects for generating and building projections from the Windows SDK, WinUI, Benchmark (produced by the BenchmarkComponent project), and Test metadata (produced by the TestWinRT and TestComponentCSharp projects). | ||
|
|
||
| ## The [`UnitTest`](/UnitTest) folder | ||
|
|
||
| Contains unit tests for validating the Windows SDK, WinUI, and Test projections generated above. All pull requests should ensure that this project executes without errors. | ||
|
|
||
| ## The [`Benchmarks`](/Benchmarks) folder | ||
|
|
||
| Contains benchmarks written using BenchmarkDotNet to track the performance of scenarios in the generated projection. To run the benchmarks using the CsWinRT projection, run **benchmark.cmd**. To run the same benchmarks using the built-in WinMD support in NET Core 3.1 to compare against as a baseline, run **benchmark_winmd.cmd**. | ||
|
|
||
| ## The [`WinUIDesktopSample`](/WinUIDesktopSample) folder | ||
|
|
||
| Contains an end-to-end sample app that uses the Windows SDK and WinUI projections generated above. | ||
| # Repository Structure | ||
|
|
||
| This document describes the CsWinRT repository organization. Documentation and specs are located in the [`/docs`](.) folder. All source code for CsWinRT is located in the [`/src`](../src) folder, and files for generating the NuGet package are located in [`/nuget`](../nuget). | ||
|
|
||
| ## [`nuget`](../nuget) | ||
|
|
||
| Contains source files for producing a C#/WinRT NuGet package, which is regularly built, signed, and published to nuget.org by Microsoft. The C#/WinRT NuGet package contains the cswinrt.exe compiler, and both versions of the winrt.runtime.dll. | ||
|
|
||
| ## [`src/Authoring`](../src/Authoring) | ||
|
|
||
| Contains projects for implementing authoring and hosting support. | ||
|
|
||
| ## [`src/Benchmarks`](../src/Benchmarks) | ||
|
|
||
| Contains benchmarks written using BenchmarkDotNet to track the performance of scenarios in the generated projection. To run the benchmarks using the CsWinRT projection, run **benchmark.cmd**. To run the same benchmarks using the built-in WinMD support in NET Core 3.1 to compare against as a baseline, run **benchmark_winmd.cmd**. | ||
|
|
||
| ## [`src/cswinrt`](../src/cswinrt) | ||
|
|
||
| Contains the sources and cswinrt.vcxproj project file for building the C#/WinRT compiler, cswinrt.exe. The projection's base library is contained in /cswinrt/strings/WinRT.cs, which is processed by /strings.props to generate string literals contained in the compiler. | ||
|
|
||
| The compiler uses the [WinMD NuGet package](http://aka.ms/winmd/nuget) for parsing [ECMA-335 metadata](http://www.ecma-international.org/publications/standards/Ecma-335.htm) files. The WinMD github repo includes a [winmd.natvis](https://github.com/microsoft/winmd/blob/master/vs/winmd.natvis) script for debugging metadata parsing. A symlink can be used to install the script: | ||
| > for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\winmd.natvis" "c:\git\winmd\vs\winmd.natvis" | ||
| The C#/WinRT project also contains a cswinrt.natvis script for debugging the C# projection writing, which can also be installed with a symlink: | ||
| > for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\cswinrt.natvis" "c:\git\cswinrt\cswinrt\cswinrt.natvis" | ||
| See also [Deploying .natvis files](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2015#BKMK_natvis_location). | ||
|
|
||
| ## [`src/Projections`](../src/Projections) | ||
|
|
||
| Contains several projects for generating and building projections from the Windows SDK, WinUI, Benchmark (produced by the BenchmarkComponent project), and Test metadata (produced by the TestWinRT and TestComponentCSharp projects). | ||
|
|
||
| ## [`src/Samples`](../src/Samples) | ||
|
|
||
| - [`Net5ProjectionSample`](../src/Samples/Net5ProjectionSample): Contains an end-to-end sample for component authors, showing how to generate a projection from a C++/WinRT component and consume it using a NuGet package. | ||
|
|
||
| - [`WinUIDesktopSample`](../src/Samples/WinUIDesktopSample): Contains an end-to-end sample app that uses the Windows SDK and WinUI projections generated above. | ||
|
|
||
| ## [`src/Tests`](../src/Tests) | ||
|
|
||
| Contains various testing-related projects: | ||
|
|
||
| - [`TestComponentCSharp`](../src/Tests/TestComponentCSharp): This is an implementation of a WinRT test component, defined in class.idl and used by the UnitTest project. To complement the general TestComponent above, the TestComponentCSharp tests scenarios specific to the C#/WinRT language projection. | ||
|
|
||
| - [`UnitTest`](../src/Tests/UnitTest): Unit tests for validating the Windows SDK, WinUI, and Test projections generated above. All pull requests should ensure that this project executes without errors. | ||
|
|
||
| - [`HostTest`](../src/Tests/HostTest): Unit tests for WinRT.Host.dll, which provides hosting for runtime components written in C#. | ||
|
|
||
| ## [`src/TestWinRT`](https://github.com/microsoft/TestWinRT/) | ||
|
|
||
| C#/WinRT makes use of the standalone [TestWinRT](https://github.com/microsoft/TestWinRT/) repository for general language projection test coverage. This repo is cloned via **get_testwinrt.cmd** into the `src` folder, so that the cswinrt.sln can resolve its reference to TestComponent.vcxproj. The resulting `TestComponent` and `BenchmarkComponent` files are consumed by the UnitTest and Benchmarks projects above. | ||
|
|
||
| ## [`src/WinRT.Runtime`](../src/WinRT.Runtime) | ||
|
|
||
| Contains the WinRT.Runtime project for building the C#/WinRT runtime assembly, winrt.runtime.dll. There are two versions of this assembly, providing an abstraction layer over both .NET Standard 2.0 and .NET 5 runtimes. While all code generated by cswinrt.exe is compatible with .NET Standard 2.0, there are runtime differences which must be addressed. The primary difference is that the .NET 5 winrt.runtime.dll provides Xaml reference tracking support, which is necessary for WinUI 3 applications to manage memory correctly. Future performance enhancements, such as function pointer support, may also be limited to the .NET 5 winrt.runtime.dll. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,21 +1,21 @@ | ||
| # Usage | ||
|
|
||
| ## Component Project | ||
|
|
||
| A component project adds a NuGet reference to C#/WinRT to invoke cswinrt.exe at build time, generate projection sources, and compile these into an interop assembly. For an example of this, see the [Projection Sample](https://github.com/microsoft/CsWinRT/tree/master/Samples/Net5ProjectionSample). Command line options can be displayed by running **cswinrt -?**. The interop assembly is then typically distributed as a NuGet package itself. | ||
|
|
||
| ### Example | ||
|
|
||
| To invoke cswinrt to generate projection sources for types in the **Contoso** namespace, you need to add the following property to your C# library project file. In this project you would also need to reference the CsWinRT NuGet package and the project-specific `winmd` files you want to project, whether through a NuGet package, project reference or direct reference. By default, the **Windows** and **Microsoft** namespaces are not projected. | ||
|
|
||
| ``` | ||
| <PropertyGroup> | ||
| <CsWinRTIncludes>Contoso</CsWinRTIncludes> | ||
| </PropertyGroup> | ||
| ``` | ||
|
|
||
| To further customize C#/WinRT behavior, refer to the [CsWinRT NuGet documentation](https://github.com/microsoft/CsWinRT/blob/master/nuget/readme.md). | ||
|
|
||
| ## Application Project | ||
|
|
||
| An application project adds NuGet references to both the component interop assembly produced above and to CsWinRT to include the `winrt.runtime.dll` assembly. If the interop assembly is distributed as a NuGet package itself, this package will require a dependency on C#/WinRT for .NET5 targets. If a third party WinRT component is distributed without an official interop assembly, an application project may add a reference to C#/WinRT to generate its own private component interop assembly. There are versioning concerns related to this scenario, so the preferred solution is for the third party to publish an interop assembly directly. | ||
| # Usage | ||
|
|
||
| ## Component Project | ||
|
|
||
| A component project adds a NuGet reference to C#/WinRT to invoke cswinrt.exe at build time, generate projection sources, and compile these into an interop assembly. For an example of this, see the [Projection Sample](https://github.com/microsoft/CsWinRT/tree/master/Samples/Net5ProjectionSample). Command line options can be displayed by running **cswinrt -?**. The interop assembly is then typically distributed as a NuGet package itself. | ||
|
|
||
| ### Example | ||
|
|
||
| To invoke cswinrt to generate projection sources for types in the **Contoso** namespace, you need to add the following property to your C# library project file. In this project you would also need to reference the CsWinRT NuGet package and the project-specific `winmd` files you want to project, whether through a NuGet package, project reference or direct reference. By default, the **Windows** and **Microsoft** namespaces are not projected. | ||
|
|
||
| ``` | ||
| <PropertyGroup> | ||
| <CsWinRTIncludes>Contoso</CsWinRTIncludes> | ||
| </PropertyGroup> | ||
| ``` | ||
|
|
||
| To further customize C#/WinRT behavior, refer to the [CsWinRT NuGet documentation](../nuget/readme.md). | ||
|
|
||
| ## Application Project | ||
|
|
||
| An application project adds NuGet references to both the component interop assembly produced above and to CsWinRT to include the `winrt.runtime.dll` assembly. If the interop assembly is distributed as a NuGet package itself, this package will require a dependency on C#/WinRT for .NET5 targets. If a third party WinRT component is distributed without an official interop assembly, an application project may add a reference to C#/WinRT to generate its own private component interop assembly. There are versioning concerns related to this scenario, so the preferred solution is for the third party to publish an interop assembly directly. |
Oops, something went wrong.