mirror of
https://github.com/VSadov/Satori.git
synced 2025-06-10 18:11:04 +09:00
Documentation refinements (#1738)
* Documentation refinements * Fix a formatting issue * Code review updates
This commit is contained in:
Bruce Forstall
parent
74ad73e1f0
commit
247c5b96a2
GPG key ID:
4AEE18F83AFDEB23
5 changed files with 98 additions and 48 deletions
|
|
@ -12,18 +12,34 @@ The repo can be built for the following platforms, using the provided setup and
|
|||
| ARM64 | ✔ | ✔ | | |
|
||||
| | [Requirements](requirements/windows-requirements.md) | [Requirements](requirements/linux-requirements.md) | [Requirements](requirements/macos-requirements.md) |
|
||||
|
||||
Before proceeding further, please click on the link above that matches your machine and ensure you have installed all the pre-requisites for build to work.
|
||||
Before proceeding further, please click on the link above that matches your machine and ensure you have installed all the prerequisites for build to work.
|
||||
|
||||
## Concepts
|
||||
|
||||
The runtime repo can be built from a regular, non-admin command prompt. The repository currently consists of three different major parts: the runtime (a.k.a. coreclr), the libraries and the installer. To build everything you use the root build script (build.cmd/sh), and you add the `-subsetCategory` flag to build just one part.
|
||||
The runtime repo can be built from a regular, non-administrator command prompt, from the root of the repo, as follows:
|
||||
|
||||
For information about the different options available, supply the argument `-help|-h` when invoking the build script:
|
||||
For Linux:
|
||||
```
|
||||
./build.sh
|
||||
```
|
||||
|
||||
For Windows:
|
||||
```
|
||||
build.cmd
|
||||
```
|
||||
|
||||
This builds the product (in the default debug configuration), but not the tests.
|
||||
|
||||
For information about the different options available, supply the argument `--help|-h` when invoking the build script:
|
||||
```
|
||||
build -h
|
||||
```
|
||||
|
||||
On Unix, arguments can be passed in with a single `-` or double hyphen `--`.
|
||||
|
||||
The repository currently consists of three different major parts: the runtime (a.k.a. coreclr), the libraries, and the installer.
|
||||
To build just one part you use the root build script (build.cmd/sh), and you add the `-subsetCategory` flag.
|
||||
|
||||
## Configurations
|
||||
|
||||
You may need to build the tree in a combination of configurations. This section explains why.
|
||||
|
|
@ -36,15 +52,15 @@ A quick reminder of some concepts -- see the [glossary](../project/glossary.md)
|
|||
|
||||
When we talk about mixing configurations, we're discussing three sub-components:
|
||||
|
||||
* **CoreCLR** (often referred to as the runtime, most code under src/coreclr) -- this is the execution engine for managed code. It is written in C/C++. When built in a debug configuration, it is easier to debug into it, but it executes managed code more slowly - so slowly it will take a long time to run the managed code unit tests
|
||||
* **CoreLib** (also known as System.Private.CoreLib - code under src/coreclr/System.Private.CoreLib) -- this is the lowest level managed library. It has a special relationship with the runtime -- it must be in the matching configuration, e.g., if the runtime you are using was built in a debug configuration, this must be in a debug configuration
|
||||
* **CoreCLR** (often referred to as the runtime, most code under src/coreclr) -- this is the execution engine for managed code. It is written in C/C++. When built in a debug configuration, it is easier to debug into it, but it executes managed code more slowly - so slowly it will take a long time to run the managed code unit tests.
|
||||
* **CoreLib** (also known as System.Private.CoreLib - code under src/coreclr/System.Private.CoreLib) -- this is the lowest level managed library. It has a special relationship with the runtime -- it must be in the matching configuration, e.g., if the runtime you are using was built in a debug configuration, this must be in a debug configuration.
|
||||
* **All other libraries** (most code under src/libraries) -- the bulk of the libraries are oblivious to the configuration that CoreCLR/CoreLib were built in. Like most code they are most debuggable when built in a debug configuration, and, happily, they still run sufficiently fast in that configuration that it's acceptable for development work.
|
||||
|
||||
### What does this mean for me?
|
||||
|
||||
At this point you probably know what you are planning to work on first: the runtime or libraries.
|
||||
|
||||
* if you're working in CoreCLR proper, you may want to build everything in the debug configuration, depending on how comfortable you are debugging optimized native code
|
||||
* if you're working in CoreCLR proper, you may want to build everything in the debug configuration, depending on how comfortable you are debugging optimized native code.
|
||||
* if you're working in most libraries, you will want to use debug libraries with release CoreCLR and CoreLib, because the tests will run faster.
|
||||
* if you're working in CoreLib - you probably want to try to get the job done with release CoreCLR and CoreLib, and fall back to debug if you need to. The [Building libraries](building/libraries/README.md) document explains how you'll do this.
|
||||
|
||||
|
|
@ -56,4 +72,4 @@ Now you know about configurations and how we use them, you will want to read how
|
|||
After that, here's information about how to run tests:
|
||||
|
||||
- [Testing coreclr](testing/coreclr/testing.md)
|
||||
- [Testing libraries](testing/libraries/testing.md)
|
||||
- [Testing libraries](testing/libraries/testing.md)
|
||||
|
|
|
|||
|
|
@ -1,32 +1,42 @@
|
|||
# Building
|
||||
|
||||
To build just CoreCLR, use the `--subsetCategory` flag to the `build.sh` (or `build.cmd`) at the repo root:
|
||||
To build just CoreCLR, use the `--subsetCategory` flag to the `build.sh` (or `build.cmd`) script at the repo root:
|
||||
|
||||
For Linux:
|
||||
```
|
||||
./build.sh --subsetCategory coreclr
|
||||
```
|
||||
or on Windows,
|
||||
|
||||
For Windows:
|
||||
```
|
||||
build.cmd --subsetCategory coreclr
|
||||
```
|
||||
|
||||
By default, build generates a 'debug' build type, that includes asserts and is easier for some people to debug. If you want to make performance measurements, or just want tests to execute more quickly, you can also build the 'release' version which does not have these checks by adding the flag `-configuration release` (or `-c release`), for example
|
||||
By default, build generates a 'debug' build type, that includes asserts and is easier for some people to debug. If you want to make performance measurements, or just want tests to execute more quickly, you can also build the 'release' version (which does not have these checks) by adding the flag `-configuration release` (or `-c release`), for example:
|
||||
```
|
||||
./build.sh --subsetCategory coreclr -configuration release
|
||||
```
|
||||
|
||||
CoreCLR also supports a 'checked' build type which has asserts enabled like 'debug', but is built with the native compiler optimizer enabled, so it runs much faster. This is the usual mode used for running tests in the CI system. You can build that using, for example:
|
||||
```
|
||||
./build.sh --subsetCategory coreclr -configuration checked
|
||||
```
|
||||
|
||||
This will produce outputs as follows:
|
||||
|
||||
- Product binaries will be dropped in `artifacts\bin\coreclr\<OS>.<arch>.<flavor>` folder.
|
||||
- A NuGet package, Microsoft.Dotnet.CoreCLR, will be created under `artifacts\bin\coreclr\<OS>.<arch>.<flavor>\.nuget` folder.
|
||||
- Test binaries will be dropped under `artifacts\tests\coreclr\<OS>.<arch>.<flavor>` folder.
|
||||
|
||||
- Test binaries will be dropped under `artifacts\tests\coreclr\<OS>.<arch>.<flavor>` folder. However, the root build script will not build the tests.
|
||||
|
||||
The build places logs in `artifacts\log` and these are useful when the build fails.
|
||||
|
||||
The build places all of its output in the `artifacts\obj\coreclr` directory, so if you remove that directory you can force a
|
||||
The build places all of its intermediate output in the `artifacts\obj\coreclr` directory, so if you remove that directory you can force a
|
||||
full rebuild.
|
||||
|
||||
The build has a number of options that you can learn about using `build -?`. In particular `-skiptests` skips building the tests, which makes the build quicker.
|
||||
To build CoreCLR, the root build script invokes the src\coreclr\build.cmd (or build.sh) script. To build the CoreCLR tests, you must use this script.
|
||||
Use `build -?` to learn about the options to this script.
|
||||
|
||||
See [Running Tests](../../testing/coreclr/testing.md) for instructions on running the tests.
|
||||
|
||||
See also [Build CoreCLR on Linux](linux-instructions.md), [Build CoreCLR on OS X](osx-instructions.md), [Build CoreCLR on FreeBSD](freebsd-instructions.md),
|
||||
[Cross Compilation for ARM on Windows](cross-building.md), [Cross Compilation for Android on Linux](android.md).
|
||||
|
|
|
|||
|
|
@ -6,36 +6,37 @@ Details on test metadata can be found in [test-configuration.md](test-configurat
|
|||
|
||||
1) Build the CoreCLR product
|
||||
* [Unix](../../building/coreclr/linux-instructions.md)
|
||||
* [OSX](../../building/coreclr/osx-instructions.md)
|
||||
* [macOS](../../building/coreclr/osx-instructions.md)
|
||||
* [Windows](../../building/coreclr/README.md)
|
||||
1) [Build the libraries](../../building/libraries/README.md) in Release configuration. Pass the configuration of CoreCLR you just built to the build script (e.g. `/p:CoreCLRConfiguration=Debug`).
|
||||
1) From the src/coreclr directory run the following command:
|
||||
2) [Build the libraries](../../building/libraries/README.md) in Release configuration. Pass the configuration of CoreCLR you just built to the build script (e.g. `/p:CoreCLRConfiguration=Debug`).
|
||||
3) From the src/coreclr directory run the following command:
|
||||
* Non-Windows - `./build-test.sh`
|
||||
* Windows - `build-test.cmd`
|
||||
* Supply `-h` for usage flags
|
||||
|
||||
### Test priority
|
||||
|
||||
The CoreCLR tests have two priorities 0 and 1, the priority 0 tests run by default on all PRs, while the priority 1 tests run out outerloop CI runs.
|
||||
The CoreCLR tests have two priorities, 0 and 1. The priority 0 tests run by default on all pull requests (PRs), while the priority 1 tests run in outerloop CI runs.
|
||||
|
||||
### Examples
|
||||
|
||||
* Build all tests priority `1` and higher
|
||||
* Build all tests priority 1 and higher
|
||||
* `build-test.cmd -priority=1`
|
||||
* `build-test.sh -priority1`
|
||||
|
||||
## Build Individual Test
|
||||
|
||||
Note: CoreCLR must be built prior to building an individual test. See first step for building all tests.
|
||||
Note: CoreCLR must be built prior to building an individual test. See the first step, above, for building all tests.
|
||||
|
||||
* Native Test: Build the generated CMake projects
|
||||
* Projects are auto-generated when the `build-test.sh`/`build-test.cmd` script is run
|
||||
* It is possible to explicitely run only the native test build with `build-test.sh/cmd skipmanaged`
|
||||
* Managed Test: Invoke dotnet msbuild on the project directly
|
||||
> ~/runtime/.dotnet/dotnet msbuild ~/runtime/src/coreclr/tests/src/JIT/CodegenBringupTests/Array1.csproj /p:__BuildOs=OSX /p:__BuildType=Release
|
||||
- Note that /p:__BuildOs=`[Windows_NT, OSX, Linux]` is required.
|
||||
* It is possible to explicitly run only the native test build with `build-test.sh/cmd skipmanaged`
|
||||
* Managed Test: Invoke `dotnet msbuild` on the project directly. `dotnet` can be the `dotnet.sh` or `dotnet.cmd` script in the repo root.
|
||||
```
|
||||
<runtime-repo-root>/dotnet.sh msbuild <runtime-repo-root>/src/coreclr/tests/src/JIT/CodegenBringupTests/Array1_d.csproj /p:__BuildType=Release
|
||||
```
|
||||
|
||||
## Additional Documents
|
||||
|
||||
* [Windows](../../testing/coreclr/windows-test-instructions.md)
|
||||
* [Non-Windows](../../testing/coreclr/unix-test-instructions.md)
|
||||
* [Windows](windows-test-instructions.md)
|
||||
* [Non-Windows](unix-test-instructions.md)
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Building and running tests on Linux, OS X, and FreeBSD
|
||||
Building and running tests on Linux, macOS, and FreeBSD
|
||||
======================================================
|
||||
|
||||
CoreCLR tests
|
||||
|
|
@ -6,44 +6,52 @@ CoreCLR tests
|
|||
|
||||
## Building
|
||||
|
||||
Build CoreCLR on [Unix](https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md).
|
||||
Build CoreCLR on [Unix](../../building/coreclr/linux-instructions.md).
|
||||
|
||||
## Building the Tests
|
||||
|
||||
DotNet is required to build the tests, this can be done on any platform then copied over if the arch or os does not support DotNet. If DotNet is not supported, [CoreFX](https://github.com/dotnet/corefx/blob/master/Documentation/building/unix-instructions.md) is also required to be built.
|
||||
Dotnet CLI is required to build the tests. This can be done on any platform then copied over if the architecture or OS does not support Dotnet.
|
||||
|
||||
To build the tests on Unix:
|
||||
|
||||
> `./src/coreclr/build-test.sh`
|
||||
```sh
|
||||
./src/coreclr/build-test.sh
|
||||
```
|
||||
|
||||
Please note that this builds the Priority 0 tests. To build priority 1:
|
||||
|
||||
> `src/coreclr/build-test.sh -priority 1`
|
||||
```sh
|
||||
./src/coreclr/build-test.sh -priority1
|
||||
```
|
||||
|
||||
## Building Individual Tests
|
||||
|
||||
During development there are many instances where building an individual test is fast and necessary. All of the necessary tools to build are under `coreclr`. It is possible to use `runtime/.dotnet/dotnet msbuild` as you would normally use MSBuild with a few caveats.
|
||||
During development there are many instances where building an individual test is fast and necessary. All of the necessary tools to build are under `coreclr`. It is possible to use `~/runtime/dotnet.sh msbuild` as you would normally use MSBuild with a few caveats.
|
||||
|
||||
**!! Note !! -- Passing /p:__BuildOs=[OSX|Linux] is required.**
|
||||
**!! Note !! -- Passing /p:__BuildOS=[OSX|Linux] is required.**
|
||||
|
||||
## Building an Individual Test
|
||||
|
||||
>`/path/to/runtime/.dotnet/dotnet msbuild src/coreclr/tests/src/path-to-proj-file /p:__BuildOS=<BuildOS> /p:__BuildType=<BuildType>`
|
||||
```
|
||||
/path/to/runtime/dotnet.sh msbuild src/coreclr/tests/src/path-to-proj-file /p:__BuildOS=<BuildOS> /p:__BuildType=<BuildType>
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
The following instructions assume that on the Unix machine:
|
||||
- The CoreCLR repo is cloned at `/mnt/coreclr`
|
||||
|
||||
`src/coreclr/build-test.sh` will have setup the Core_Root directory correctly after the test build.
|
||||
`src/coreclr/build-test.sh` will have set up the `Core_Root` directory correctly after the test build.
|
||||
|
||||
```bash
|
||||
~/runtime$ src/coreclr/tests/runtest.sh x64 checked
|
||||
~/runtime$ ./src/coreclr/tests/runtest.sh x64 checked
|
||||
```
|
||||
|
||||
Please use the following command for help.
|
||||
|
||||
>./src/coreclr/tests/runtest.sh -h
|
||||
```
|
||||
~/runtime$ ./src/coreclr/tests/runtest.sh -h
|
||||
```
|
||||
|
||||
### Unsupported and temporarily disabled tests
|
||||
|
||||
|
|
@ -70,8 +78,12 @@ Build CoreCLR on the Unix machine.
|
|||
|
||||
Run tests:
|
||||
|
||||
> `~/runtime$ src/coreclr/src/pal/tests/palsuite/runpaltests.sh ~/runtime/artifacts/obj/coreclr/Linux.x64.Debug`
|
||||
```
|
||||
~/runtime$ src/coreclr/src/pal/tests/palsuite/runpaltests.sh ~/runtime/artifacts/obj/coreclr/Linux.x64.Debug
|
||||
```
|
||||
|
||||
Test results will go into:
|
||||
|
||||
> `/tmp/PalTestOutput/default/pal_tests.xml`
|
||||
```
|
||||
/tmp/PalTestOutput/default/pal_tests.xml
|
||||
```
|
||||
|
|
|
|||
|
|
@ -4,24 +4,30 @@ Building and running tests on Windows
|
|||
## Building Tests
|
||||
|
||||
To build the tests simply navigate to the tests directory above the repo and run,
|
||||
|
||||
```
|
||||
C:\git\runtime>src\coreclr\build-test.cmd
|
||||
```
|
||||
|
||||
## Cleaning Tests
|
||||
|
||||
**Note:** Cleaning should be done before all tests to be sure that the test assets are initialized correctly. To do a clean build of the tests, in a clean command prompt, issue the following command:
|
||||
|
||||
```
|
||||
C:\git\runtime>src\coreclr\build-test.cmd -rebuild
|
||||
```
|
||||
|
||||
## Building Tests that will be precompiled
|
||||
|
||||
```
|
||||
C:\git\runtime>src\coreclr\build-test.cmd crossgen
|
||||
```
|
||||
|
||||
This will use `crossgen.exe` to precompile the test executables before they are executed.
|
||||
|
||||
## Building Other Priority Tests
|
||||
|
||||
```
|
||||
C:\git\runtime>src\coreclr\build-test.cmd -priority=1
|
||||
```
|
||||
|
||||
The number '1' is just an example. The default value (if no priority is specified) is 0. To clarify, if '1' is specified, all tests with CLRTestPriorty 0 **and** 1 will be built and consequently run.
|
||||
|
||||
|
|
@ -29,15 +35,17 @@ The number '1' is just an example. The default value (if no priority is specifie
|
|||
|
||||
To run a clean, priority 1, crossgen test pass:
|
||||
|
||||
```
|
||||
C:\git\runtime>src\coreclr\build-test.cmd -rebuild crossgen -priority=1
|
||||
```
|
||||
|
||||
`src\coreclr\build-test.cmd /?` - will list additional supported parameters.
|
||||
`src\coreclr\build-test.cmd -?` - will list additional supported parameters.
|
||||
|
||||
### Building Individual Tests
|
||||
|
||||
Note: build-test.cmd or build.cmd skipnative needs to be run at least once
|
||||
Note: `build-test.cmd` or `build.cmd skipnative` needs to be run at least once
|
||||
|
||||
* Native Test: Build the generated Visual Studio solution or make file corresponding to Test cmake file.
|
||||
* Native Test: Build the generated Visual Studio solution or makefile corresponding to test cmake file.
|
||||
|
||||
* Managed Test: You can invoke msbuild on the project directly from Visual Studio Command Prompt.
|
||||
|
||||
|
|
@ -47,15 +55,17 @@ Note: build-test.cmd or build.cmd skipnative needs to be run at least once
|
|||
|
||||
For example to run all of the tests using your checked build:
|
||||
|
||||
```
|
||||
<repo_root>\src\coreclr\tests\runtest.cmd checked
|
||||
```
|
||||
|
||||
This will generate a report named as `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_Windows_NT__x64__Checked.html`) in the subdirectory `<repo_root>\artifacts\log`. Any tests that failed will be listed in `TestRunResults_Windows_NT__x64__Checked.err`.
|
||||
This will generate a report named as `TestRun_<arch>_<flavor>.html` (e.g. `TestRun_Windows_NT_x64_Checked.html`) in the subdirectory `<repo_root>\artifacts\log`. Any tests that failed will be listed in `TestRunResults_Windows_NT_x64_Checked.err`.
|
||||
|
||||
### Investigating Test Failures
|
||||
|
||||
Upon completing a test run, you may find one or more tests have failed.
|
||||
|
||||
The output of the Test will be available in Test reports directory, but the default the directory would be something like is `<repo_root>\artifacts\tests\coreclrWindows_NT.x64.Checked\Reports\Exceptions\Finalization`.
|
||||
The output of the Test will be available in Test reports directory, but by default the directory would be something like `<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Reports\Exceptions\Finalization`.
|
||||
|
||||
There are 2 files of interest:
|
||||
|
||||
|
|
@ -69,13 +79,14 @@ If you wish to re-run a failed test, please follow the following steps:
|
|||
1. Set an environment variable, `CORE_ROOT`, pointing to the path to product binaries that was passed to runtest.cmd.
|
||||
For example using a checked build the location would be: `<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Tests\Core_Root`
|
||||
|
||||
1. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Exceptions\Finalization\Finalizer.cmd`.
|
||||
2. Next, run the failed test, the command to which is also present in the test report for a failed test. It will be something like `<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Exceptions\Finalization\Finalizer.cmd`.
|
||||
|
||||
If you wish to run the test under a debugger (e.g. [WinDbg](http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063(v=vs.85).aspx)), append `-debug <debuggerFullPath>` to the test command. For example:
|
||||
|
||||
```
|
||||
<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Exceptions\Finalization\Finalizer.cmd -debug <debuggerFullPath>
|
||||
```
|
||||
|
||||
### Modifying a test
|
||||
|
||||
If test changes are needed, make the change and build the test project. This will binplace the binaries in test binaries folder (e.g. `<repo_root>\artifacts\tests\coreclr\Windows_NT.x64.Checked\Exceptions\Finalization`). At this point, follow the steps to re-run a failed test to re-run the modified test.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue