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

Imported Upstream version 5.0.0.42

Browse Source 
Former-commit-id: fd56571888259555122d8a0f58c68838229cea2b
This commit is contained in:
Xamarin Public Jenkins (auto-signing)
2017-04-10 11:41:01 +00:00
parent 1190d13a04
commit 6bdd276d05
19939 changed files with 3099680 additions and 93811 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
external/corefx/Documentation/building/build-tests-against-packages.md vendored Normal file
View File

@@ -0,0 +1,52 @@
# Building Tests Against Packages
## Usage Scenarios
### Build the product locally and then test what you've built
In this scenario, you produce a product build, including packages, then generate test project.json's which reference the locally built package versions and finally build tests compiling against the local packages.
1. Build the product and packages
- ```Build.cmd -BuildTests=false```
2. Generate Test project.json files
- ```sync.cmd -t -- /p:"SkipCleanPackages=true" /p:"PackagesDrops=[ProjectDir]bin/packages/[Release|Debug]/"```
- /p:SkipCleanPackages=true is required for release branches where the packages folder is cleaned during every build.
3. Build Tests against packages
- ```build-tests.cmd -BuildTestsAgainstPackages -- /p:"PackagesDrops=[ProjectDir]bin/packages/[Release|Debug]/"```
- -BuildTestsAgainstPackages tells the build to use the project.json files you generated in the "Generate Test project.json files" step
- /p:"PackagesDrops=[ProjectDir]bin/packages/[Release|Debug]/" tells the build to use the packages from your local build drop.
### Download product from an Azure blob
This scenario skips the product build step, and instead downloads packages from Azure blob storage
1. Sync product from Azure
- ```sync.cmd -ab -AzureAccount=dotnetbuildoutput -AzureToken=******** -Container=[Azure container name] -- /p:"DownloadDirectory=[ProjectDir]Packages\AzureTransfer" /p:"SkipCleanPackages=true"```
2. Generate Test project.json files
- ```sync.cmd -t -- /p:"SkipCleanPackages=true" /p:"PackagesDrops=[ProjectDir]Packages/AzureTransfer/[Release|Debug]/"```
- /p:SkipCleanPackages=true is required for release branches where the packages folder is cleaned during every build.
3. Build Tests against packages
- ```build-tests.cmd -BuildTestsAgainstPackages -- /p:"PackagesDrops=[ProjectDir]Packages/AzureTransfer/[Release|Debug]/"```
- -BuildTestsAgainstPackages tells the build to use the project.json files you generated in the "Generate Test project.json files" step
- /p:"PackagesDrops=[ProjectDir]Packages/AzureTransfer/[Release|Debug]/" tells the build to use the packages from the Azure download (DownloadDirectory).
### Use a versions file for specifying package versions
This scenario uses a versions file (https://github.com/dotnet/versions/blob/master/build-info/dotnet/corefx/master/Latest_Packages.txt, for example) to determine what package versions to build tests against.
1. Generate Test project.json files using a 'versions' file.
- ```sync.cmd -t -- /p:"SkipCleanPackages=true" /p:"VersionsFiles=[local version file path]"```
- /p:SkipCleanPackages=true is required for release branches where the packages folder is cleaned during every build.
2. Build Tests against packages
- ```build-tests.cmd -BuildTestsAgainstPackages -- /p:"PackagesDrops=[ProjectDir]bin/packages/[Release|Debug]/"```
- -BuildTestsAgainstPackages tells the build to use the project.json files you generated in the "Generate Test project.json files" step
- /p:"PackagesDrops=[ProjectDir]bin/packages/[Release|Debug]/" tells the build to use the packages from your local build drop.
- If the package versions you are referencing have been published publically, you can omit the "PackagesDrops" property.
## Common Questions
- **How do I know it worked?** The best way is to look in the log for the compilation line ("csc.exe") and ensure that its references now point to packages (packages\blah) where previously they pointed to build product binaries (bin\blah).
- **Why are there build failures?** Not all of our tests build nicely against package references due to differences in the public surface area (compiling against the reference assembly versus an implementation assembly). In cases where we were unable to sync / restore (packages were unavailable or other restore problems), we've opted those projects out of this process by adding "KeepAllProjectReferences" or "KeepProjectReference" (added to a Project Reference's metadata) to the test project.
- **Where are the generated project.json files?** Generated project.json files get created under "[ProjectDir]bin/obj/generated".

84
external/corefx/Documentation/building/code-coverage.md vendored Normal file
View File

