mono/linux-packaging-mono
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Imported Upstream version 5.10.0.69

Browse Source 
Former-commit-id: fc39669a0b707dd3c063977486506b6793da2890
This commit is contained in:
Xamarin Public Jenkins (auto-signing)
2018-01-29 19:03:06 +00:00
parent d8f8abd549
commit e2950ec768
6283 changed files with 453847 additions and 91879 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
external/corefx/Documentation/project-docs/dogfooding.md vendored
View File

@@ -1,32 +1,54 @@
# How to get up and running on .NET Core 2.0
# How to get up and running on .NET Core
This document provides the steps necessary to consume a nightly build of
.NET Core 2.0 runtime and SDK.
.NET Core runtime and SDK.
Please note that these steps are likely to change as we're simplifying
this experience. Make sure to consult this document often.
## Install prerequisites
1. Acquire the latest nightly .NET Core SDK 2.0
1. Acquire the latest nightly .NET Core SDK by downloading the zip or tarball listed in https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries (for example, https://dotnetcli.blob.core.windows.net/dotnet/Sdk/master/dotnet-sdk-latest-win-x64.zip ) into a new folder.
- [Win 64-bit Latest Zip](https://dotnetcli.azureedge.net/dotnet/Sdk/master/dotnet-dev-win-x64.latest.zip) [Installer](https://dotnetcli.azureedge.net/dotnet/Sdk/master/dotnet-dev-win-x64.latest.exe)
- [macOS 64-bit Latest Tar](https://dotnetcli.azureedge.net/dotnet/Sdk/master/dotnet-dev-osx-x64.latest.tar.gz) [Installer](https://dotnetcli.azureedge.net/dotnet/Sdk/master/dotnet-dev-osx-x64.latest.pkg)
- [Others](https://github.com/dotnet/cli/blob/master/README.md#installers-and-binaries)
2. By default, the dotnet CLI will use the globally installed SDK if it matches the major/minor version you request and has a higher revision. To force it to use the locally installed SDK, you must set an environment variable `DOTNET_MULTILEVEL_LOOKUP=0` in your shell. You can use `dotnet --info` to verify what version of the Shared Framework it is using.
To setup the SDK download the zip and extract it somewhere and add the root folder to your path or always fully
qualify the path to dotnet in the root of this folder for all the instructions in this document.
3. Reminder: if you are using a local copy of the dotnet CLI, take care that when you type `dotnet` you do not inadvertently pick up a different copy that you may have in your path. On Windows, for example, if you use a Developer Command Prompt, a global copy may be in the path, so use the fully qualified path to your local `dotnet`. If you receive an error "The current .NET SDK does not support targeting .NET Core 2.1." then you may be executing an older `dotnet`.
Note: Installer will put dotnet globally in your path which you might not want for dogfooding daily toolsets.
After setting up dotnet you can verify you are using the newer version by executing `dotnet --info` -- the version should be greater than 2.2.0-* (dotnet CLI is currently numbered 2.2.0-* not 2.1.0-* ). Here is an example output at the time of writing:
```
>dotnet.exe --info
.NET Command Line Tools (2.2.0-preview1-007460)
After setting up dotnet you can verify you are using the newer version by:
Product Information:
Version: 2.2.0-preview1-007460
Commit SHA-1 hash: 173cc035e4
`dotnet --info` -- the version should be greater than 2.0.0-*
Runtime Environment:
OS Name: Windows
OS Version: 10.0.16299
OS Platform: Windows
RID: win10-x64
Base Path: F:\dotnet\sdk\2.2.0-preview1-007460\
Microsoft .NET Core Shared Framework Host
Version : 2.1.0-preview1-25825-07
Build : 4c165c13bd390adf66f9af30a088d634d3f37a9d
```
4. Our nightly builds are uploaded to MyGet, not NuGet - so ensure the .NET Core MyGet feed is in your nuget configuration in case you need other packages from .NET Core that aren't included in the download. For example, on Windows you could edit `%userprofile%\appdata\roaming\nuget\nuget.config` or on Linux edit `~/.nuget/NuGet/NuGet.Config` to add this line:
```xml
<packageSources>
<add key="myget.dotnetcore" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />
...
</packageSources>
```
(Documentation for configuring feeds is [here](https://docs.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior).)
## Setup the project
1. Create a new project
- Create a new folder for your app
- Create a new folder for your app and change to that folder
- Create project file by running `dotnet new console`
2. Restore packages so that you're ready to play:
@@ -37,25 +59,6 @@ $ dotnet restore
## Consume the new build
Edit your `Program.cs` to consume the new APIs, for example:
```CSharp
using System;
using System.Net;
class Program
{
static void Main(string[] args)
{
WebUtility.HtmlDecode("&amp;", Console.Out);
Console.WriteLine();
Console.WriteLine("Hello World!");
}
}
```
Run the bits:
```
$ dotnet run
```
@@ -65,7 +68,7 @@ Rinse and repeat!
## Advanced Scenario - Using a nightly build of Microsoft.NETCore.App
When using the above instructions, your application will run against the same
.NET Core 2.0 runtime that comes with the SDK. That works fine to get up and
.NET Core runtime that comes with the SDK. That works fine to get up and
running quickly. However, there are times when you need to use a nightly build
of Microsoft.NETCore.App which hasn't made its way into the SDK yet. To enable
this, there are two options you can take.
@@ -84,8 +87,8 @@ runtime.
```XML
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.0</TargetFramework>
<RuntimeFrameworkVersion>2.0.0-beta-xyz-00</RuntimeFrameworkVersion> <!-- this line -->
<TargetFramework>netcoreapp2.1</TargetFramework>
<RuntimeFrameworkVersion>2.1.0-preview1-25825-07</RuntimeFrameworkVersion> <!-- modify build in this line -->
</PropertyGroup>
```
@@ -105,19 +108,21 @@ make it self-contained
```XML
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.0</TargetFramework>
<RuntimeFrameworkVersion>2.0.0-beta-xyz-00</RuntimeFrameworkVersion> <!-- pick nightly build -->
<RuntimeIdentifier>win7-x64</RuntimeIdentifier> <!-- make self-contained -->
<TargetFramework>netcoreapp2.1</TargetFramework>
<RuntimeFrameworkVersion>2.1.0-preview1-25825-07</RuntimeFrameworkVersion> <!-- modify build in this line -->
<RuntimeIdentifier>win-x64</RuntimeIdentifier> <!-- make self-contained -->
</PropertyGroup>
```
```
$ dotnet restore
$ dotnet publish
$ bin\Debug\netcoreapp2.0\win7-x64\publish\App.exe
$ bin\Debug\netcoreapp2.1\win-x64\publish\App.exe
```
## Using your local CoreFx build
## More Advanced Scenario - Using your local CoreFx build
If you built corefx locally with `build -allconfigurations` after building binaries it will build NuGet packages containing them. You can use those in your projects.
To use your local built corefx packages you will need to be a self-contained application and so you will
need to follow the "Self-contained" steps from above. Once you can successfully restore, build, publish,
@@ -127,11 +132,11 @@ and run a self-contained application you need the following steps to consume you
Look for a package named `Microsoft.Private.CoreFx.NETCoreApp.<version>.nupkg` under `corefx\bin\packages\Debug` (or Release if you built a release version of corefx).
Once you find the version number (for this example assume it is `4.4.0-beta-25102-0`) you need to add the following line to your project file:
Once you find the version number (for this example assume it is `4.5.0-preview1-25830-0`) you need to add the following line to your project file:
```
<ItemGroup>
<PackageReference Include="Microsoft.Private.CoreFx.NETCoreApp" Version="4.4.0-beta-25102-0" />
<PackageReference Include="Microsoft.Private.CoreFx.NETCoreApp" Version="4.5.0-preview1-25830-0" />
</ItemGroup>
```
@@ -146,25 +151,26 @@ you need to tell the tooling to use the assets from your local package. To do th
Replacing the RID in `runtime.win-x64.Microsoft.Private.CoreFx.NETCoreApp` with the RID of your current build.
Note these instructions above were only about updates to the binaries that are part of Microsoft.NETCore.App, if you want to test a package for library that ships in its own nuget package you can follow the same steps above but instead add a package reference to that package instead of "Microsoft.Private.CoreFx.NETCoreApp".
#### 2 - Add your bin directory to the Nuget feed list
By default the dogfooding dotnet SDK will create a Nuget.Config file next to your project, if it doesn't
you can create one. Your config file will need a source for your local corefx package directory as well
as a reference to our nightly dotnet-core feed on myget:
as a reference to our nightly dotnet-core feed on myget. The Nuget.Config file content should be:
```xml
<configuration>
<packageSources>
<add key="local coreclr" value="D:\git\corefx\bin\packages\Debug" />
<add key="local coreclr" value="D:\git\corefx\bin\packages\Debug" /> <!-- Change this to your own output path -->
<add key="dotnet-core" value="https://dotnet.myget.org/F/dotnet-core/api/v3/index.json" />
</packageSources>
</configuration>
```
Obviously **you need to update path in the XML to be the path to output directory for your build**.
Be sure to correct the path to your build output above.
On Windows you also have the alternative of modifying the Nuget.Config
at `%HOMEPATH%\AppData\Roaming\Nuget\Nuget.Config` (`~/.nuget/NuGet/NuGet.Config` on Linux) with the new location.
You also have the alternative of modifying the Nuget.Config
at `%HOMEPATH%\AppData\Roaming\Nuget\Nuget.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Linux) with the new location.
This will allow your new runtime to be used on any 'dotnet restore' run by the current user.
Alternatively you can skip creating this file and pass the path to your package directory using
the -s SOURCE qualifer on the dotnet restore command below. The important part is that somehow
@@ -178,9 +184,15 @@ dotnet publish
```
Now your publication directory should contain your local built CoreFx binaries.
#### 3 - Consuming updated packages
#### 3 - Consuming subsequent code changes by overwriting the binary (Alternative 1)
One possible problem with the technique above is that Nuget assumes that distinct builds have distinct version numbers.
To apply changes you subsequently make in your source tree, it's usually easiest to just overwrite the binary in the publish folder. Build the assembly containing your change as normal, then overwrite the assembly in your publish folder and running the app will pick up that binary. This relies on the fact that all the other binaries still match what is in your bin folder so everything works together.
#### 3 - Consuming subsequent code changes by rebuilding the package (Alternative 2)
This is more cumbersome than just overwriting the binaries, but is more correct.
First note that Nuget assumes that distinct builds have distinct version numbers.
Thus if you modify the source and create a new NuGet package you must give it a new version number and use that in your
application's project. Otherwise the dotnet.exe tool will assume that the existing version is fine and you
won't get the updated bits. This is what the Minor Build number is all about. By default it is 0, but you can
@@ -188,66 +200,13 @@ give it a value by setting the BuildNumberMinor environment variable.
```bat
set BuildNumberMinor=3
```
before packaging. You should see this number show up in the version number (e.g. 4.4.0-beta-25102-03).
before packaging. You should see this number show up in the version number (e.g. 4.5.0-preview1-25830-03).
As an alternative you can delete the existing copy of the package from the Nuget cache. For example on
Alternatively just delete the existing copy of the package from the Nuget cache. For example on
windows (on Linux substitute ~/ for %HOMEPATH%) you could delete
```bat
%HOMEPATH%\.nuget\packages\Microsoft.Private.CoreFx.NETCoreApp\4.4.0-beta-25102-0
%HOMEPATH%\.nuget\packages\Microsoft.Private.CoreFx.NETCoreApp\4.5.0-preview1-25830-0
%HOMEPATH%\.nuget\packages\runtime.win-x64.microsoft.private.corefx.netcoreapp\4.5.0-preview1-25830-0
```
which should make things work (but is fragile, confirm file timestamps that you are getting the version you expect)
which should make `dotnet restore` now pick up the new copy.
### Consuming individual library packages
The instructions above were only about updates to the binaries that are part of Microsoft.NETCore.App, if you want to test a package
for library that ships in its own nuget package you can follow the same steps above but instead add a package reference to the
individual library package from your `bin\packages\Debug` folder.
## Consuming non-NetStandard assets in a .NET Core 2.0 application
Currently if you reference a NuGet package that does not have a NETStandard asset in your .NET Core 2.0 application, you will hit package
incompatibility errors when trying to restore packages. You can resolve this issue by adding `PackageTargetFallback` property
(MSBuild equivalent of `imports`) to your .csproj:
```XML
<PackageTargetFallback>$(PackageTargetFallback);net45</PackageTargetFallback>
```
Note that this can fix the problem if the package is actually compatible with netcoreapp2.0 (meaning it does not use types/APIs
that are not available in netcoreapp2.0)
For final release, we are considering modifying NuGet behavior to automatically consume the non-netstandard asset if there is no netstandard available.
## Creating a .NET Core 2.0 console application from Visual Studio 2017
File > New > Project > Console App (.NET Core)
By default, Visual Studio creates a netcoreapp1.1 application. After installing the prerequisites mentioned above, you will
need to modify your .csproj to target netcoreapp2.0 and reference the nightly build of Microsoft.NETCore.APP
```XML
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.0</TargetFramework> <!-- this line -->
<RuntimeFrameworkVersion>2.0.0-beta-xyz-00</RuntimeFrameworkVersion> <!-- this line -->
</PropertyGroup>
```
In a future update to Visual Studio, it will no longer be necessary to make this edit.
## Finding specific builds
The URL scheme for the runtime is as follows:
```
https://dotnetcli.azureedge.net/dotnet/master/Installers/$version$/dotnet-$os$-$arch$.$version$.exe
https://dotnetcli.azureedge.net/dotnet/master/Installers/2.0.0-preview1-001915-00/dotnet-win-x64.2.0.0-preview1-001915-00.exe
```
The URL scheme for the SDK & CLI is as follows:
```
https://dotnetcli.azureedge.net/dotnet/Sdk/$version$/dotnet-dev-$os$-$arch.$version$.exe
https://dotnetcli.azureedge.net/dotnet/Sdk/2.0.0-preview1-005791/dotnet-dev-win-x86.2.0.0-preview1-005791.exe
```