Merge pull request dotnet#10359 from maririos/documentation

Update documentation on how to build CoreFx
gokarnm · Jul 28, 2016 · a6e95d3 · a6e95d3
2 parents d349984 + b465208
commit a6e95d3
Show file tree

Hide file tree

Showing 7 changed files with 265 additions and 207 deletions.
diff --git a/Documentation/building/code-coverage.md b/Documentation/building/code-coverage.md
@@ -36,9 +36,9 @@ You can perform code coverage runs locally on your own machine.  Normally to bui
 
     build
 
-To include code coverage in this run, augment it with the ```/p:Coverage=true``` argument:
+To include code coverage in this run, augment it with the `coverage` argument:
 
-    build /p:Coverage=true
+    build -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:
 

diff --git a/Documentation/building/cross-platform-testing.md b/Documentation/building/cross-platform-testing.md
@@ -24,13 +24,15 @@ instructions assume you are building for Linux, but are easily modifiable for OS
    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 to build the managed
-   parts of CoreFX on Windows, To do so run `build.cmd /p:TargetOS=Linux
-   /p:OSGroup=Linux`. It is okay to build a Debug version of CoreFX and run it
+   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 -target-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).
-4. A Linux build of the native CoreFX components. On Linux, run `./build.sh native` from
-   the root of your CoreFX enlistment.
-5. The packages folder which contains all the packages restored from NuGet and
+
+   * 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.
 
 

diff --git a/Documentation/building/unix-instructions.md b/Documentation/building/unix-instructions.md
@@ -1,21 +1,12 @@
 Building CoreFX on FreeBSD, Linux and OS X
 ==========================================
+###Building
+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.
 
-The CoreFX build has two logical components, the native build which produces the
-"shims" (which provide a stable interface between the OS and managed code) and
-the managed build which produces the MSIL code and nuget packages that make up
-CoreFX.
+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).
 
-The native component should be buildable on any system, but the managed
-components require a version of the .NET Core CLI (which the build will
-download) so managed components can only be built on a subset of distros.
-
-### Prerequsites (native build)
-
-The native build produces shims over libc, openssl, gssapi, libcurl and
-libz. The build system uses CMake (2.8.12 or higher) to generate Makefiles using
-clang (3.5 or higher).  The build also uses git for generating some version
-information.
+### Prerequisites (native build)
 
 For Ubuntu 14.04, the following packages should be installed to build the native
 components
@@ -45,19 +36,12 @@ brew link --force openssl
 Once installed, the native components can be built by running:
 
 ```bash
-./build.sh native
+./build-native.sh
 ```
 
-from the root of the repository
+from the root of the repository.
 
-### Prerequsites (managed build)
-
-Since the managed build uses the .NET Core CLI, there are some additional
-pre-requesties from the CLI which need to be installed. Both libicu and
-libunwind are used by CoreCLR to execute managed code, so they must be
-installed. Since CoreFX does not actually link against these packages, runtime
-versions are sufficent.  We also require curl to be present, which we use to
-download the .NET Core CLI.
+### Prerequisites (managed build)
 
 For Ubuntu 14.04, install the following packages:
 
@@ -67,49 +51,18 @@ For Ubuntu 14.04, install the following packages:
 
 `sudo apt-get install libunwind8 libicu52 curl`
 
-In addition to the above pacakges, the runtime versions of the packages listed
+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).
 
-On OS X, we also require that openssl has been installed via Homebrew.
+On OS X, we also require that openssl has been installed via [Homebrew](http://brew.sh).
 
 Once installed, the managed components can be built by running:
 
 ```bash
-./build.sh managed
+./build-managed.sh
 ```
 
-### `build.sh` Usage
-When run without any arguments, `build.sh` will attempt to build both the native
-and managed code.
-
-There many flags that can be passed to `build.sh` to control its behavior.
-
-`./build.sh [managed] [native] [BuildArch] [BuildType] [clean] [verbose] [clangx.y] [platform] [cross] [skiptests] [cmakeargs]`
-
-**Example:**
-
-`./build.sh native x64 verbose clang3.9`
-
-**Options:**
-
-```bash
-managed            # optional argument to build the managed code
-native             # optional argument to build the native code
-platform           # OS to compile for (FreeBSD, Linux, NetBSD, OSX, Windows)
-skiptests          # build, but do not run, the managed unit tests
-BuildType          # build configuration type (Debug, Release)
-
-# The following arguments affect native builds only:
-
-BuildArch          # build architecture (x64, x86, arm, arm64)
-clean              # optional argument to force a clean build
-verbose            # optional argument to enable verbose build output
-clangx.y           # optional argument to build using clang version x.y
-cross              # optional argument to signify cross compilation, uses ROOTFS_DIR environment variable if set
-cmakeargs          # user-settable additional arguments passed to CMake
-
-```
 ### Known Issues
 If you see errors along the lines of `SendFailure (Error writing headers)` you may need to import trusted root certificates:
 

diff --git a/Documentation/building/versioning.md b/Documentation/building/versioning.md
@@ -34,7 +34,7 @@ In the case of packages, there is one small difference compared to the assembly
 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 /p: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.
+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
 ========================================================
@@ -47,8 +47,8 @@ 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.cmd /p:BuildNumberMajor=00001 /p:BuildNumberMinor=01` in Windows
-- `build.sh /p:BuildNumberMajor=00001 /p:BuildNumberMinor=01` in non-Windows
+- `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
 ===================================

diff --git a/Documentation/building/windows-instructions.md b/Documentation/building/windows-instructions.md
@@ -2,8 +2,6 @@ Building CoreFX on Windows
 ==========================
 
 You can build .NET Core either via the command line or by using Visual Studio.
-We currently only support building and running on Windows. Other platforms will
-come later.
 
 ## Required Software
 
@@ -21,121 +19,16 @@ We also require that [Visual Studio 2015 Update 1](https://www.visualstudio.com/
 ## Building From the Command Line
 
 Open a [Visual Studio Command Prompt](http://msdn.microsoft.com/en-us/library/ms229859(v=vs.110).aspx).
-From the root of the repository, type `build`. This will build everything and run
-the core tests for the project. 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.
-
-### Building individual DLLs of the CoreFX
-
-Under the src directory is a set of directories, each of which represents a particular assembly in CoreFX.  
-For example the src\System.Diagnostics.DiagnosticSource directory holds the source code for the System.Diagnostics.DiagnosticSource.dll assembly. Each of these directories includes two projects, one for the DLL being built and one for the tests, both specified by a .builds file.
-You can build the DLL for System.Diagnostics.DiagnosticSource.dll by going to the src\System.Diagnostics.DiagnosticsSource\src directory and typing `msbuild System.Diagnostics.DiagnosticSource.builds`. The DLL ends up as  bin\AnyOS.AnyCPU.Debug\System.Diagnostics.DiagnosticSource\System.DiagnosticSource.dll.
-You can build the tests for System.Diagnostics.DiagnosticSource.dll by going to 
-src\System.Diagnostics.DiagnosticSource\tests and typing `msbuild System.Diagnostics.DiagnosticSource.Tests.builds`.
-
-There is also a pkg directory for each project, and if you go into it and type `msbuild`, it will build the DLL (if needed)
-and then also build the NuGet package for it. The NuGet package ends up in the bin\packages directory.  
-
-### Building other OSes
-
-By default, building from the root will only build the libraries for the OS you are running on. One can
-build for another OS by specifying `/p:FilterToOSGroup=[Windows_NT|Linux|OSX|FreeBSD]` or build for all by specifying
-`/p:BuildAllOSGroups=true`.
-
-[Building CoreFX on FreeBSD, Linux and OS X](unix-instructions.md)
-
-### Building in Release or Debug
-
-By default, building from the root or within a project will build the libraries in Debug mode. One can build in Debug or Release mode by specifying `/p:ConfigurationGroup=[Debug|Release]` after the `msbuild` command.
-
-### Building other Architectures
-
-One can build 32 or 64 bit binaries or for any architecture by specifying `/p:Platform=[x86|x64|AnyCPU]` after the `msbuild` command.
-
-## Tests
-
-We use the OSS testing framework [xunit](http://xunit.github.io/).
-
-### Running tests on the command line
-
-By default, the core tests are run as part of the build. Running the tests from
-the command line is as simple as invoking `build.cmd` on windows, and `run-test.sh` on linux and osx.
-
-You can also run the tests for an individual project by building it individually, e.g.:
-
-```
-cd src\System.Collections.Immutable\tests
-msbuild /t:BuildAndTest (or /t:Test to just run the tests if the binaries are already built)
-```
-
-It is possible to pass parameters to the underlying xunit runner via the `XunitOptions` parameter, e.g.:
-```cmd
-msbuild /t:Test "/p:XunitOptions=-class Test.ClassUnderTests"
-```
+From the root of the repository, type `build.cmd`. This will build everything and run
+the core tests for the project. 
 
-There may be multiple projects in some directories so you may need to specify the path to a specific test project to get it to build and run the tests.
-
-Tests participate in the incremental build.  This means that if tests have already been run, and inputs to the incremental build have not changed, rerunning the tests target will not execute the test runner again.  To force re-executing tests in this situation, use `msbuild /t:clean;build;test`.
-
-The tests can also be filtered based on xunit trait attributes defined in [`xunit.netcore.extensions`](https://github.com/dotnet/buildtools/tree/master/src/xunit.netcore.extensions). These attributes are to be specified over the test method. The available attributes are:
-
-_**`OuterLoop`:**_
-Tests marked as ```Outerloop``` are for scenarios that don't need to run every build. They may take longer than normal tests, cover seldom hit code paths, or require special setup or resources to execute. These tests are excluded by default when testing through msbuild but can be enabled manually by adding the  ```/p:Outerloop=true``` property e.g. 
-
-```cmd
-build.cmd *.csproj /p:Outerloop=true
-```
-
-To run <b>only</b> the Outerloop tests, use the following command:
-```cmd
-xunit.console.netcore.exe *.dll -trait category=outerloop
-build.cmd *.csproj /p:WithCategories=OuterLoop
-```
-
-_**`PlatformSpecific(Xunit.PlatformID platforms)`:**_
-Use this attribute on test methods to specify that this test may only be run on the specified platforms. This attribute returns the following categories based on platform
-
-       - `nonwindowstests`: for tests that don't run on Windows
-       - `nonlinuxtests`: for tests that don't run on Linux
-       - `nonosxtests`: for tests that don't run on OS X
-
-To run Linux specific tests on a Linux box, use the following commandline,
-```sh
-xunit.console.netcore.exe *.dll -notrait category=nonlinuxtests
-```
-
-_**`ActiveIssue(int issue, Xunit.PlatformID platforms)`:**_
-Use this attribute over tests methods, to skip failing tests only on the specific platforms, if no platforms is specified, then the test is skipped on all platforms. This attribute returns the 'failing' category, so to run all acceptable tests on Linux that are not failing, use the following commandline,
-```sh
-xunit.console.netcore.exe *.dll -notrait category=failing -notrait category=nonlinuxtests
-```
-
-And to run all Linux-compatible tests that are failing,
-```sh
-xunit.console.netcore.exe *.dll -trait category=failing -notrait category=nonlinuxtests
-```
-
-_**A few common examples with the above attributes:**_
+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.
 
-- Run all tests acceptable on Windows
-```cmd
-xunit.console.netcore.exe *.dll -notrait category=nonwindowstests
-```
-- Run all inner loop tests acceptable on Linux
-```sh
-xunit.console.netcore.exe *.dll -notrait category=nonlinuxtests -notrait category=OuterLoop
-```
-- Run all outer loop tests acceptable on OS X that are not currently associated with active issues
-```sh
-xunit.console.netcore.exe *.dll -notrait category=nonosxtests -trait category=OuterLoop -notrait category=failing
-```
-- Run all tests acceptable on Linux that are currently associated with active issues
-```sh
-xunit.console.netcore.exe *.dll -notrait category=nonlinuxtests -trait category=failing
-```
+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.
 
-All the required dlls to run a test project can be found in `bin\tests\{Configration}\{Project}.Tests\netcoreapp1.0\` which should be created when the test project is built.
+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
 
@@ -153,22 +46,6 @@ All the required dlls to run a test project can be found in `bin\tests\{Configra
 
 For advanced debugging using WinDBG see [Debugging CoreFX on Windows](https://github.com/dotnet/corefx/blob/master/Documentation/debugging/windows-instructions.md)
 
-### Code Coverage
-
-Code coverage is built into the corefx build system.  It utilizes OpenCover for generating coverage data and ReportGenerator for generating reports about that data.  To run:
-
-```cmd
-// Run full coverage
-build.cmd /p:Coverage=true
-
-// To run a single project with code coverage enabled pass the /p:Coverage=true property
-cd src\System.Collections.Immutable\tests
-msbuild /t:BuildAndTest /p:Coverage=true
-```
-If coverage succeeds, the code coverage report will be generated automatically and placed in the bin\tests\coverage directory.  You can view the full report by opening index.htm
-
-Code coverage reports from the continuous integration system are available from the links on the front page of the corefx repo.
-
 ### 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.