0c36a9a209
Refactor the PAL test framework to be useable in our CI system, and enable it for testing The existing PAL tests are problematic in a few ways for our CI. 1. They are large in terms of disk space used per test, this interferes with building them properly, especially as they are part of the product build, and not of the test build 2. While part of the product build, the option to build them was well hidden. 3. The tests are not related to our existing tests, and in particular are not driven from managed xunit wrappers. The change here has 4 components 1. Reduce the volume of the binaries such that they can be passed from a product build to a test job effectively. This is done by merging all tests which are not strictly dependent on secondary libraries. - This was done via a tool which parsed and replaced all of the CMakeFiles.txt - And then manual editing to remove all duplicate global symbols 2. The build flag for building the tests has been exposed as a first class option to build-runtime, as well as through the subset mechanism. As of this change, developers who wish to build the tests should use the clr.paltests subset to build the tests. 3. As the tests do not have normal xunit wrappers, but they *do* have a script which will generate xunit output, they cannot quite be run in the existing helix pathway. Add a separate path for launch the appropriate helix workitem as part of outerloop test runs. 4. A new issue exclusion mechanism has been built. Add exclusions by modifying src/coreclr/src/pal/tests/palsuite/issues.targets - There are a number of failures in the current test suite that should probably be investigated, but making meaningful changes to the tests should not be part of this change. |
||
|---|---|---|
| .. | ||
| building | ||
| ci | ||
| debugging | ||
| requirements | ||
| testing | ||
| trimming | ||
| editing-and-debugging.md | ||
| README.md | ||
| using-dotnet-cli.md | ||
Workflow Guide
The repo can be built for the following platforms, using the provided setup and the following instructions. Before attempting to clone or build, please check these requirements.
Build Requirements
| Chip | Windows | Linux | macOS | FreeBSD |
|---|---|---|---|---|
| x64 | ✔ | ✔ | ✔ | ✔ |
| x86 | ✔ | |||
| ARM | ✔ | ✔ | ||
| ARM64 | ✔ | ✔ | ||
| Requirements | Requirements | Requirements | Requirements |
Before proceeding further, please click on the link above that matches your machine and ensure you have installed all the prerequisites for the build to work.
Concepts
The runtime repo can be built from a regular, non-administrator command prompt, from the root of the repo, as follows:
For Linux and macOS
./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 like systems, arguments can be passed in with a single - or double hyphen --.
The repository currently consists of different major parts: the runtimes, the libraries, and the installer.
To build just one part you use the root build script (build.cmd/sh), and you add the -subset flag.
Editing and Debugging
For instructions on how to edit code and debug your changes, see Editing and Debugging.
Configurations
You may need to build the tree in a combination of configurations. This section explains why.
A quick reminder of some concepts -- see the glossary for more on these:
- Debug Configuration -- Non-optimized code. Asserts are enabled.
- Checked Configuration -- Optimized code. Asserts are enabled. Only relevant to CoreCLR runtime.
- Release Configuration -- Optimized code. Asserts are disabled. Runs at the best speed, and suitable for performance profiling. You will have limited debugging experience.
When we talk about mixing configurations, we're discussing the following sub-components:
- Runtime is the execution engine for managed code and there are two different implementations available. Both are written in C/C++, therefore, easier to debug when built in a Debug configuration.
- CoreCLR is the comprehensive execution engine which if build in Debug Configuration it executes managed code very slowly. For example, it will take a long time to run the managed code unit tests. The code lives under src/coreclr.
- Mono is portable and also slimmer runtime and it's not that sensitive to Debug Configuration for running managed code. You will still need to build it without optimizations to have good runtime debugging experience though. The code lives under src/mono.
- CoreLib (also known as System.Private.CoreLib) is the lowest level managed library. It has a special relationship to the runtimes and therefore it must be built 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. The runtime agnostic code for this library can be found at src/libraries/System.Private.CoreLib/src.
- Libraries is the bulk of the dlls that are oblivious to the configuration that runtimes and CoreLib were built in. 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. The code lives under src/libraries.
What does this mean for me?
At this point you probably know what you are planning to work on primarily: the runtimes or libraries.
- if you're working in runtimes, 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 libraries, you will want to use debug libraries with a release version of runtime 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 runtime and CoreLib, and fall back to debug if you need to. The Building Libraries document explains how you'll do this.
Now you know about configurations and how we use them, you will want to read how to build what you plan to work on. Pick one of these:
After that, here's information about how to run tests:
And how to measure performance: