зеркало из https://github.com/dotnet/msbuild.git
Point wiki pages to new location in the main repo
Rainer Sigwald
Родитель
ca0bb95c4a
Коммит
a3cf78b945
|
|
@ -1,89 +1 @@
|
|||
# MSBuild binary log overview
|
||||
|
||||
Starting with MSBuild 15.3 a new binary log format is introduced, to complement the existing file and console loggers.
|
||||
|
||||
Goals:
|
||||
* completeness (more information than the most detailed file log)
|
||||
* build speed (doesn't slow the build down nearly as much as the diagnostic-level file log)
|
||||
* smaller disk size (10-20x more compact than a file log)
|
||||
* structure (preserves the exact build event args that can later be replayed to reconstruct the exact events and information as if a real build was running). File logs erase structure and are harder to parse (especially for multicore /m builds). Build analyzer tools are conceivable that could benefit from the structure in a binary log. An API is available to load and query binary logs.
|
||||
* optionally collect the project files (and all imported targets files) used during the build. This can help analyzing the logs and even view preprocessed source for all projects (with all imported projects inlined).
|
||||
|
||||
See http://msbuildlog.com for more information.
|
||||
|
||||
# Creating a binary log during a build
|
||||
|
||||
Use the new `/bl` switch to enable the binary logger:
|
||||
```
|
||||
> msbuild.exe MySolution.sln /bl
|
||||
```
|
||||
|
||||
By default the binary log file is named `msbuild.binlog` and it is written to the current directory. To specify a custom log file name and/or path, pass it after a colon:
|
||||
```
|
||||
> msbuild.exe MySolution.sln /bl:out.binlog
|
||||
```
|
||||
|
||||
You can use the binary logger simultaneously with other loggers, such as text file (/fl) and console loggers. They are independent and having a binary log side-by-side with other logs may be beneficial (for sending a log to other people or running automatic build analysis tools that rely on the exact build event structure without having to parse text logs).
|
||||
|
||||
When using the binary logger all other log formats are technically redundant since you can later reconstruct all the other logs from the binary log. To turn off console logging, pass the `/noconlog` switch. Builds will usually be much faster if you don't pass the console and file loggers.
|
||||
|
||||
# Collecting projects and imports source files
|
||||
|
||||
By default the binary logger will collect the source code of all project files and all imported project/targets files used during the build. You can control this behavior:
|
||||
* `/bl:ProjectImports=None` (do not collect project and imports files)
|
||||
* `/bl:ProjectImports=Embed` (default - embed in the `.binlog` file)
|
||||
* `/bl:ProjectImports=ZipFile` (produce a separate `.ProjectImports.zip` file next to the log file that contains the files)
|
||||
|
||||
Note that only `*.csproj`, `*.targets` and other MSBuild project formats are collected. No other source files (`*.cs`, `*.cpp` etc) are collected.
|
||||
|
||||
If the binary log contains the projects/imports files the MSBuild Structured Log Viewer will display all the files contained in the log, let you search through them and even display preprocessed view for any project where all imported projects are inlined (similar to `msbuild /pp` switch).
|
||||
|
||||
# Replaying a binary log
|
||||
|
||||
Instead of passing the project/solution to MSBuild.exe you can now pass a binary log to "build". This will replay all events to all other loggers (just the console by default). Here's an example of replaying a `.binlog` file to the diagnostic verbosity text log:
|
||||
|
||||
```
|
||||
> msbuild.exe msbuild.binlog /noconlog /flp:v=diag;logfile=diag.log
|
||||
```
|
||||
|
||||
# Creating a binary log with older MSBuild versions
|
||||
|
||||
It is also possible to use the BinaryLogger with older MSBuild versions, such as MSBuild 14.0. For this you'll need the StructuredLogger.dll available here:
|
||||
https://github.com/KirillOsenkov/MSBuildStructuredLog/releases/download/v1.0.130/StructuredLogger.dll
|
||||
|
||||
Alternatively you can download/install the https://www.nuget.org/packages/Microsoft.Build.Logging.StructuredLogger NuGet package and use the `StructuredLogger.dll` provided by it.
|
||||
|
||||
Once you have the `StructuredLogger.dll` on disk you can pass it to MSBuild like this:
|
||||
|
||||
```
|
||||
> msbuild.exe /logger:BinaryLogger,"path\to\StructuredLogger.dll";msbuild.binlog
|
||||
```
|
||||
|
||||
# Using MSBuild Structured Log Viewer
|
||||
|
||||
You can use the MSBuild Structured Log Viewer tool to view `.binlog` files:
|
||||
http://msbuildlog.com
|
||||
|
||||
# Binary log file format
|
||||
|
||||
The implementation of the binary logger is here:
|
||||
https://source.dot.net/#Microsoft.Build/Logging/BinaryLogger/BinaryLogger.cs
|
||||
https://github.com/Microsoft/msbuild/blob/master/src/Build/Logging/BinaryLogger/BinaryLogger.cs
|
||||
|
||||
It is a `GZipStream`-compressed binary stream of serialized `BuildEventArgs` objects. The event args objects are serialized and deserialized using:
|
||||
* https://source.dot.net/#Microsoft.Build/Logging/BinaryLogger/BuildEventArgsWriter.cs
|
||||
* https://source.dot.net/#Microsoft.Build/Logging/BinaryLogger/BuildEventArgsReader.cs
|
||||
|
||||
## Incrementing the file format
|
||||
|
||||
Every .binlog file has the first three bytes that indicate the file version. The current file format version is 2 (`00 00 02`).
|
||||
|
||||
When incrementing the file format, keep this in mind:
|
||||
* Increment the version and add a summary of the changes: https://github.com/Microsoft/msbuild/blob/master/src/Build/Logging/BinaryLogger/BinaryLogger.cs#L22
|
||||
* In BuildEventArgsWriter.cs, just add fields, etc. without worrying.
|
||||
* In BuildEventArgsReader.cs, add exactly the same changes, but wrapped in an `if`-statement like this: `if (fileFormatVersion > version where the field was introduced)
|
||||
* Open an issue over at https://github.com/KirillOsenkov/MSBuildStructuredLog/issues/new so I can adapt the Structured Log Viewer to these changes.
|
||||
|
||||
The format is backwards compatible, i.e. MSBuild will be able to play back .binlog files created with an older version of MSBuild. The Viewer will also be able to open files of any older version. Since the viewer updates automatically and I can push out updates easily, we can consider the Viewer is always able to read all .binlogs.
|
||||
|
||||
However MSBuild of version 15.3 won't be able to read .binlogs created with MSBuild version 15.6. This means the format is unfortunately not forwards-compatible. It is not self-describing, i.e. it doesn't carry its schema around for performance and compactness reasons. This is not a problem with a Viewer because Viewer is always up-to-date (there isn't an "old version" of the Viewer unless people go to great lengths to prevent it from auto-updating).
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Binary-Log.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,50 +1 @@
|
|||
MSBuild can be successfully built on Windows, OS X 10.11, Ubuntu 14.04, and Ubuntu 16.04. Newer versions of Ubuntu may work, but .NET Core development is currently aimed at 14.04.
|
||||
|
||||
# Windows #
|
||||
## Build process
|
||||
|
||||
`cibuild.cmd --target CoreCLR`
|
||||
|
||||
# Unix #
|
||||
|
||||
**Required packages for OSX & Ubuntu**
|
||||
|
||||
MSBuild currently builds with a prerelease version of .NET Core 1.0. It requires the [.NET Core prerequisites](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md), which you can acquire manually or easily get by [installing the .NET Core SDK](https://dot.net/core).
|
||||
|
||||
* *OpenSSL*: MSBuild uses the .Net CLI to download Nuget packages during its build process. The CLI requires a recent OpenSSL library available in `/usr/lib`. This can be downloaded using [brew](http://brew.sh/) on OS X (`brew install openssl`) and apt-get (`apt-get install openssl`) on Ubuntu, or [building from source](https://wiki.openssl.org/index.php/Compilation_and_Installation#Mac). If you use a different package manager and see an error that says `Unable to load DLL 'System.Security.Cryptography.Native'`, `dotnet` may be looking in the wrong place for the library.
|
||||
|
||||
* [Mono](http://www.mono-project.com/download/#download-lin) when doing a Mono-hosted version of MSBuild
|
||||
|
||||
**Required packages for Ubuntu**
|
||||
* [libunwind](http://www.nongnu.org/libunwind/index.html) is required by .NET Core. Install it using `sudo apt-get install libunwind8`
|
||||
|
||||
##Build process##
|
||||
|
||||
Targeting .Net Core: `./cibuild.sh --target CoreCLR`
|
||||
|
||||
Targeting Mono: `./cibuild.sh --target Mono`
|
||||
|
||||
Using a .NET core MSBuild host: `./cibuild.sh --host CoreCLR`
|
||||
|
||||
Using a Mono MSBuild host: `./cibuild --host Mono`
|
||||
|
||||
##Tests##
|
||||
|
||||
Tests are currently disabled on platforms other than Windows. If you'd like to run them, explicitly opt in with
|
||||
```sh
|
||||
./cibuild.sh --scope Test
|
||||
```
|
||||
|
||||
## Getting .Net Core MSBuild binaries without building the code ##
|
||||
The best way to get .NET Core MSBuild is through the [dotnet CLI](https://github.com/dotnet/cli/), which redistributes us. It's not always the very very latest but they take regular drops. After installing it, you can use MSBuild through `dotnet build` or by manual invocation of the `MSBuild.dll` in the dotnet distribution.
|
||||
|
||||
## Debugging
|
||||
|
||||
### Wait in Main
|
||||
Set the environment variable `MSBUILDDEBUGONSTART` to 2.
|
||||
|
||||
### Debugging a test
|
||||
Add a `Console.ReadKey` in the test and manually invoke it via xunit. Example:
|
||||
```
|
||||
Tools\dotnetcli\dotnet.exe bin\Debug-NetCore\AnyCPU\Windows_NT\Windows_NT_Deployment_Test\xunit.console.netcore.exe bin\Debug-NetCore\AnyCPU\Windows_NT\Windows_NT_Deployment_Test\Microsoft.Build.Engine.UnitTests.dll -noshadow -method Microsoft.Build.UnitTests.Evaluation.ItemEvaluation_Tests.ImmutableListBuilderBug
|
||||
```
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Building-Testing-and-Debugging-on-.Net-Core-MSBuild.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,60 +1 @@
|
|||
**These instructions refer to working with the Master branch.**
|
||||
|
||||
## Required Software
|
||||
**Microsoft Visual Studio 2015 **
|
||||
|
||||
This version of MSBuild closely aligns to the version that ships with Visual Studio 2015. You may be able to build and debug with Visual Studio 2013, but using Visual Studio 2015 is recommended. You can download the community edition from [https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx).
|
||||
|
||||
> MSBuild requires that you have the Windows SDK plugin installed with Visual Studio 2015. Make sure you have the plugin selected when installing Visual Studio. You can also modify your existing VS installation by running the installer again. 
|
||||
|
||||
> Please note this is intending as a standalone build engine, not integrated with Visual Studio. We may add support/documentation for that scenario if we see community interest for it.
|
||||
|
||||
## Getting the code
|
||||
|
||||
1. Clone the repo: `git clone https://github.com/Microsoft/msbuild.git`
|
||||
2. Build on the command line: `cibuild.cmd --target Full --scope Compile --bootstrap-only`
|
||||
3. Open the solution file in Visual Studio 2015 (`src/MSBuild.sln`).
|
||||
|
||||
# Running Unit Tests
|
||||
To run the unit tests from Visual Studio:
|
||||
|
||||
1. Open the MSBuild solution file (`src/MSBuild.sln`) in Visual Studio 2015.
|
||||
2. Open the Test menu -> Windows -> Test Explorer.
|
||||
3. Click Run All.
|
||||
|
||||
To build MSBuild and run all unit tests, use `RebuildWithLocalMSBuild.cmd` as described in "Build and verify MSBuild" below. That is usually the best way to ensure that a change is ready to go.
|
||||
|
||||
# Contributing
|
||||
Please see [Contributing Code](https://github.com/Microsoft/msbuild/wiki/Contributing-Code) for details on contributing changes back to the code. Please read this carefully and engage with us early to ensure work is not wasted.
|
||||
|
||||
# Walkthroughs
|
||||
## Build and verify MSBuild
|
||||
The first scenario you might want to try is building our source tree and then using that output to build it again. To do this, you will need to have Visual Studio 2015 installed on your machine. First, open a 'Developer Command Prompt for VS2015':
|
||||
```
|
||||
git clone https://github.com/Microsoft/msbuild.git
|
||||
cd .\msbuild
|
||||
.\build.cmd
|
||||
.\RebuildWithLocalMSBuild.cmd
|
||||
```
|
||||
|
||||
## Debugging MSBuild
|
||||
- Breaking into the main method of MSBuild.exe: set the environment variable `MSBUILDDEBUGONSTART` to 1 or 2: https://github.com/Microsoft/msbuild/blob/master/src/MSBuild/XMake.cs#L488-L501
|
||||
- Dumping scheduler state: set `MSBUILDDEBUGSCHEDULER` to 1; set `MSBUILDDEBUGPATH` to where to dump the scheduling state
|
||||
- Example of manually running a single unit test:
|
||||
```
|
||||
packages\xunit.runner.console\2.1.0\tools\xunit.console.x86.exe bin\Debug\x86\Windows_NT\Windows_NT_Deployment_Test\Microsoft.Build.Engine.UnitTests.dll -noshadow -method Microsoft.Build.UnitTests.Evaluation.ItemEvaluation_Tests.ImmutableListBuilderBug
|
||||
```
|
||||
|
||||
## Build a Console App
|
||||
To build a console app, you first need a drop of MSBuild (built on your machine) with all the required dependencies. To do this, open a 'Developer Command Prompt for VS2015' and run the following command from your msbuild folder:
|
||||
```
|
||||
BuildAndCopy.cmd bin\MSBuild
|
||||
```
|
||||
Now, just point `bin\MSBuild\MSBuild.exe` at a project file. Here's a quick sample project that will build an application that runs on the .NET Core framework:
|
||||
```
|
||||
cd ..\
|
||||
git clone https://github.com/dotnet/corefxlab
|
||||
.\msbuild\bin\MSBuild\MSBuild.exe .\corefxlab\demos\CoreClrConsoleApplications\HelloWorld\HelloWorld.csproj
|
||||
.\corefxlab\demos\CoreClrConsoleApplications\HelloWorld\bin\Debug\HelloWorld.exe
|
||||
```
|
||||
>Paths here assumes corefxlab and msbuild repos are in the same parent folder.
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,33 +1 @@
|
|||
MSBuild can be successfully built on Windows, OS X 10.11, Ubuntu 14.04, and Ubuntu 16.04.
|
||||
|
||||
Mono maintains a fork of msbuild (for now) at `https://github.com/mono/msbuild/`. You can clone that and use the `xplat-master` branch or `mono-2017-10` for the next release branch.
|
||||
|
||||
# Unix #
|
||||
|
||||
**Required packages for OSX & Ubuntu**
|
||||
|
||||
MSBuild currently builds with a prerelease version of .NET Core 1.0. It requires the [.NET Core prerequisites](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md), which you can acquire manually or easily get by [installing the .NET Core SDK](https://dot.net/core).
|
||||
|
||||
* *OpenSSL*: MSBuild uses the .Net CLI to download Nuget packages during its build process. The CLI requires a recent OpenSSL library available in `/usr/lib`. This can be downloaded using [brew](http://brew.sh/) on OS X (`brew install openssl`) and apt-get (`apt-get install openssl`) on Ubuntu, or [building from source](https://wiki.openssl.org/index.php/Compilation_and_Installation#Mac). If you use a different package manager and see an error that says `Unable to load DLL 'System.Security.Cryptography.Native'`, `dotnet` may be looking in the wrong place for the library.
|
||||
|
||||
* [Mono](http://www.mono-project.com/download/) when doing a Mono-hosted version of MSBuild
|
||||
|
||||
**Required packages for Ubuntu**
|
||||
* [libunwind](http://www.nongnu.org/libunwind/index.html) is required by .NET Core. Install it using `sudo apt-get install libunwind8`
|
||||
|
||||
## Build process ##
|
||||
|
||||
```make```
|
||||
|
||||
## Tests ##
|
||||
|
||||
```make test-mono```
|
||||
|
||||
## Installing ##
|
||||
|
||||
`./install-mono-prefix.sh </your/mono/prefix>`
|
||||
|
||||
## Getting Mono MSBuild binaries without building the code ##
|
||||
The best way to get Mono MSBuild for OSX/macOS is to get the official [Mono package](http://www.mono-project.com/download/#download-mac). After installing it, you can run `msbuild`.
|
||||
<br/>
|
||||
For Linux, you can install mono and msbuild from [here](http://www.mono-project.com/download/#download-lin).
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Building-Testing-and-Debugging-on-Mono-MSBuild.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,36 +1 @@
|
|||
### Contributing Code
|
||||
Before submitting a feature or substantial code contribution please discuss it with the team and ensure it follows the product roadmap. The team rigorously reviews and tests all code submissions. The submissions must meet an extremely high bar for quality, design, backwards compatibility, and roadmap appropriateness.
|
||||
|
||||
Because our focus right now is on maintaining backwards compatibility, the team has set the following limits on pull requests:
|
||||
|
||||
- Contributions must be discussed with the team first, or they will likely be declined. As our process matures and our experience grows, the team expects to take larger contributions.
|
||||
- Only contributions referencing an approved Issue will be accepted.
|
||||
- Pull requests that do not merge easily with the tip of the master branch will be declined. The author will be asked to merge with tip and submit a new pull request.
|
||||
- Submissions must meet functional and performance expectations, including scenarios for which the team doesn't yet have open source tests. This means you may be asked to fix and resubmit your pull request against a new open test case if it fails one of these tests.
|
||||
- Submissions must follow the [.Net Foundation Coding Guidelines](https://github.com/dotnet/corefx/wiki/Contributing#c-coding-style)
|
||||
|
||||
When you are ready to proceed with making a change, get set up to [[build|Building Testing and Debugging]] the code and familiarize yourself with our workflow and our coding conventions. These two blogs posts on contributing code to open source projects are good too: Open Source Contribution Etiquette by Miguel de Icaza and Don’t “Push” Your Pull Requests by Ilya Grigorik.
|
||||
|
||||
You must sign a Contributor License Agreement (CLA) before submitting your pull request. To complete the CLA, submit a request via the form and electronically sign the CLA when you receive the email containing the link to the document. You need to complete the CLA only once to cover all Microsoft Open Technologies OSS projects.
|
||||
|
||||
### Developer Workflow
|
||||
|
||||
1. Work item is assigned to a developer during the triage process
|
||||
2. Both Microsoft and external contributors are expected to do their work in a local fork and submit code for consideration via a pull request.
|
||||
3. When the pull request process deems the change ready it will be merged directly into the tree.
|
||||
|
||||
### Creating New Issues
|
||||
|
||||
Please follow these guidelines when creating new issues in the issue tracker:
|
||||
|
||||
- Use a descriptive title that identifies the issue to be addressed or the requested feature. For example when describing an issue where the compiler is not behaving as expected, write your bug title in terms of what the product should do rather than what it is doing – “MSBuild should report CS1234 when Xyz is used in Abcd.”
|
||||
- Do not set any bug fields other than Impact.
|
||||
- Specify a detailed description of the issue or requested feature.
|
||||
- For bug reports, please also:
|
||||
- Describe the expected behavior and the actual behavior. If it is not self-evident such as in the case of a crash, provide an explanation for why the expected behavior is expected.
|
||||
- Provide example code that reproduces the issue.
|
||||
- Specify any relevant exception messages and stack traces.
|
||||
- Subscribe to notifications for the created issue in case there are any follow up questions.
|
||||
|
||||
### Coding Conventions
|
||||
- Use the coding style outlined in the [.Net Foundation Coding Guidelines](https://github.com/dotnet/corefx/wiki/Contributing#c-coding-style)
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Contributing-Code.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,29 +1 @@
|
|||
# Contributing Tasks
|
||||
|
||||
MSBuild tasks are units of executable code used to perform atomic build operations. There are many tasks already in MSBuild but there is always a need for more. We encourage you to contribute useful tasks directory to MSBuild.
|
||||
|
||||
## Getting Started
|
||||
Please [open an issue](https://github.com/Microsoft/msbuild/issues/new) to propose a new task. This gives the community a chance to provide feedback and make suggestions. Once there is consensus that the task is needed and the below requirements are met, fork the repository and begin development.
|
||||
|
||||
## Requirements
|
||||
The following requirements are in place for contributed tasks:
|
||||
|
||||
1. The task must not introduce the need to ship any third-party assemblies.
|
||||
2. The task should work on .NET Framework and .NET Core if possible. It can be confusing to users if a task only works on certain platforms.
|
||||
3. The task must have unit tests in place to prevent regressions.
|
||||
|
||||
## Developing a new Task
|
||||
Review the existing documentation on [Task Writing](https://docs.microsoft.com/en-us/visualstudio/msbuild/task-writing) to learn about the fundamentals. You can also looking at existing tasks in the [Microsoft.Build.Tasks.Core assembly](https://github.com/Microsoft/msbuild/tree/master/src/Tasks) for a great starting point.
|
||||
|
||||
Tasks are generally simple and should not require much effort to develop. If you find a task becoming very complicated, consider breaking it up into smaller tasks which can be run together in a target.
|
||||
|
||||
## Developing unit tests
|
||||
Contributed tasks must have unit tests in place to prove they work and to prevent regressions caused by other code changes. There are a lot of examples in the [Microsoft.Build.Tasks.UnitTests](https://github.com/Microsoft/msbuild/tree/master/src/Tasks.UnitTests) project. Please provide a reasonable amount of test coverage so ensure the quality of the product.
|
||||
|
||||
## Documentation
|
||||
You can document the new task in the [visualstudio-docs](https://github.com/MicrosoftDocs/visualstudio-docs/tree/master/docs/msbuild) repository. This helps users discover the new functionality. The easiest way is to copy the documentation page for an existing task as a template.
|
||||
|
||||
## Ship schedule
|
||||
MSBuild ships regularly with Visual Studio. It also is updated in Preview releases. Once your contribution is merged, expect it to be available in the next release.
|
||||
|
||||
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Contributing-Tasks.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
18
Home.md
18
Home.md
|
|
@ -1,17 +1 @@
|
|||
# Getting Started
|
||||
|
||||
* Building Testing and Debugging
|
||||
* [Full Framework MSBuild](https://github.com/Microsoft/msbuild/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild)
|
||||
* [.Net Core MSBuild](https://github.com/Microsoft/msbuild/wiki/Building-Testing-and-Debugging-on-.Net-Core-MSBuild)
|
||||
* [Mono MSBuild](https://github.com/Microsoft/msbuild/wiki/Building-Testing-and-Debugging-on-Mono-MSBuild)
|
||||
* [Contributing Code](Contributing-Code)
|
||||
* [MSBuild Roadmap](Roadmap)
|
||||
* [MSBuild Resources](MSBuild-Resources)
|
||||
* [MSBuild Tips & Tricks](MSBuild-Tips-&-Tricks)
|
||||
* [Binary log](Binary-Log)
|
||||
* [Rebuilding when nothing changed](Rebuilding-when-nothing-changed)
|
||||
* [Something's wrong in my build](Something's-wrong-in-my-build)
|
||||
* [Microsoft.Build.Framework](Microsoft.Build.Framework) - Some gotchas around the Microsoft.Build.Framework project/assembly.
|
||||
* [Target Maps](Target-Maps)
|
||||
* Tasks
|
||||
* [ResolveAssemblyReference](ResolveAssemblyReference)
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Home.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,8 +1 @@
|
|||
MSbuild got forked from an internal Microsoft repository. Although the Github repository is the official one, where development takes place, there are still some left-over connections to the internal one. This page attempts to document these.
|
||||
|
||||
Changes to these files need to be migrated back into the internal repo because that's where they are localized:
|
||||
- [src/XMakeCommandLine/Microsoft.Build.Core.xsd](https://github.com/Microsoft/msbuild/blob/xplat/src/XMakeCommandLine/Microsoft.Build.Core.xsd)
|
||||
- [src/XMakeCommandLine/Microsoft.Build.CommonTypes.xsd](https://github.com/Microsoft/msbuild/blob/xplat/src/XMakeCommandLine/Microsoft.Build.CommonTypes.xsd)
|
||||
|
||||
There should be no changes to the following files. They are shipped from the internal repo. The github ones are stale.
|
||||
- [all XamlRules](https://github.com/Microsoft/msbuild/tree/xplat/src/XMakeTasks/XamlRules)
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Interactions-with-the-internal-repository.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,23 +1 @@
|
|||
## Localizable resource structure
|
||||
- Neutral resources: [*resx](https://github.com/search?utf8=%E2%9C%93&q=repo%3AMicrosoft%2Fmsbuild+extension%3Aresx&type=Code&ref=advsearch&l=&l=)
|
||||
- `Strings.shared.resx` is a shared resource and gets embedded into all msbuild dlls
|
||||
- each neutral resource has a directory named `xlf` besides it which contains its localized strings in .xlf format
|
||||
- there is one language per xlf
|
||||
- the logical name for a resource is: `<Assembly Name>.<Neutral Resx File Name>.resources`. In the ResourceManager this appears as `<Assembly Name>.<Neutral Resx File Name>` (without the trailing `.resources`). For example, the `Microsoft.Build` assembly uses the `Microsoft.Build.Strings.resources` [logical resource name](https://github.com/Microsoft/msbuild/blob/master/src/XMakeBuildEngine/Microsoft.Build.csproj#L659) (the resource file is `Strings.resx`), and its corresponding [ResourceManager](https://github.com/Microsoft/msbuild/blob/master/src/XMakeBuildEngine/Resources/AssemblyResources.cs#L116) uses `Microsoft.Build.Strings`.
|
||||
|
||||
## How to edit a resource
|
||||
- if you need to add / remove / update a resource, only do so in the neutral resx files. xlf files get automatically updated during localized builds.
|
||||
|
||||
## What a localized build does
|
||||
- converts xlf files to localized resx files
|
||||
- the localized resx files are generated into the `$(IntermediaryOutputPath)`
|
||||
- produces satellite assemblies for each language
|
||||
- satellite assemblies are used even on English machines. This is for testing purposes, to ensure that English builds are not different than non English builds
|
||||
|
||||
## Process for interacting with the localization team
|
||||
- 3 weeks cadence for master, initiated by loc team
|
||||
- on demand for master / release branches, initiated by msbuild team
|
||||
|
||||
## Contributing a better translation
|
||||
- send a PR with an updated `<target>` element of the xlf resource (do not include other non-localization changes)
|
||||
- we will notify the localization team, which will then take over and review the PR
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Localization.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,45 +1 @@
|
|||
# Concepts
|
||||
* [https://msdn.microsoft.com/en-us/library/dd637714.aspx](https://msdn.microsoft.com/en-us/library/dd637714.aspx)
|
||||
* [MSBuild Reserved and Well-Known Properties](https://msdn.microsoft.com/en-us/library/ms164309.aspx)
|
||||
* [Target Maps](Target-Maps)
|
||||
|
||||
# MSBuild Source Code
|
||||
* [https://github.com/Microsoft/MSBuild](https://github.com/Microsoft/MSBuild)
|
||||
* [https://source.dot.net](https://source.dot.net)
|
||||
* Use [http://referencesource.microsoft.com](http://referencesource.microsoft.com) or [http://source.roslyn.io](http://source.roslyn.io) to browse Microsoft MSBuild targets. Examples:
|
||||
* search for "[_FindDependencies MSBuildProperty](http://referencesource.microsoft.com/#q=_FindDependencies%20MSBuildProperty)"
|
||||
* find targets [http://referencesource.microsoft.com/#MSBuildTarget=ResolveAssemblyReferences](http://referencesource.microsoft.com/#MSBuildTarget=ResolveAssemblyReferences)
|
||||
|
||||
# Tips & Tricks
|
||||
* [MSBuild Tips & Tricks](MSBuild-Tips-&-Tricks)
|
||||
|
||||
# Tools
|
||||
* MSBuildStructuredLog
|
||||
* [https://github.com/KirillOsenkov/MSBuildStructuredLog](https://github.com/KirillOsenkov/MSBuildStructuredLog)
|
||||
* MSBuildExtensionPack
|
||||
* [http://www.msbuildextensionpack.com](http://www.msbuildextensionpack.com)
|
||||
* [https://github.com/mikefourie/MSBuildExtensionPack](https://github.com/mikefourie/MSBuildExtensionPack)
|
||||
* MSBuilder
|
||||
* [https://github.com/MobileEssentials/MSBuilder](https://github.com/MobileEssentials/MSBuilder) - reusable blocks of MSBuild helpers
|
||||
* MSBuildExplorer
|
||||
* [http://msbuildexplorer.com](http://msbuildexplorer.com)
|
||||
* [https://github.com/mikefourie/MSBuildExplorer](https://github.com/mikefourie/MSBuildExplorer)
|
||||
* MSBuild Sidekick
|
||||
* [http://attrice.info/msbuild](http://attrice.info/msbuild)
|
||||
* MSBuildDumper
|
||||
* [https://github.com/KirillOsenkov/MSBuildTools](https://github.com/KirillOsenkov/MSBuildTools) - install from Chocolatey `cinst MSBuildDumper` - very quick tool to dump properties and items of a project
|
||||
* MSBuild Profiler
|
||||
* [https://msbuildprofiler.codeplex.com/](https://msbuildprofiler.codeplex.com/)
|
||||
* MSBuild Shell Extension
|
||||
* [https://msbuildshellex.codeplex.com/](https://msbuildshellex.codeplex.com/)
|
||||
|
||||
# Books
|
||||
* [Inside the Microsoft Build Engine: Using MSBuild and Team Foundation Build (2nd Edition) by Sayed Hashimi, William Bartholomew](http://www.amazon.com/Inside-Microsoft-Build-Engine-Foundation/dp/0735645248)
|
||||
* [MSBuild Trickery: 99 Ways to Bend the Build Engine to Your Will, by Brian Kretzler](http://www.amazon.com/MSBuild-Trickery-Ways-Build-Engine/dp/061550907X)
|
||||
|
||||
# Blogs
|
||||
* [https://blogs.msdn.microsoft.com/msbuild](https://blogs.msdn.microsoft.com/msbuild)
|
||||
* [Sayed Hashimi's blog http://sedodream.com](http://sedodream.com)
|
||||
* [Mike Fourie's blog https://mikefourie.wordpress.com](https://mikefourie.wordpress.com)
|
||||
|
||||
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/MSBuild-Resources.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,69 +1 @@
|
|||
# MSBuild.exe /pp
|
||||
MSBuild preprocessor. Pass /pp to the command line to create a single huge XML project file with all project imports inlined in the correct order. This is useful to investigate the ordering of evaluation and execution.
|
||||
|
||||
Example:
|
||||
```
|
||||
msbuild MyProject.csproj /pp:inlined.proj
|
||||
```
|
||||
|
||||
# MSBuild.exe /m
|
||||
Parallel build. Many people still don't know that they can significantly speed up their builds by passing /m to MSBuild.exe.
|
||||
|
||||
# MSBuild.exe /nr:false
|
||||
Disable node reuse (/nodeReuse:false). Don't leave MSBuild.exe processes hanging around locking files after the build completes. See more details in MSBuild command line help (/?). See also `MSBUILDDISABLENODEREUSE=1` below.
|
||||
|
||||
# EnvironmentVariables
|
||||
* `MSBUILDTARGETOUTPUTLOGGING=1` - set this to enable [printing all target outputs to the log](https://blogs.msdn.microsoft.com/msbuild/2010/03/31/displaying-target-output-items-using-the-console-logger).
|
||||
* `MSBUILDLOGTASKINPUTS=1` - log task inputs (not needed if there are any diagnostic loggers already).
|
||||
* `MSBUILDEMITSOLUTION=1` - save the generated .proj file for the .sln that is used to build the solution.
|
||||
* `MSBUILDENABLEALLPROPERTYFUNCTIONS=1` - enable [additional property functions](https://blogs.msdn.microsoft.com/visualstudio/2010/04/02/msbuild-property-functions).
|
||||
* `MSBUILDLOGVERBOSERARSEARCHRESULTS=1` - in ResolveAssemblyReference task, log verbose search results.
|
||||
* `MSBUILDLOGCODETASKFACTORYOUTPUT=1` - dump generated code for task to a <GUID>.txt file in the TEMP directory
|
||||
* `MSBUILDDISABLENODEREUSE=1` - set this to not leave MSBuild processes behind (see /nr:false above, but the environment variable is useful to also set this for Visual Studio for example).
|
||||
* `MSBUILDLOGASYNC=1` - enable asynchronous logging.
|
||||
|
||||
# TreatAsLocalProperty
|
||||
If MSBuild.exe is passed properties on the command line, such as `/p:Platform=AnyCPU` then this value overrides whatever assignments you have to that property inside property groups. For instance, `<Platform>x86</Platform>` will be ignored. To make sure your local assignment to properties overrides whatever they pass on the command line, add the following at the top of your MSBuild project file:
|
||||
|
||||
```
|
||||
<Project TreatAsLocalProperty="Platform" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
|
||||
```
|
||||
|
||||
This will make sure that your local assignments to the `Platform` property are respected. You can specify multiple properties in `TreatAsLocalProperty` separated by semicolon.
|
||||
|
||||
# Visual Studio Background Builds
|
||||
Set the `TRACEDESIGNTIME=true` environment variable to output design-time build logs to TEMP: read more here: https://blogs.msdn.microsoft.com/jeremykuhne/2016/06/06/vs-background-builds
|
||||
|
||||
# Visual Studio Design-time (IntelliSense) builds
|
||||
|
||||
Use this command-line to approximate what the design-time build does:
|
||||
|
||||
```
|
||||
/t:CollectResolvedSDKReferencesDesignTime;DebugSymbolsProjectOutputGroup;CollectPackageReferences;ResolveComReferencesDesignTime;ContentFilesProjectOutputGroup;DocumentationProjectOutputGroupDependencies;SGenFilesOutputGroup;ResolveProjectReferencesDesignTime;SourceFilesProjectOutputGroup;DebugSymbolsProjectOutputGroupDependencies;SatelliteDllsProjectOutputGroup;BuiltProjectOutputGroup;SGenFilesOutputGroupDependencies;ResolveAssemblyReferencesDesignTime;CollectAnalyzersDesignTime;CollectSDKReferencesDesignTime;DocumentationProjectOutputGroup;PriFilesOutputGroup;BuiltProjectOutputGroupDependencies;ResolvePackageDependenciesDesignTime;SatelliteDllsProjectOutputGroupDependencies;SDKRedistOutputGroup;CompileDesignTime /p:SkipCompilerExecution=true /p:ProvideCommandLineArgs=true /p:BuildingInsideVisualStudio=true /p:DesignTimeBuild=true
|
||||
```
|
||||
|
||||
# Extend all builds (at system-wide level)
|
||||
See https://www.simple-talk.com/dotnet/.net-tools/extending-msbuild, "Extending all builds" section. Also read about [MSBuildUserExtensionsPath](http://referencesource.microsoft.com/#MSBuildFiles/C/ProgramFiles(x86)/MSBuild/14.0/Microsoft.Common.props,33), [CustomBeforeMicrosoftCommonProps](http://referencesource.microsoft.com/#MSBuildFiles/C/ProgramFiles(x86)/MSBuild/14.0/Microsoft.Common.props,68), [CustomBeforeMicrosoftCommonTargets](http://referencesource.microsoft.com/#MSBuildFiles/C/ProgramFiles(x86)/MSBuild/14.0/bin_/amd64/Microsoft.Common.targets,71), and CustomAfterMicrosoftCommonProps/CustomAfterMicrosoftCommonTargets.
|
||||
|
||||
Example:
|
||||
Create this file (Custom.props) in `C:\Users\username\AppData\Local\Microsoft\MSBuild\14.0\Microsoft.Common.targets\ImportAfter`:
|
||||
|
||||
```
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
|
||||
<PropertyGroup>
|
||||
<MyCustomProperty>Value!</MyCustomProperty>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
then build any project. It will have MyCustomProperty set to Value!
|
||||
|
||||
# Diagnose WPF temporary assembly compilation issues
|
||||
|
||||
Set the property `GenerateTemporaryTargetAssemblyDebuggingInformation` on the `GenerateTemporaryTargetAssembly` task:
|
||||
https://referencesource.microsoft.com/#PresentationBuildTasks/BuildTasks/Microsoft/Build/Tasks/Windows/GenerateTemporaryTargetAssembly.cs,4571677f19ba0d24,references
|
||||
|
||||
If the property `$(GenerateTemporaryTargetAssemblyDebuggingInformation)` is set, the temporary project generated during XAML project build will not be deleted and will be available for inspection. This is only available in the recent versions of .NET Framework, so check if your `Microsoft.WinFX.targets` file has it.
|
||||
|
||||
Also the name of the project was renamed from `*.tmp_proj` to `*_wpftmp.csproj` so the file extension is now C#: `WpfApp1_jzmidb3d_wpftmp.csproj`
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/MSBuild-Tips-&-Tricks.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,31 +1 @@
|
|||
### Microsoft.Build.Framework
|
||||
It you have looked carefully, you might notice some odd behavior around this assembly (Microsoft.Build.Framework). We released the source here, but in some cases if you use our `BuildAndCopy.cmd` script, you will reference the one one your machine instead of the one you just built! Here's why.
|
||||
|
||||
Microsoft.Build.Framework contains the types and interfaces for extensibility in MSBuild. If you've ever written a custom Task, you might recognize them as ITask, ITaskItem, etc. After you build your Task, let's say targeting `Microsoft.Build.Framework, Version=12.0.0.0, PublicKeyToken=b03f5f7f11d50a3a` (Visual Studio 2013), anyone with MSBuild 12.0 or later can use your Task. In later versions of MSBuild, say version 14.0, we will use a [binding redirect](https://msdn.microsoft.com/en-us/library/eftw1fys(v=vs.110).aspx) to point you to the newer version of Microsoft.Build.Framework. Assuming we did our jobs right with compatibility, your Task should run without ever knowing the difference. The crucial point of detail here is that the public key token for the Framework assembly **did not change** between version. If it does, binding redirection is not allowed.
|
||||
|
||||
## Option 1 - Project Reference
|
||||
By default this is enabled. This means that all MSBuild code will reference Microsoft.Build.Framework as a project reference and therefore will not have the same public key token as the retail version.
|
||||
|
||||
| Pros | Cons |
|
||||
|:-:|:-:|
|
||||
| You can customize/change Microsoft.Build.Framework as much as you want. Change the types, base implementation, interfaces, it's up to you. | You can not build anything that uses a custom task **unless** that custom task references your Microsoft.Build.Framework (or more precisely, one with the same public key token) |
|
||||
|
||||
## Option 2 - Retail Assembly Reference
|
||||
If you set the `TargetRetailBuildFramework` property to `true`, this behavior will occur. You are now referencing the public retail assembly version 14.0.0.0 (Visual Studio 2015).
|
||||
|
||||
| Pros | Cons |
|
||||
|:-:|:-:|
|
||||
| You can build projects that use custom tasks. | You cannot make any changes to the Framework project. If you do, they won't be used. |
|
||||
|
||||
To make this a little bit easier, use:
|
||||
```
|
||||
BuildAndCopy.cmd <path> true
|
||||
```
|
||||
This will set the property for you and create a drop of MSBuild and dependencies needed to build other project.
|
||||
|
||||
## Option 3 - Test or Delay Signing
|
||||
For the advanced user, another option here is to delay sign this version of MSBuild with our public key. Since that part of the key is public, it's very easy to extract (using `Sn.exe`) and delay sign. You can get more information on that here:
|
||||
* [Delay Signing](https://blogs.msdn.microsoft.com/shawnfa/2004/03/17/delay-signing/)
|
||||
* [Test Key Signing](http://blogs.msdn.com/b/shawnfa/archive/2005/10/24/484170.aspx)
|
||||
|
||||
Delay signing is the easiest, but it modifies your system to allow it to load and trust an assembly (Microsoft.Build.Framework) even when it's not signed at all, from any source. The Test Key Signing allows for a much more secure approach (as long as you keep your private key private), but is more complicated to setup. We are providing this as a reference, but please only try this if you: really want to customize Microsoft.Build.Framework and use existing custom Tasks, you feel comfortable with the security implications, and you acknowledge this is all at your own risk.
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Microsoft.Build.Framework.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,16 +1 @@
|
|||
# How to investigate rebuilding when nothing has changed
|
||||
|
||||
There is a class of problems with build where when you build twice, it still rebuilds fully the second time even though nothing has changed. This is called build incrementality issues. They can happen in MSBuild or in Visual Studio (in which case the VS project system's up-to-date-check decides to rebuild the project).
|
||||
|
||||
There are multiple tools to investigate and fix broken incrementality. Start with the blog posts below.
|
||||
|
||||
* [https://blogs.msdn.microsoft.com/kirillosenkov/2014/08/04/how-to-investigate-rebuilding-in-visual-studio-when-nothing-has-changed/](https://blogs.msdn.microsoft.com/kirillosenkov/2014/08/04/how-to-investigate-rebuilding-in-visual-studio-when-nothing-has-changed/)
|
||||
* [http://www.andreas-reiff.de/2012/02/when-visual-studio-keeps-rebuilding-projects-that-have-not-changed/](http://www.andreas-reiff.de/2012/02/when-visual-studio-keeps-rebuilding-projects-that-have-not-changed/)
|
||||
* [MSDN: How to build incrementally](https://msdn.microsoft.com/en-us/library/ms171483.aspx)
|
||||
|
||||
Strings to search for in the build logs:
|
||||
* `Building target "CoreCompile" completely`
|
||||
* `is newer than output`
|
||||
* `out-of-date`
|
||||
|
||||
Consider using https://github.com/KirillOsenkov/MSBuildStructuredLog to help with searching through the build log.
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Rebuilding-when-nothing-changed.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,152 +1 @@
|
|||
One of the most important tasks in the MSBuild toolset is `ResolveAssemblyReference` (RAR). Its purpose is to take all the references specified in .csproj files (or elsewhere) via the `<Reference>` item and map them to paths to assembly files on disk. The compiler only can accept a .dll path on disk as a reference, so `ResolveAssemblyReference` converts strings like `mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089` to paths like `C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.6.1\mscorlib.dll` which are then passed to the compiler via the /r switch.
|
||||
|
||||
Additionally RAR determines a closure of all .dll/exe references recursively, and for each of them determines whether it should be copied to the build output directory or not. It doesn't do the actual copying (that is handled later, after the actual compile step), but it prepares an item list of files to copy.
|
||||
|
||||
RAR is invoked from the `ResolveAssemblyReferences` target:
|
||||
|
||||
|
||||
If you notice the ordering, ResolveAssemblyReferences is happening before Compile, and CopyFilesToOutputDirectory happens after Compile (obviously).
|
||||
|
||||
## Source Code
|
||||
You can browse Microsoft's MSBuild targets online at:
|
||||
http://source.roslyn.io/#MSBuildFiles/C/ProgramFiles(x86)/MSBuild/14.0/bin_/amd64/Microsoft.Common.CurrentVersion.targets,1820
|
||||
This is where the RAR task is invoked in the targets file.
|
||||
|
||||
The source code for RAR is at:
|
||||
https://github.com/Microsoft/msbuild/blob/master/src/Tasks/AssemblyDependency/ResolveAssemblyReference.cs
|
||||
|
||||
## Inputs
|
||||
RAR is very detailed about logging its inputs:
|
||||
|
||||
The Parameters node is standard for all tasks, but additionally RAR logs its own set of information under Inputs (which is basically the same as under Parameters but structured differently). RAR logs this information in a method called LogInputs():
|
||||
https://github.com/Microsoft/msbuild/blob/xplat/src/XMakeTasks/AssemblyDependency/ResolveAssemblyReference.cs#L1249
|
||||
|
||||
The most important inputs are Assemblies and AssemblyFiles:
|
||||
|
||||
```
|
||||
<ResolveAssemblyReference
|
||||
Assemblies="@(Reference)"
|
||||
AssemblyFiles="@(_ResolvedProjectReferencePaths);@(_ExplicitReference)"
|
||||
```
|
||||
|
||||
http://source.roslyn.io/#MSBuildFiles/C/ProgramFiles(x86)/MSBuild/14.0/bin_/amd64/Microsoft.Common.CurrentVersion.targets,1820
|
||||
|
||||
`Assemblies` is just using the contents of the `Reference` MSBuild item at the moment when RAR is invoked for the project. All the metadata/assembly references, including your NuGet references, go here. Each reference has a rich set of metadata attached to it:
|
||||
|
||||
|
||||
`AssemblyFiles` comes from `ResolveProjectReference` target's output item called `_ResolvedProjectReferencePaths`. `ResolveProjectReference` runs before RAR and it converts `<ProjectReference>` items to paths of built assemblies on disk. So the `AssemblyFiles` will contain the assemblies built by all referenced projects of the current project:
|
||||
|
||||
|
||||
Another useful input is the boolean `FindDependencies` parameter which takes its value from the `_FindDependencies` property:
|
||||
```
|
||||
FindDependencies="$(_FindDependencies)"
|
||||
```
|
||||
|
||||
You can set this property to false in your build to turn off analyzing transitive dependency assemblies.
|
||||
|
||||
## Execution
|
||||
|
||||
The source code of the main `Execute()` method can be found in MSBuild source code on GitHub:
|
||||
https://github.com/Microsoft/msbuild/blob/xplat/src/XMakeTasks/AssemblyDependency/ResolveAssemblyReference.cs#L1877
|
||||
|
||||
The algorithm simplified is:
|
||||
```
|
||||
...
|
||||
Line 1923: LogInputs();
|
||||
...
|
||||
// useful environment variable to set to crank up detailed search result logging
|
||||
Line 1930: _logVerboseSearchResults = Environment.GetEnvironmentVariable("MSBUILDLOGVERBOSERARSEARCHRESULTS") != null;
|
||||
...
|
||||
Line 2087: ReferenceTable dependencyTable = new ReferenceTable(...) // main data structure
|
||||
...
|
||||
Line 2052: ReadStateFile(); // read the cache file from the `obj` directory if present
|
||||
...
|
||||
Line 2182: dependencyTable.ComputeClosure(allRemappedAssemblies, _assemblyFiles, _assemblyNames, generalResolutionExceptions);
|
||||
...
|
||||
Line 2213: // Build the output tables.
|
||||
dependencyTable.GetReferenceItems
|
||||
(
|
||||
out _resolvedFiles,
|
||||
out _resolvedDependencyFiles,
|
||||
out _relatedFiles,
|
||||
out _satelliteFiles,
|
||||
out _serializationAssemblyFiles,
|
||||
out _scatterFiles,
|
||||
out _copyLocalFiles
|
||||
);
|
||||
...
|
||||
Line 2274: WriteStateFile(); // write the cache file to the `obj` directory
|
||||
...
|
||||
Line 2284: LogResults();
|
||||
...
|
||||
```
|
||||
|
||||
Very simplified, the way it works is it takes the input list of assemblies (both from metadata and project references), retrieves the list of references for each assembly it processes (by reading metadata) and builds a transitive closure of all referenced assemblies, and resolves them from various locations (including the GAC, AssemblyFoldersEx, etc.).
|
||||
|
||||
It builds a ReferenceTable:
|
||||
https://github.com/Microsoft/msbuild/blob/xplat/src/XMakeTasks/AssemblyDependency/ReferenceTable.cs
|
||||
|
||||
Referenced assemblies are added to the closure iteratively until no more new references are added. Then the algorithm stops.
|
||||
|
||||
Direct references that we started with are called Primary references. Indirect assemblies that were added to closure because of a transitive reference are called Dependency. Each indirect assembly remembers all the primary ("root") items that led to its inclusion and their corresponding metadata.
|
||||
|
||||
## Results
|
||||
|
||||
RAR is just as rich at logging results as it is for inputs:
|
||||
|
||||
|
||||
Resolved assemblies are divided into two categories: Primary references and Dependencies. Primary references were specified explicitly as references of the project being built. Dependencies were inferred from references of references transitively.
|
||||
|
||||
**Important note:** RAR reads assembly metadata to determine the references of a given assembly. When the C# compiler emits an assembly it only adds references to assemblies that are actually needed. So it may happen that when compiling a certain project the project may specify a unneeded reference that won't be baked into the assembly. It is OK to add references to project that are not needed; they are just ignored.
|
||||
|
||||
## CopyLocal item metadata
|
||||
|
||||
References can also have the `CopyLocal` metadata or not. If the reference has `CopyLocal = true`, it will later be copied to the output directory by the `CopyFilesToOutputDirectory` target. In this example, DataFlow is CopyLocal while Immutable is not:
|
||||
|
||||
|
||||
If the CopyLocal metadata is missing entirely, it is assumed to be true by default. So RAR by default tries to copy dependencies to output unless it finds a reason not to. RAR is quite detailed about the reasons why it chose a particular reference to be CopyLocal or not.
|
||||
|
||||
All possible reasons for CopyLocal decision are enumerated here:
|
||||
https://github.com/Microsoft/msbuild/blob/master/src/Tasks/AssemblyDependency/CopyLocalState.cs
|
||||
It is useful to know these strings to be able to search for them in build logs.
|
||||
|
||||
## Private item metadata
|
||||
An important part of determining CopyLocal is the Private metadata on all primary references. Each reference (primary or dependency) has a list of all primary references (source items) that have contributed to that reference being added to the closure.
|
||||
|
||||
1. If none of the source items specify `Private` metadata, `CopyLocal` is set to `True` (or not set, which defaults to `True`)
|
||||
2. If any of the source items specify `Private=true`, `CopyLocal` is set to `True`
|
||||
3. If none of the source assemblies specify `Private=true` and at least one specifies `Private=false`, `CopyLocal` is set to `False`
|
||||
|
||||
Here's the source code:
|
||||
https://github.com/Microsoft/msbuild/blob/master/src/Tasks/AssemblyDependency/Reference.cs#L1243
|
||||
|
||||
## Which reference set Private to false?
|
||||
|
||||
The last point is an often used reason for CopyLocal being set to false:
|
||||
`This reference is not "CopyLocal" because at least one source item had "Private" set to "false" and no source items had "Private" set to "true".`
|
||||
|
||||
Unfortunately MSBuild doesn't tell us _which_ reference has set Private to false. I've filed an issue on MSBuild to improve logging: https://github.com/Microsoft/msbuild/issues/1485
|
||||
|
||||
For now, MSBuildStructuredLog offers an enhancement. It adds Private metadata to the items that had it specified above:
|
||||
|
||||
|
||||
This greatly simplifies investigations and tells you exactly which reference caused the dependency in question to be CopyLocal=false.
|
||||
|
||||
Here's a special analyzer that was added to MSBuild Structured Log Viewer to add this information:
|
||||
https://github.com/KirillOsenkov/MSBuildStructuredLog/blob/65f57afb858280effd4b56c59ef8d78de861241d/src/StructuredLogViewer/Analyzers/ResolveAssemblyReferenceAnalyzer/CopyLocalAnalyzer.cs
|
||||
|
||||
## GAC
|
||||
The Global Assembly Cache plays an important role in determining whether to copy references to output. This is unfortunate because the GAC contents is machine specific and this results in problems for reproducible builds (where the behavior differs on different machine dependent on machine state, such as the GAC).
|
||||
|
||||
There were recent fixes made to RAR to alleviate the situation. You can control the behavior by these two new inputs to RAR:
|
||||
|
||||
```
|
||||
CopyLocalDependenciesWhenParentReferenceInGac="$(CopyLocalDependenciesWhenParentReferenceInGac)"
|
||||
DoNotCopyLocalIfInGac="$(DoNotCopyLocalIfInGac)"
|
||||
```
|
||||
|
||||
## There was a conflict
|
||||
|
||||
A common situation is MSBuild gives a warning about different versions of the same assembly being used by different references. The solution often involves adding a binding redirect to the app.config file.
|
||||
|
||||
A useful way to investigate these conflicts is to search in MSBuild Structured Log Viewer for "There was a conflict". It will show you detailed information about which references needed which versions of the assembly in question.
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/ResolveAssemblyReference.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
35
Roadmap.md
35
Roadmap.md
|
|
@ -1,34 +1 @@
|
|||
MSBuild is under active development primarily in two different areas: .NET Core MSBuild and Desktop MSBuild.
|
||||
|
||||
# .NET Core MSBuild
|
||||
Our goal is the enable a subset of MSBuild to run cross-platform and build applications that target the .NET Core framework. This version should be delivered via NuGet and have no required dependencies on the machine (no installer, no registry, no GAC). It is not intended to replace the version integrated with Visual Studio nor build projects targeting the full .NET Framework.
|
||||
* Fully support Linux, OSX, and Windows with all .NET Core MSBuild features.
|
||||
* Eliminate dependency on the full .NET Framework (and mono).
|
||||
* Enable features over time to reduce feature gap ([#303](/Microsoft/msbuild/issues/303), [#304](/Microsoft/msbuild/issues/304)).
|
||||
|
||||
* Note that features like toolsets, registry, GAC, Frameworks, etc. that do not apply to building .NET Core applications will remain disabled.*
|
||||
|
||||
# Desktop MSBuild
|
||||
This version of MSBuild is the version we ship with Visual Studio (previously shipped as part of the .NET Framework) and runs on the full .NET Framework. Our goal is to maintain a single code base with a high degree of compatibility and stability between releases. As such, the bar for new features or behavior change should be very high.
|
||||
##Quality
|
||||
* Performance-related fixes to improve the end-to-end experience for developers in Visual Studio. [ongoing]
|
||||
* Fix top-hitting issues gathered from feedback and Watson events (crash data). [ongoing]
|
||||
|
||||
## Performance
|
||||
* Address "low-hanging fruit" to improve build speed, particularly around C++. [post Update 1 time-frame]
|
||||
* Improved incremental build with help of fully deterministic Roslyn builds. [post Update 1 time-frame]
|
||||
|
||||
## Technical Debt
|
||||
* Merge codebases (xplat, master, and internal branches). [RC time-frame]
|
||||
* Introduce compiler constants for CoreCLR feature flags.
|
||||
* Ship MSBuild for Visual Studio out of GitHub sources. [Visual Studio vNext time-frame]
|
||||
|
||||
## Telemetry
|
||||
* Gather additional data on usage and issues (hangs in Visual Studio, etc). [tentatively RTM time-frame]
|
||||
|
||||
# Branch Strategy
|
||||
* `xplat`: Work for cross-platform support, primarily focused on CoreCLR. In the medium term, we should build both CoreCLR and Desktop MSBuild from the same branch and merge this branch into `master`.
|
||||
* `master`: Work for Desktop MSBuild for Visual Studio "15", for now manually mirrored into internal source control.
|
||||
* Microsoft Internal: At the moment, the "official" location that produces builds that ship with Visual Studio and its updates. Changes are manually mirrored from GitHub `master` as we go along.
|
||||
* Stabilization: when we're preparing a release, we'll start a branch for that release. Most commits should be pushed to `master` as usual. Last-minute bugfixes can have pull requests targeting the update branch. Any commit to the release branch should be followed immediately by a merge of the release branch to `master`, so that `master` is always up to date. Since `master` is now destined to release with Visual Studio "15", commits intended to be included in an update for Visual Studio 2015 (MSBuild 14.0) should go to `dev14-update`.
|
||||
* Mono support: Still TBD. See [#302](/Microsoft/msbuild/issues/302). LKG xplat [`@f9d8cc7`] (https://github.com/Microsoft/msbuild/commit/f9d8cc725ca2cd46d7e01015afba0defea95ce37)
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Roadmap.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,20 +1 @@
|
|||
📝 This is horrifically incomplete, put here in the spirit of "something is better than nothing".
|
||||
|
||||
To debug a tricky problem with your build, try these tools in order:
|
||||
|
||||
1. Diagnostic-level logs show you project state changes and inputs to all tasks
|
||||
1. The MSBuild preprocessor `msbuild /pp:out.xml` shows you the full logic of the project in a single file (so you can easily grep around for "what uses this property?" and "where is this target defined?")
|
||||
1. Add a target to debug project state of specific interest at specific times:
|
||||
```xml
|
||||
<Target Name="PrintfDebugger" BeforeTargets="Something">
|
||||
<Message Importance="High" Text="PropOfInterest: $(PropOfInterest)" />
|
||||
<Message Importance="High" Text="ItemOfInterest: @(ItemOfInterest)" />
|
||||
</Target>
|
||||
```
|
||||
|
||||
### Tools
|
||||
To get a clearer idea of what's going on in your build, one option is [MSBuildStructuredLog](https://github.com/KirillOsenkov/MSBuildStructuredLog). MSBuildStructuredLog is a logger for MSBuild that records and visualizes a structured representation of executed targets, tasks, properties, and item values. It can be easier to look though than the diagnostic log.
|
||||
|
||||
|
||||
|
||||
More debugging tools listed [here](https://github.com/Microsoft/msbuild/wiki/MSBuild-Resources).
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Something's-wrong-in-my-build.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
|
|
@ -1,4 +1 @@
|
|||
[Build Target Map](https://raw.githubusercontent.com/KirillOsenkov/MSBuildStructuredLog/master/docs/BuildTargets.png)
|
||||
|
||||
[Compile Target Map](https://raw.githubusercontent.com/KirillOsenkov/MSBuildStructuredLog/master/docs/CompileTargets.png)
|
||||
|
||||
This page has moved to the [documentation folder](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/Target-Maps.md) in the main repo to allow pull requests.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче