From 2e2d7d3e6fe4944ee69d36cc8c47b158d549415c Mon Sep 17 00:00:00 2001 From: Andrei Borodin Date: Thu, 21 Nov 2019 13:05:30 -0800 Subject: [PATCH 1/5] Modified the verisons in the Readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c0e6c79..3dcaf13 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ This scenario leverages the MSBuildForUnity [Project Builder](#msbuild-project-b ``` - Add the following to the `dependencies` section of the file: ```json - "com.microsoft.msbuildforunity": "0.1.1-20190816.2.0" + "com.microsoft.msbuildforunity": "0.8.0" ``` 1. Create a "SDK style" MSBuild project (e.g. csproj) somewhere under your `Assets` directory of your Unity project that references the `MSBuildForUnity` NuGet package. Here is an example: ```xml @@ -77,7 +77,7 @@ This scenario leverages the MSBuildForUnity [Project Builder](#msbuild-project-b netstandard2.0 - + all runtime; build; native; contentfiles; analyzers From 21aadeffe8d3a679ab8a21a036b4a4ea4ca0a107 Mon Sep 17 00:00:00 2001 From: Andrei Borodin Date: Wed, 18 Dec 2019 13:35:42 -0800 Subject: [PATCH 2/5] Added documentation for augmenting NuGet packages to support MSBuildForUnity --- Documentation/CraftingNuGetPackages.md | 69 ++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 Documentation/CraftingNuGetPackages.md diff --git a/Documentation/CraftingNuGetPackages.md b/Documentation/CraftingNuGetPackages.md new file mode 100644 index 0000000..c421c37 --- /dev/null +++ b/Documentation/CraftingNuGetPackages.md @@ -0,0 +1,69 @@ +# Crafting a NuGet Package for MSB4U + +> MSBuildForUnity consumes .NET based packages without any modifications to the package. This documentation describes how C++, WinRT or packages with Unity-specific contents can easily be adapted to work with MSBuildForUnity. + +## Quickstart Summary + +Though the use of a [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file inside a NuGet package, we can leverage properties provided by MSBuildForUnity to appropriately select the contents to bring into the Unity project. The following snippet is taken from [Microsoft.Windows.MixedReality.DotNetWinRT](https://www.nuget.org/packages/Microsoft.Windows.MixedReality.DotNetWinRT/) NuGet package. It brings in the `Unity` folder packaged in the root of the NuGet package to the output folder inside Unity. + +```xml + + + + $(MSBuildThisFileName) + + + + + PreserveNewest + + false + $(PackageDestinationFolder)\%(RecursiveDir)%(Filename)%(Extension) + + + +``` + +## Understanding MSBuildForUnity Behavior + +MSBuildForUnity is based on MSBuild and thereby leverages the build rules including package and project reference resoluton of MSBuild. These steps are invoked at Editor Compilation stage with a set of MSBuildForUnity provided variables. At this stage, we have the following information available: + +- Unity Version (ie Major.Minor) +- Platform being targeted (UWP, Android, Standalone, etc). +- .NET Target Framework (4.6, .NET Standard 2.0) +- Compilation define symbols specified +- For UWP Platform we know Min and Target UWP SDK + +Because this stage is not aware of the target device, and happens before we build the player output (to Android Studio, XCode or Visual Studio) we don't have the following information: + +- The target platform of the device (ARM, x86, x64) + +This means that we don't know the target platform of the device and thereby can't bring in a specific native DLL (ARM, x86, x64). Thus for NuGet packages with Native code, we must add additional logic to bring in every DLL as well as Unity specific .meta files. + +### Meta Files + +MSBuildForUnity performs meta file generation for .NET libraries, and there are plans to support processing Native DLLs as well, however this is not possible yet. For this reasons, packages with Native DLLs that must be brought into Unity must be accompanied with .meta files configured for those packages. + +### Properties Provided Through MSBuildForUnity + +The following properties are either passed through as the build CLI argument, or available in the Unity Project root's `MSBuildForUnity.Common.props` file. + +- **UnityConfiguration:** Whether we are building for `InEditor` or `Player`. (**LIMITATION** we only support `InEditor` for now; [Issue #59](https://github.com/microsoft/MSBuildForUnity/issues/59)) +- **UnityPlatform:** The platform that we are building for, the values match Unity's `BuildTarget` enum ([documentation](https://docs.unity3d.com/ScriptReference/BuildTarget.html)) +- **MSBuildForUnityVersion:** The `{Major}.{Minor}.{Patch}` version of MSBuildForUnity, it can be used in comparison. +- **MSBuildForUnityDefaultOutputPath:** The default output path for the Unity project's dependencies. + > **NOTE:** Don't rely on this unless you absolutely need to, rely on default MSBuild "copy-to-output" behavior. +- **TargetFramework:** By default, MSBuild will make TargetFramework available. + > MSBuild will also automatically bring in the DLLs from the NuGet packages' matching target framework folder. +- **UnityMajorVersion:** The major version of Unity (ie. 2018, 2019, etc) +- **UnityMinorVersion:** The minor version of Unity (ie. 1, 2, 3, 4) + +## Supporting MSBuildForUnity in your NuGet Package + +As mentioned in the [Quickstart Summary](##Quickstart%20Summary), to augment your NuGet package, you should do the following: + +1. Add [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file to your package. +2. Add necessary .meta files for your Native libraries. +3. Add additional content files (prefabs, etc) that is only Unity specific. +4. Specify your Native DLLs, .Meta and other files as `Content` in the build targets or props file. +5. Make sure to condition your properties/inclusions on the presence of `'$(MSBuildForUnityVersion)' != ''"` property. (If required, you can condition on specific MSBuild or Unity version). From 6d79117c531b71d85a952d1d6bdd6dd0b49a01f2 Mon Sep 17 00:00:00 2001 From: Andrei Borodin Date: Wed, 18 Dec 2019 14:43:59 -0800 Subject: [PATCH 3/5] Update Documentation/CraftingNuGetPackages.md Co-Authored-By: Chris Barth --- Documentation/CraftingNuGetPackages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CraftingNuGetPackages.md b/Documentation/CraftingNuGetPackages.md index c421c37..7dc4dd0 100644 --- a/Documentation/CraftingNuGetPackages.md +++ b/Documentation/CraftingNuGetPackages.md @@ -4,7 +4,7 @@ ## Quickstart Summary -Though the use of a [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file inside a NuGet package, we can leverage properties provided by MSBuildForUnity to appropriately select the contents to bring into the Unity project. The following snippet is taken from [Microsoft.Windows.MixedReality.DotNetWinRT](https://www.nuget.org/packages/Microsoft.Windows.MixedReality.DotNetWinRT/) NuGet package. It brings in the `Unity` folder packaged in the root of the NuGet package to the output folder inside Unity. +Through the use of a [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file inside a NuGet package, we can leverage properties provided by MSBuildForUnity to appropriately select the contents to bring into the Unity project. The following snippet is taken from [Microsoft.Windows.MixedReality.DotNetWinRT](https://www.nuget.org/packages/Microsoft.Windows.MixedReality.DotNetWinRT/) NuGet package. It brings in the `Unity` folder packaged in the root of the NuGet package to the output folder inside Unity. ```xml From e734584602e1ffe85c27cf745af203641a6307cb Mon Sep 17 00:00:00 2001 From: Andrei Borodin Date: Wed, 18 Dec 2019 17:00:07 -0800 Subject: [PATCH 4/5] Updated based on feedback: --- Documentation/CraftingNuGetPackages.md | 77 ++++++++++++-------------- 1 file changed, 34 insertions(+), 43 deletions(-) diff --git a/Documentation/CraftingNuGetPackages.md b/Documentation/CraftingNuGetPackages.md index 7dc4dd0..862eb39 100644 --- a/Documentation/CraftingNuGetPackages.md +++ b/Documentation/CraftingNuGetPackages.md @@ -1,48 +1,45 @@ # Crafting a NuGet Package for MSB4U -> MSBuildForUnity consumes .NET based packages without any modifications to the package. This documentation describes how C++, WinRT or packages with Unity-specific contents can easily be adapted to work with MSBuildForUnity. +> MSBuildForUnity (MSB4U) consumes .NET based packages without any modifications to the package. This documentation describes how C++, WinRT or packages with Unity-specific contents can easily be adapted to work with MSBuildForUnity. -## Quickstart Summary +## Quick Start -Through the use of a [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file inside a NuGet package, we can leverage properties provided by MSBuildForUnity to appropriately select the contents to bring into the Unity project. The following snippet is taken from [Microsoft.Windows.MixedReality.DotNetWinRT](https://www.nuget.org/packages/Microsoft.Windows.MixedReality.DotNetWinRT/) NuGet package. It brings in the `Unity` folder packaged in the root of the NuGet package to the output folder inside Unity. +A NuGet package is enabled for MSB4U through the use of a [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file inside a NuGet package, and a set of properties provided by MSB4U. The props/targets file is then responsible for declaring the contents that will get placed into the package consumer's Unity project. Essentially, the steps are as follows: -```xml - - - - $(MSBuildThisFileName) - - - - - PreserveNewest - - false - $(PackageDestinationFolder)\%(RecursiveDir)%(Filename)%(Extension) - - - -``` +1. In your package root, add a `Unity` folder with content to be placed into the consumer's Unity project: + - Assets - prefabs, meshes, textures, etc + - Native DLLs for each platform you support. + - Unity .meta files for the Assets and DLLs (with appropriate architecture marked) +2. Add a `build/.targets` file to your package, with the following contents: -## Understanding MSBuildForUnity Behavior + ```xml + + + + $(MSBuildThisFileName) + -MSBuildForUnity is based on MSBuild and thereby leverages the build rules including package and project reference resoluton of MSBuild. These steps are invoked at Editor Compilation stage with a set of MSBuildForUnity provided variables. At this stage, we have the following information available: + + + PreserveNewest + + false + $(PackageDestinationFolder)\%(RecursiveDir)%(Filename)%(Extension) + + + + ``` -- Unity Version (ie Major.Minor) -- Platform being targeted (UWP, Android, Standalone, etc). -- .NET Target Framework (4.6, .NET Standard 2.0) -- Compilation define symbols specified -- For UWP Platform we know Min and Target UWP SDK + > This is a real example taken from the [Microsoft.Windows.MixedReality.DotNetWinRT](https://www.nuget.org/packages/Microsoft.Windows.MixedReality.DotNetWinRT/) NuGet package. -Because this stage is not aware of the target device, and happens before we build the player output (to Android Studio, XCode or Visual Studio) we don't have the following information: +### What Happens -- The target platform of the device (ARM, x86, x64) +Those two steps are the basics for getting up to speed. When MSB4U is used to reference your NuGet package, the following will happen: -This means that we don't know the target platform of the device and thereby can't bring in a specific native DLL (ARM, x86, x64). Thus for NuGet packages with Native code, we must add additional logic to bring in every DLL as well as Unity specific .meta files. - -### Meta Files - -MSBuildForUnity performs meta file generation for .NET libraries, and there are plans to support processing Native DLLs as well, however this is not possible yet. For this reasons, packages with Native DLLs that must be brought into Unity must be accompanied with .meta files configured for those packages. +- Using the active Target Framework (.NET46, .NET Standard 2.0) configured in the consumer's Unity project, MSBuild will pick up the DLL from the libs folder and bring it into the Unity project. +- Furthermore, MSBuild will automatically reference the `.targets` file. +- MSB4U has a property `MSBuildForUnityVersion` declared, and thereby the condition `'$(MSBuildForUnityVersion)' != ''` will evaluate to `true`. + - This will include the Unity folder in your NuGet package as Content, which will get put into the consumer's Unity project. ### Properties Provided Through MSBuildForUnity @@ -53,17 +50,11 @@ The following properties are either passed through as the build CLI argument, or - **MSBuildForUnityVersion:** The `{Major}.{Minor}.{Patch}` version of MSBuildForUnity, it can be used in comparison. - **MSBuildForUnityDefaultOutputPath:** The default output path for the Unity project's dependencies. > **NOTE:** Don't rely on this unless you absolutely need to, rely on default MSBuild "copy-to-output" behavior. -- **TargetFramework:** By default, MSBuild will make TargetFramework available. +- `(MSBuild)` **TargetFramework:** By default, MSBuild will make TargetFramework available. > MSBuild will also automatically bring in the DLLs from the NuGet packages' matching target framework folder. - **UnityMajorVersion:** The major version of Unity (ie. 2018, 2019, etc) - **UnityMinorVersion:** The minor version of Unity (ie. 1, 2, 3, 4) -## Supporting MSBuildForUnity in your NuGet Package - -As mentioned in the [Quickstart Summary](##Quickstart%20Summary), to augment your NuGet package, you should do the following: +### Limitations -1. Add [Build Targets or Props](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package#include-msbuild-props-and-targets-in-a-package) file to your package. -2. Add necessary .meta files for your Native libraries. -3. Add additional content files (prefabs, etc) that is only Unity specific. -4. Specify your Native DLLs, .Meta and other files as `Content` in the build targets or props file. -5. Make sure to condition your properties/inclusions on the presence of `'$(MSBuildForUnityVersion)' != ''"` property. (If required, you can condition on specific MSBuild or Unity version). +Because all package resolution happens in the Unity Editor during edit-time compilation, we don't have access to the target architecture of the final device the code will live on. Because of this, we must include all flavors of Native binaries. From 079ed3525aba3dcb79238d5794a426138d0934c6 Mon Sep 17 00:00:00 2001 From: Andrei Borodin Date: Wed, 18 Dec 2019 17:14:03 -0800 Subject: [PATCH 5/5] Updated not at the top to stand out more --- Documentation/CraftingNuGetPackages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CraftingNuGetPackages.md b/Documentation/CraftingNuGetPackages.md index 862eb39..867eb73 100644 --- a/Documentation/CraftingNuGetPackages.md +++ b/Documentation/CraftingNuGetPackages.md @@ -1,6 +1,6 @@ # Crafting a NuGet Package for MSB4U -> MSBuildForUnity (MSB4U) consumes .NET based packages without any modifications to the package. This documentation describes how C++, WinRT or packages with Unity-specific contents can easily be adapted to work with MSBuildForUnity. +MSBuildForUnity (MSB4U) consumes .NET based packages **without any modifications** to the package. This documentation describes how C++, WinRT or packages with Unity-specific contents can easily be adapted to work with MSBuildForUnity. ## Quick Start