# MSBuildForUnity MSBuildForUnity solves the problem of establishing clear dependency relationships between Unity project and other .NET components such as external (to Unity) C# projects, or NuGet packages. It creates a familiar to .NET developers project structure and ensures that the dependencies are resolved and brought into the Unity project as appropriate. With this component, you can: - Share code between Unity and other .NET projects (such as UWP XAML apps, Xamarin apps, etc.). - Consuming existing .NET components (e.g. NuGet packages). The samples included in this repository best convey the simplicity and value of this component: - [Simple NuGet Dependency Sample](https://github.com/microsoft/MSBuildForUnity/blob/master/Samples/SimpleNuGetDependency.Unity/README.md) - Showcases the simplest and most minimal usage of this component to pull in a dependency. - [Integrated Dependencies Sample](https://github.com/microsoft/MSBuildForUnity/blob/master/Samples/IntegratedDependencies.Unity/README.md) - Showcases the power of this component by relying on project generation. - [Cross Unity Dependencies Sample](https://github.com/microsoft/MSBuildForUnity/blob/master/Samples/CrossUnityDependencies.Unity/README.md) - Showcases how to establish a dependency between two Unity projects (almost like AsmDef-to-AsmDef). ### Builds and Packages | Build | Build Status | Package Feed | |-------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | UPM | [![UPM Build Status][UPMBuildBadge]][UPMBuild] | [Azure DevOps][UPMPackage] | | NuGet | [![NuGet Build Status][NuGetBuildBadge]][NuGetBuild] | [![NuGet Package][NuGetPackageBadge]][NuGetPackage] | ## Quick Start The following are basic instructions for taking advantage of MSBuildForUnity for some common scenarios. ### Bring NuGet packages and MSBuild projects into a Unity project This scenario leverages the MSBuildForUnity [Project Builder](https://github.com/microsoft/MSBuildForUnity/raw/master/#msbuild-project-builder) and the MSBuildForUnity [NuGet Package](https://github.com/microsoft/MSBuildForUnity/raw/master/#msbuildforunity-nuget-package). 1. Add the `com.microsoft.msbuildforunity` UPM (Unity Package Manager) package. - Edit the `Packages/manifest.json` file in your Unity project. - Add the following near the top of the file: ```json "scopedRegistries": [ { "name": "Microsoft", "url": "https://pkgs.dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_packaging/UnityDeveloperTools/npm/registry/", "scopes": [ "com.microsoft" ] } ], ``` - Add the following to the `dependencies` section of the file: ```json "com.microsoft.msbuildforunity": "" ``` NOTE: Replace `` with the latest package version from the [MSBuildForUnity UPM feed][UPMPackage]. 1. MSBuildForUnity will create a top-level project in your `Assets` folder named after your Unity project name: `{UnityProjectName}.Dependencies.msb4u.csproj`, edit this project file to add additional references to any NuGet packages or C# projects you want to use in your Unity project. ```xml $(UnityCurrentTargetFramework) ``` 1. For additional instructions, see [Core Scenarios](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/CoreScenarios.md). ## Extended Instructions Here you can find additional instructions for various things you may want to accomplish: - [Add Support MSB4U to a NuGet Package](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/CraftingNuGetPackages.md) - [OSX and Linux Support](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/OSXAndLinuxSupport.md) ## Features MSBuildForUnity has several features that can be used independently or in conjunction. ### MSBuild Project Builder The MSBuild Project Builder provides a means of building MSBuild projects from within Unity, where the output is generally consumed by the Unity project. [![MSBuild Project Builder Progress Bar](https://github.com/microsoft/MSBuildForUnity/raw/master/Documentation/MSBuildProjectBuilder/MSBuildProgressBar.gif)](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/MSBuildProjectBuilder/MSBuildProjectBuilder.md) For details, see the [documentation](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/MSBuildProjectBuilder/MSBuildProjectBuilder.md), [source](https://github.com/microsoft/MSBuildForUnity/raw/master/Source/MSBuildTools.Unity/Packages/com.microsoft.msbuildforunity/Editor/ProjectBuilder/MSBuildProjectBuilder.cs), and [samples](https://github.com/microsoft/MSBuildForUnity/raw/master/Source/MSBuildTools.Unity/Assets/Samples/Samples.sln). ### MSBuild Project Generator The MSBuild Project Generator will generate a Visual Studio solution configured for building the Unity project into DLLs outside of Unity. This solution is configured for each of the platforms installed with Unity and the InEditor/Player variants of the assemblies. ### MSBuildForUnity NuGet Package The `MSBuildForUnity` NuGet package augments the default MSBuild build logic to ensure the build output is suitable for Unity consumption. This package can be referenced from MSBuild projects that are built by the [MSBuild Project Builder](https://github.com/microsoft/MSBuildForUnity/raw/master/#msbuild-project-builder) to add these features: - Meta file generation - generates .meta files for build output such as .dlls. - Dependency resolution - all dependencies (through `PackageReference`s or `ProjectReference`s) are resolved and sent to the output directory (which is typically under the Unity project's Assets directory). - Debug symbol patching - enables debugging pre-built dlls (e.g. from NuGet packages) while running in the Unity Editor. For details, see the [documentation](https://github.com/microsoft/MSBuildForUnity/blob/master/Documentation/MSBuildForUnityNuGetPackage/MSBuildForUnityNuGetPackage.md), [source](https://github.com/microsoft/MSBuildForUnity/raw/master/Source/MSBuildTools.Unity.NuGet/MSBuildForUnity.csproj), and [samples](https://github.com/microsoft/MSBuildForUnity/raw/master/Source/MSBuildTools.Unity/Assets/Samples/Samples.sln). [PRBuildBadge]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_apis/build/status/MSBuildForUnity.PRGate?branchName=master [PRBuild]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_build/latest?definitionId=2&branchName=master [UPMBuildBadge]: https://camo.githubusercontent.com/064f5c06cb876a7651cb4587664b9abc03efa50144b04e7a8b20ad61e6fb760f/68747470733a2f2f6465762e617a7572652e636f6d2f556e697479446576656c6f706572546f6f6c732f4d534275696c64466f72556e6974792f5f617069732f6275696c642f7374617475732f4d534275696c64466f72556e6974792e5075626c6973682e55504d3f6272616e63684e616d653d6d6173746572 [UPMBuild]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_build/latest?definitionId=1&branchName=master [NuGetBuildBadge]: https://camo.githubusercontent.com/0a0ce9d3f15d47f94ee0d56f6da7ff0efc7e86dcfb56cd883c047b32528073a8/68747470733a2f2f6465762e617a7572652e636f6d2f556e697479446576656c6f706572546f6f6c732f4d534275696c64466f72556e6974792f5f617069732f6275696c642f7374617475732f4d534275696c64466f72556e6974792e5075626c6973682e4e754765743f6272616e63684e616d653d6d6173746572 [NuGetBuild]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_build/latest?definitionId=3&branchName=master [UPMPackage]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_packaging?_a=package&feed=UnityDeveloperTools&view=versions&package=com.microsoft.msbuildforunity&protocolType=Npm [NuGetPackageBadge]: https://camo.githubusercontent.com/432f6c78227039afd77bab03b3322001b9805aa489078cbcc3331a2201ec9c2d/68747470733a2f2f66656564732e6465762e617a7572652e636f6d2f556e697479446576656c6f706572546f6f6c732f30636239356532352d393139342d346363642d396166622d3433396232356563623933612f5f617069732f7075626c69632f5061636b6167696e672f46656564732f61336431633363632d363034322d346530352d623639392d3339613934376537353633392f5061636b616765732f62646637386433312d646439372d346636622d626566622d3735626236313835313732652f4261646765 [NuGetPackage]: https://dev.azure.com/UnityDeveloperTools/MSBuildForUnity/_packaging?_a=package&feed=a3d1c3cc-6042-4e05-b699-39a947e75639&package=bdf78d31-dd97-4f6b-befb-75bb6185172e&preferRelease=true ## Contributing This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit . When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](https://github.com/microsoft/MSBuildForUnity/raw/master/mailto:opencode@microsoft.com) with any additional questions or comments. ### Prerequisites The following tools are required to contribute to this project: - [Visual Studio 2017+](https://visualstudio.microsoft.com/downloads) - [Unity 2018+](https://unity3d.com/get-unity/download) To get started, clone the repo, and then run `git submodule update --init` to initialize submodules.