@@ -0,0 +1,84 @@
Code Coverage
=============
"Code coverage" is a measure that indicates how much of our library code is exercised by our test suites. We measure code coverage using the [OpenCover](https://github.com/opencover/opencover), and a report of our latest code coverage results can be seen by clicking the coverage badge on the [CoreFX home page](https://github.com/dotnet/corefx):
[![Coverage status](https://img.shields.io/badge/coverage-report-blue.svg)](http://dotnet-ci.cloudapp.net/job/dotnet_corefx_coverage_windows/lastBuild/Code_Coverage_Report/)
This report shows each library currently being tested with code coverage and provides statistics around the quality of the code coverage for the library. It also provides a line-by-line breakdown of what lines are being covered and what lines are not.
## Goals
The code coverage report provides a percentage value per library of the number of source lines exercised by the tests. There is no hard and fast percentage that must be obtained per library, as every library is unique and comes with its own set of intricacies and constraints. While in some cases it's possible and reasonable to achieve 100% code coverage, this is rare. There are many valid reasons certain pieces of code won't be exercised in tests, e.g.:
- A code file is compiled into multiple projects, and only some of the code is used in each project.
- Code exists to handle rare race conditions too costly to simulate in normal conditions.
- Code exists to handle particular machine/OS configurations that are not used during code coverage runs.
Etc. What's important is that the right set of tests exist to ensure that the code is behaving properly and that regressions in functionality can be caught quickly, and code coverage metrics are a way to help guide us to that end.
Our default, somewhat-arbitrary initial goal for a library is 90% code coverage. That doesn't mean we're done with testing once a library hits 90%, nor does it mean we must keep going with a library until it hits 90%. We use this metric and the associated coverage information to help guide us towards the ideal for a given library.
(Note that we do not want to arbitrarily inflate our code coverage numbers. Tests must provide value in and of themselves and should not simply be written in a haphazard manner meant to execute more lines of code without providing real value.)
## Issues
Issues are opened for a library when a cursory examination of its code coverage reveal that there are likely still some meaningful gaps that need to be addressed. We welcome contributions to our test suites to help address these gaps and close these issues. Many of these issues are marked as "up for grabs".
An issue need not be addressed in its entirety. We happily accept contributions that improve our tests and work towards improving code coverage numbers even if they only incrementally improve the situation.
## Automated Code Coverage Runs
Code coverage runs are performed by Jenkins approximately twice a day. The results of these runs are all available from the site linked to by the code coverage badge on the home page.
## Local Code Coverage Runs
You can perform code coverage runs locally on your own machine. Normally to build your entire CoreFX repo, from the root of your repo you'd run:
build
build-tests
To include code coverage in this run, augment the `build-tests` call with the `coverage` argument:
build
build-tests -coverage
This will do the build and testing as with the normal ```build```, but it will run the tests using the OpenCover tool. A resulting index.htm file providing the results of the run will be available at:
bin\tests\coverage\index.htm
You can also build and test with code coverage for a particular test project rather than for the whole repo. Normally to build and test a particular test suite, from the same directory as that test suite's .csproj, you'd run:
msbuild /t:BuildAndTest
To do so with code coverage, as with ```build``` append the ```/p:Coverage=true``` argument:
msbuild /t:BuildAndTest /p:Coverage=true
The results for this one library will then also show up in the aforementioned index.htm file. For example, to build, test, and get code coverage results for the System.Diagnostics.Debug library, from the root of my repo I can do:
cd src\System.Diagnostics.Debug\tests\
msbuild /t:BuildAndTest /p:Coverage=true
And then once the run completes:
..\..\..\bin\tests\coverage\index.htm
## Code coverage with mscorlib code
Some of the libraries for which contracts and tests live in the corefx repo are actually implemented in the core runtime library in another repo, e.g. the implementation that backs the System.Runtime contract is in System.Private.Corlib.dll in either the coreclr or corert repo. To run coverage reports for these projects, you need to build mscorlib locally from the coreclr repo.
The following steps can be used manually to produce a coverage report, but a customizable batch file can be found [here](facade-code-coverage.bat). Changing the parameters in the first couple of lines lets you run a coverage report easily for any facade project.
1. Build the local test project (`msbuild /T:Build`)
3. Build coreclr locally in Debug or Release (`build.cmd all Debug skiptests`)
2. Navigate to the built test directory in the corefx bin (e.g. `bin/tests/AnyOS.AnyCPU.Debug/System.Runtime/netcoreapp1.0` for `System.Runtime`
4. Delete `coreclr.dll`, `mscorlib.dll`, `mscorlib.ni.dll`, `System.Private.CoreLib.dll` and `System.Private.CoreLib.ni.dll` from that directory
5. Copy all files in the coreclr `bin` directory to the test directory
6. Copy all files in the coreclr `bin/PDB` directory to the test directory
7. Run an OpenCover command with `xunit.console.netcore.exe`. For example:
<corefx-root>/packages/OpenCover/<opencover-version>/tools/OpenCover.Console.exe -oldStyle -filter:"+[*]* -[*.Tests]* -[xunit.*]*" -excludebyfile:"*\Common\src\System\SR.*" -nodefaultfilters -excludebyattribute:*.ExcludeFromCodeCoverage* -skipautoprops -hideskipped:All -threshold:1 -returntargetcode -register:user -targetdir:<path-to corefx-bin> -target:CoreRun.exe -output:coverage.xml -targetargs:"xunit.console.netcore.exe System.Runtime.Tests -xml testResults.xml -notrait Benchmark=true -notrait category=OuterLoop -notrait category=failing -notrait category=nonwindowstests"
8. Run a ReportGenerator command with the generated `coverage.xml` file. For example:
<corefx-root>/packages/ReportGenerator/<opencover-version>/tools/ReportGenerator.exe -reporttypes:Html;Badges -reports:coverage.xml

105
external/corefx/Documentation/building/cross-building.md vendored Normal file
View File

@@ -0,0 +1,105 @@
Cross Compilation for ARM on Linux
==================================
It is possible to build CoreFx on Linux for arm, armel, or arm64 by cross compiling.
It is very similar to the cross compilation procedure of CoreCLR.
Requirements
------------
You need a Debian based host, and the following packages need to be installed:
lgs@ubuntu ~/git/corefx/ $ sudo apt-get install qemu qemu-user-static binfmt-support debootstrap
In addition, to cross compile CoreFX, the binutils for the target are required. So for arm you need:
lgs@ubuntu ~/git/corefx/ $ sudo apt-get install binutils-arm-linux-gnueabihf
for armel:
lgs@ubuntu ~/git/corefx/ $ sudo apt-get install binutils-arm-linux-gnueabi
and for arm64 you need:
lgs@ubuntu ~/git/corefx/ $ sudo apt-get install binutils-aarch64-linux-gnu
Generating the rootfs
---------------------
The `cross\build-rootfs.sh` script can be used to download the files needed for cross compilation. It will generate an Ubuntu 14.04 rootfs as this is what CoreFX targets.
Usage: ./cross/build-rootfs.sh [BuildArch] [UbuntuCodeName]
BuildArch can be: arm, armel, arm64, x86
UbuntuCodeName - optional, Code name for Ubuntu, can be: trusty(default), vivid, wily, xenial. If BuildArch is armel, jessie(default) or tizen.
The `build-rootfs.sh` script must be run as root, as it has to make some symlinks to the system. It will, by default, generate the rootfs in `cross\rootfs\<BuildArch>` however this can be changed by setting the `ROOTFS_DIR` environment variable.
For example, to generate an arm rootfs:
lgs@ubuntu ~/git/corefx/ $ sudo ./cross/build-rootfs.sh arm
and if you wanted to generate the rootfs elsewhere:
lgs@ubuntu ~/git/corefx/ $ sudo ROOTFS_DIR=/home/lgs/corefx-cross/arm ./build-rootfs.sh arm
Cross compiling for native CoreFX
---------------------------------
Once the rootfs has been generated, it will be possible to cross compile CoreFX. If `ROOTFS_DIR` was set when generating the rootfs, then it must also be set when running `build.sh`.
So, without `ROOTFS_DIR`:
lgs@ubuntu ~/git/corefx/ $ ./build-native.sh -debug -buildArch=arm -- verbose cross
And with:
lgs@ubuntu ~/git/corefx/ $ ROOTFS_DIR=/home/lgs/corefx-cross/arm ./build-native.sh -debug -buildArch=arm -- verbose cross
As usual the generated binaries will be found in `bin/BuildOS.BuildArch.BuildType/native` as following:
lgs@ubuntu ~/git/corefx/ ls -al ./bin/Linux.arm.Debug/native
total 988
drwxrwxr-x 2 lgs lgs 4096 3 6 18:33 .
drwxrwxr-x 3 lgs lgs 4096 3 6 18:33 ..
-rw-r--r-- 1 lgs lgs 19797 3 6 18:33 System.IO.Compression.Native.so
-rw-r--r-- 1 lgs lgs 428232 3 6 18:33 System.Native.a
-rw-r--r-- 1 lgs lgs 228279 3 6 18:33 System.Native.so
-rw-r--r-- 1 lgs lgs 53089 3 6 18:33 System.Net.Http.Native.so
-rw-r--r-- 1 lgs lgs 266720 3 6 18:33 System.Security.Cryptography.Native.so
lgs@ubuntu ~/git/corefx/ file ./bin/Linux.arm.Debug/native/System.Native.so
./bin/Linux.arm.Debug/native/System.Native.so:
ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV),
dynamically linked, BuildID[sha1]=fac50f1bd657c1759f0ad6cf5951511ddf252e67, not stripped
Compiling for managed CoreFX
============================
The managed components of CoreFX are architecture-independent and thus do not require a special build for arm, armel or arm64.
Many of the managed binaries are also OS-independent, e.g. System.Linq.dll, while some are OS-specific, e.g. System.IO.FileSystem.dll, with different builds for Windows and Linux.
lgs@ubuntu ~/git/corefx/ $ ./build-managed.sh -debug -verbose
The output is at `bin/[BuildConfiguration]` where `BuildConfiguration` looks something like `netcoreapp-<OSGroup>-Debug-<Architecture>`. Ex: `bin/netcoreapp-Linux-Debug-x64`. For more details on the build configurations see [project-guidelines](../coding-guidelines/project-guidelines.md)
Building corefx for Linux ARM Emulator
=======================================
It is possible to build corefx binaries (native and managed) for the Linux ARM Emulator (latest version provided here: [#3805](https://github.com/dotnet/coreclr/issues/3805)).
The `scripts/arm32_ci_script.sh` script does this.
The following instructions assume that:
* You have set up the extracted emulator at `/opt/linux-arm-emulator` (such that `/opt/linux-arm-emulator/platform/rootfs-t30.ext4` exists)
* The mount path for the emulator rootfs is `/opt/linux-arm-emulator-root` (change this path if you have a working directory at this path).
All the following instructions are for the Release mode. Change the commands and files accordingly for the Debug mode.
To just build the native and managed corefx binaries for the Linux ARM Emulator, run the following command:
```
prajwal@ubuntu ~/corefx $ ./scripts/arm32_ci_script.sh \
--emulatorPath=/opt/linux-arm-emulator \
--mountPath=/opt/linux-arm-emulator-root \
--buildConfig=Release
```
The Linux ARM Emulator is based on the soft floating point and thus the native binaries are generated for the armel architecture. The corefx binaries generated by the above command can be found at `~/corefx/bin/Linux.armel.Release`, `~/corefx/bin/Linux.AnyCPU.Release`, `~/corefx/bin/Unix.AnyCPU.Release`, and `~/corefx/bin/AnyOS.AnyCPU.Release`.

72
external/corefx/Documentation/building/cross-platform-testing.md vendored Normal file
View File

@@ -0,0 +1,72 @@
# Running XUnit tests cross platform
Unlike Windows, where we run tests as part of the build, we have a seperate
explicit testing step on Linux and OSX. Over time, this special step will go
away in favor of a similar "run tests during the build" model.
`run-test.sh` is the shell script used by Jenkins in order to run all the XUnit
tests cross platform. It combines the cross platform CoreCLR and CoreFX builds
together into a test layout and then runs each test project from CoreFX.
In order to run tests, you need to build a bunch of different projects. The
instructions assume you are building for Linux, but are easily modifiable for OSX.
1. Release or debug CoreCLR. In Jenkins we use a release CoreCLR build instead
of debug CoreCLR since it is much faster at actually running XUnit, but debug
will work if you have the time.
From the root of your CoreCLR enlistment on Linux, run `./build.sh Release` in
order to build.
2. A corresponding version of mscorlib.dll. Depending on your platform, this may
be produced when you run `build.sh`. Otherwise, this can be produced by
running `build.cmd linuxmscorlib Release` from a CoreCLR enlistment on
Windows. Remember that the runtime and mscorlib are tightly coupled with
respect to object sizes and layout so you need to ensure you have either a
release coreclr and release mscorlib or debug coreclr and debug mscorlib.
3. A Linux build of CoreFX. We currently have experimental support for building
CoreFX on Linux via `build.sh`.
The other option is:
* Build the managed parts of CoreFX on Windows. To do so run `build-managed.cmd -os=Linux`. It is okay to build a Debug version of CoreFX and run it
on top of a release CoreCLR (which is exactly what we do in Jenkins).
* Build the native parts of CoreFX on Linux. To do so run `./build-native.sh` from the root of your CoreFX enlistment.
4. The packages folder which contains all the packages restored from NuGet and
MyGet when building CoreFX.
After building all the projects, we need to copy any of the files we built on Windows
over to our Linux machine. The easiest way to do this is to mount a windows
share on linux. For example, I do:
```
# sudo mount.cifs "//MATELL3/D\$" ~/mnt/matell3/d -o user=matell
```
If needed, copy CoreFX:
```
# rsync -v -r ~/mnt/matell3/d/git/corefx/bin/tests ~/git/corefx/bin/tests
```
If needed, copy the packages folder:
```
# rsync -v -f ~/mnt/matell3/d/git/corefx/packages ~/git/corefx/packages
```
If needed, copy mscorlib:
```
# rsync -v -r ~/mnt/matell3/d/git/coreclr/bin/Product/ ~/git/coreclr/bin/Product/
```
Then, run the tests. We need to pass an explict path to the location of CoreCLR
and mscorlib.dll.
```
# ./run-test.sh --coreclr-bins ~/git/coreclr/bin/Product/Linux.x64.Release \
--mscorlib-bins ~/git/coreclr/bin/Product/Linux.x64.Release \
```
run-test.sh should now invoke all the managed tests.

82
external/corefx/Documentation/building/facade-code-coverage.bat vendored Normal file
View File

@@ -0,0 +1,82 @@
@echo off
:: Example settings for System.Runtime
SET project=System.Runtime
SET msbuildargs=/T:Build
SET testsubdir=AnyOS.AnyCPU.Debug
SET filter="+[*]* -[*.Tests]* -[*]System.Collections.* -[*]System.Diagnostics.* -[*]System.Globalization.* -[*]System.IO.* -[*]System.Reflection.* -[*]System.Resources.* -[*]System.Runtime.* -[*]System.Security.* -[*]System.StubHelpers.* -[*]System.Threading.* -[*]Microsoft.* -[*]Windows.* -[*]System.App* -[*]System.Text.Decoder* -[*]System.Text.Encoder* -[*]System.Text.*Encoding -[*]System.Text.Internal* -[xunit.*]*"
:: Update this when OpenCover or ReportGenerator are updated
SET opencoverversion=4.6.519
SET reportgeneratorversion=2.4.3
:: Assumes that the corefx and coreclr repo folders are in the same parent folder
SET root=C:\Users\Hugh\Documents\Github
SET corefx=%root%\corefx
SET coreclr=%root%\coreclr
SET packages=%corefx%\packages
SET opencover=%packages%\OpenCover\%opencoverversion%\tools\OpenCover.Console.exe
SET reportgenerator=%packages%\ReportGenerator\%reportgeneratorversion%\tools\ReportGenerator.exe
SET targetdir=%corefx%\bin\tests\%testsubdir%\%project%.Tests\netcoreapp1.0
SET resultsfile=testresults.xml
SET coveragefile=coverage.xml
SET coveragedir=coverage
SET originalfolder=%cd%
SET sourcefolder=%corefx%\src\%project%\tests
SET coreclrbuild=%coreclr%\bin\Product\Windows_NT.x64.Debug
SET coreclrbuild=%coreclr%\bin\Product\Windows_NT.x64.Release
:: Build the library
cd %sourcefolder%
msbuild %msbuildargs%
cd %originalfolder%
:: Delete old files (see #8381 for why)
del %targetdir%\mscorlib.dll
del %targetdir%\mscorlib.ni.dll
del %targetdir%\System.Private.CoreLib.dll
del %targetdir%\System.Private.CoreLib.ni.dll
del %targetdir%\coreclr.dll
del %targetdir%\CoreRun.exe
del %targetdir%\CoreConsole.exe
del %targetdir%\clretwrc.dll
del %targetdir%\clrjit.dll
del %targetdir%\dbgshim.dll
del %targetdir%\mscordaccore.dll
del %targetdir%\mscordbi.dll
del %targetdir%\mscorrc.debug.dll
del %targetdir%\mscorrc.dll
del %targetdir%\sos.dll
:: Copy over our local build files
For %%a in (
%coreclrbuild%\mscorlib.dll
%coreclrbuild%\PDB\mscorlib.pdb
%coreclrbuild%\System.Private.CoreLib.dll
%coreclrbuild%\PDB\System.Private.CoreLib.pdb
%coreclrbuild%\coreclr.dll
%coreclrbuild%\PDB\coreclr.pdb
%coreclrbuild%\CoreRun.exe
%coreclrbuild%\CoreConsole.exe
%coreclrbuild%\clretwrc.dll
%coreclrbuild%\clrjit.dll
%coreclrbuild%\dbgshim.dll
%coreclrbuild%\mscordaccore.dll
%coreclrbuild%\mscordbi.dll
%coreclrbuild%\mscorrc.debug.dll
%coreclrbuild%\mscorrc.dll
%coreclrbuild%\sos.dll
) do copy /b/v/y "%%~a" "%targetdir%\"
:: Now, run the actual tests and generate a coverage report
SET corerunargs=%targetdir%\xunit.console.netcore.exe %project%.Tests.dll -xml %resultsfile% -notrait category=OuterLoop -notrait category=failing -notrait category=nonwindowstests
%opencover% -oldStyle -filter:%filter% -excludebyfile:"*\Common\src\System\SR.*" -nodefaultfilters -excludebyattribute:*.ExcludeFromCodeCoverage* -skipautoprops -hideskipped:All -threshold:1 -returntargetcode -register:user -targetdir:%targetdir% -target:CoreRun.exe -output:%coveragefile% -targetargs:"%corerunargs%"
%reportgenerator% -targetdir:%coveragedir% -reporttypes:Html;Badges -reports:%coveragefile% -verbosity:Error

105
external/corefx/Documentation/building/unix-instructions.md vendored Normal file
View File

@@ -0,0 +1,105 @@
Building CoreFX on FreeBSD, Linux and OS X
==========================================
##Building
1. Install the prerequisites ([Linux](#user-content-linux), [macOS](#user-content-macos))
2. Clone the corefx repo `git clone https://github.com/dotnet/corefx.git`
3. Navigate to the `corefx` directory
4. Run the build script `./build.sh`
Calling the script `build.sh` builds both the native and managed code.
Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native.sh` and `build-managed.sh` respectively.
For more information about the different options when building, run `build.sh -?` and look at examples in the [developer-guide](../project-docs/developer-guide.md).
## Minimum Hardware Requirements
- 2GB RAM
## Prerequisites (native build)
### Linux
#### Native build
For Ubuntu 14.04, the following packages should be installed to build the native
components
* git
* clang-3.5
* cmake
* make
* libc6-dev
* libssl-dev
* libkrb5-dev
* libcurl4-openssl-dev
* zlib1g-dev
`sudo apt-get install git clang-3.5 cmake make libc6-dev libssl-dev libkrb5-dev
libcurl4-openssl-dev zlib1g-dev`
#### Managed build
For Ubuntu 14.04, install the following packages:
* libunwind8
* libicu52
* curl
`sudo apt-get install libunwind8 libicu52 curl`
For Ubuntu 16.04 LTS / Bash on Ubuntu on Windows you may need to replace libicu52 with libicu55. Ubuntu 16.10 will require libcu57.
`sudo apt-get install libunwind8 libicu55 curl`
In addition to the above packages, the runtime versions of the packages listed
in the native section should also be installed (this happens automatically on
most systems when you install the development packages).
### macOS
On macOS a few components are needed which are not provided by a default developer setup:
* CMake
* pkgconfig
* OpenSSL 1.0.1 or 1.0.2
One way of obtaining these components is via [Homebrew](http://brew.sh):
```sh
$ brew install cmake pkgconfig openssl
```
As of El Capitan (OS X 10.11), Apple still has the libraries for OpenSSL 0.9.8 in `/usr/lib`,
but the headers are no longer available since that library version is out of support.
Some compilers get upset over new headers being in `/usr/local/include` with the old library being present at
`/usr/lib/libcrypto.dylib` (the tools have no issue with the versioned files, e.g. `/usr/lib/libcrypto.0.9.8.dylib`),
and so Homebrew does not allow the OpenSSL package to be installed into system default paths. A minimal installation
is presented here to facilitiate simplifying runtime requirements and compile-time requirements (for build systems using
CMake's `find_package`, like ours):
```sh
# We need to make the runtime libraries discoverable, as well as make
# pkg-config be able to find the headers and current ABI version.
#
# Ensure the paths we will need exist
mkdir -p /usr/local/lib/pkgconfig
# The rest of these instructions assume a default Homebrew path of
# /usr/local/opt/<module>, with /usr/local being the answer to
# `brew --prefix`.
#
# Runtime dependencies
ln -s /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib /usr/local/lib/
ln -s /usr/local/opt/openssl/lib/libssl.1.0.0.dylib /usr/local/lib/
# Compile-time dependencies (for pkg-config)
ln -s /usr/local/opt/openssl/lib/pkgconfig/libcrypto.pc /usr/local/lib/pkgconfig/
ln -s /usr/local/opt/openssl/lib/pkgconfig/libssl.pc /usr/local/lib/pkgconfig/
ln -s /usr/local/opt/openssl/lib/pkgconfig/openssl.pc /usr/local/lib/pkgconfig/
```
### Known Issues
If you see errors along the lines of `SendFailure (Error writing headers)` you may need to import trusted root certificates:
```sh
mozroots --import --sync
```
Bash on Ubuntu on Windows issues are tracked by: [#11057](https://github.com/dotnet/corefx/issues/11057)

60
external/corefx/Documentation/building/versioning.md vendored Normal file
View File

@@ -0,0 +1,60 @@
Package and File Versioning
===========================
We have now added package versioning and assembly file versioning when building the repo. This versioning works in both Windows and non-Windows platforms. Also, this versioning applies for both the managed and native libraries we produce. We had a few constraints to take into account, for example:
- Version needed to be higher than the versions that we have already shipped.
- There needs to be an ability to have multiple versions per day.
- Versions need to be always increasing.
- Version needs to be lower than 65535(unsigned short int max) since the version is used as assembly file version which has that constraint.
- Version needs to be reproducible.
- (Nice to have) We shouldn't have the need to check in a file containing the version or revision number.
Taking into account all these constraints we came up with the new versioning. The version is calculated per build by [a targets file that lives in buildtools](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks/PackageFiles/versioning.targets), and depending on what we are building(native/managed, Windows/non-Windows) it will generate versioning assets that will be used during the build to be able to produce build output with the right versions.
How is the version calculated
=============================
The version is composed by two parts; the build number major and the build number minor. An example looks something like 00001.01, where the first five digits represent the build number major, and the two last digits after the dot represent the build number minor.
Calculating BuildNumberMajor
----------------------------
The BuildNumberMajor is represented by 5 digits, and is determined by calculating the time that has happened between the latest commit's date(SeedDate) and a VersionComparisonDate that gets passed in. In the case where VersionComparisonDate is not passed in, we will use April 1st 1996 as default. The reason why we use this specific date, is to ensure that the version produced by SeedDate is higher than the already shipped versions of the same library. The first portion of the BuildNumberMajor (first 3 digits) represent the number of month(s) since the VersionComparisonDate. The second portion of the BuildNumberMajor (last 2 digits) represent the day of the month of SeedDate. This part of the version is reproducible.
Calculating BuildNumberMinor
----------------------------
The BuildNumberMinor represent the build # of the day this version is. This number increases by 1, and it starts in 01. Given that there is no way for a dev machine to know how many builds have happened that day, this number is calculated by our VSO official builds and needs to be passed in. Since dev builds usually don't have a BuildNumberMinor (unless it's passed in manually), they will always have a BuildNumberMinor=0. For example, a Official build version would look something like `00001.01` while a dev build version will look like `00001.0`
Packages Version
----------------
In the case of packages, there is one small difference compared to the assembly file version, which is the separator of BuildNumberMajor and BuildNumberMinor. As noted above, for assembly file version we use a dot `.` to separate these two numbers, but for packages we use a dash `-`. This is due to the different requirements that package names and file versions have. For example, the package version of file 'mylibrary.dll - version 00001.01' would be `mylibrary.1.0.0-prerelease-00001-01.nupkg`
How does the Official Build workflow works
------------------------------------------
Our Official Builds are a little different than the regular dev flow, and that is because Official Builds need the ability to not only force a specific BuildNumberMinor, but also a BuildNumberMajor. The way they do it, is by passing in the parameter `OfficialBuildId` which specifies the SeedDate that should be used and the revision of the build. For example, the following invocation: `build.cmd -OfficialBuildId=20160523.99` will use May 23 2016 as the SeedDate to generate the version, and it will set '99' as the BuildNumberMinor. With this funcionality, our OfficialBuilds are able to have an orchestrator that triggers different builds and force all of them to have the same version.
Getting the version of a native binary in non-Windows platforms
========================================================
When trying to get a version of a native binary in non-Windows, there are two ways to do it:
- Using the Linux tool `sccs what(1)` by installing the tool (if it doesn't come by default with the OS) and then running something like `what myNativeNonWindowsBinary.so`. For more information on the tool, [click here](https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.cmds6/what.htm)
- The other way to do it if you don't want to install additional tools, is by using `strings+grep`, and the way to do it is by running `strings myNativeNonWindowsBinary.so | grep "@(#)"`
How to force a dev build to produce a specific version
======================================================
If you need to manually specify the version you want to produce your build output with, you can accomplish this by running the following from the root of the repo:
- `build-managed.cmd -BuildNumberMajor=00001 -BuildNumberMinor=01` in Windows
- `build-managed.sh -BuildNumberMajor=00001 -BuildNumberMinor=01` in non-Windows
Where is the version being consumed
===================================
The version we produce by our calculations is mainly used in two places:
- As the [Assembly File Version](https://msdn.microsoft.com/en-us/library/51ket42z(v=vs.110).aspx)
- As the packages version number
To get more information on where are we doing the calculations for the versioning, you can [click here](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks/PackageFiles/versioning.targets) to find the targets file where we create the versioning assets, and [here](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks/GenerateCurrentVersion.cs) to see the code on where we calculate BuildNumberMajor and BuildNumberMinor.

60
external/corefx/Documentation/building/windows-instructions.md vendored Normal file
View File

@@ -0,0 +1,60 @@
Building CoreFX on Windows
==========================
You can build .NET Core either via the command line or by using Visual Studio.
## Required Software
Visual Studio 2015 is required.
The following free downloads are compatible:
* [Visual Studio Community 2015](http://www.visualstudio.com/en-us/downloads/visual-studio-2015-downloads-vs)
Note: In order to build our C++ projects be sure to select "Programming Languages | Visual C++ | Common Tools for Visual C++ 2015" while installing VS 2015 (or modify your install to include it).
We also require that [Visual Studio 2015 Update 1](https://www.visualstudio.com/en-us/news/vs2015-update1-vs.aspx) be installed.
[CMake](https://cmake.org/) is required to build the native libraries for Windows. To build these libraries cmake must be installed from [the CMake download page](https://cmake.org/download/) and added to your path.
## Building From the Command Line
Open a [Visual Studio Command Prompt](http://msdn.microsoft.com/en-us/library/ms229859(v=vs.110).aspx).
- `build.cmd` - Will cause basic tool initialization and build the default configuration for refs, libs, and packages.
- `build-tests.cmd` - Will build and run tests for the default configuration.
For information on different configurations see [project-guidelines](../coding-guidelines/project-guidelines.md).
**Note**: Before working on individual projects or test projects you **must** run `build.cmd` from the root once before beginning that work. It is also a good idea to run `build.cmd` whenever you pull a large set of unknown changes into your branch.
Visual Studio Solution (.sln) files exist for related groups of libraries. These can be loaded to build, debug and test inside
the Visual Studio IDE.
Note that when calling the script `build.cmd` attempts to build both the native and managed code.
Only use it when the parameters that you are passing to the script apply for both components. Otherwise, use the scripts `build-native.cmd` and `build-managed.cmd` respectively.
For more information about the different options when building, run `build.cmd -?` and look at examples in the [developer-guide](../project-docs/developer-guide.md).
### Running tests from Visual Studio
1. Open solution of interest
2. Right click test project and select 'Set as startup project'
3. Ctrl+F5 (Run)
### Debugging tests in Visual Studio
1. Install VS 2015 Preview or later including Web Developer Tools
2. Open solution of interest in VS 2015
3. Right click test project and select 'Set as startup project'
4. Set breakpoint appropriately
5. F5 (Debug)
For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/debugging/windows-instructions.md)
### Notes
* Running tests from using the VS test explorer does not currently work after we switched to running on CoreCLR. [We will be working on enabling full VS test integration](https://github.com/dotnet/corefx/issues/1318) but we don't have an ETA yet. In the meantime, use the steps above to launch/debug the tests using the console runner.
* VS 2015 is required to debug tests running on CoreCLR as the CoreCLR
debug engine is a VS 2015 component.
* If the Xamarin PCL profiles are installed, the build will fail due to [issue #449](https://github.com/dotnet/corefx/issues/449). A possible workaround is listed [in the issue](https://github.com/dotnet/corefx/issues/449#issuecomment-95117040) itself.