Update guidelines for C++ standard library usage and build against libc++ w/ libstdc++ ABI for linux arm/arm64/x64 - #132347
Update guidelines for C++ standard library usage and build against libc++ w/ libstdc++ ABI for linux arm/arm64/x64#132347jkoritzinsky wants to merge 1 commit into
Conversation
…bc++ w/ libstdc++ ABI for linux arm/arm64/x64
|
Azure Pipelines: Successfully started running 6 pipeline(s). 10 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
|
Tagging subscribers to this area: @dotnet/runtime-infrastructure |
There was a problem hiding this comment.
Pull request overview
This PR updates the Linux build matrix to request a specific C++ standard library/ABI configuration (libc++ + libstdc++ ABI) for selected Linux legs, and updates the CoreCLR coding guidelines to reflect the intended use of C/C++ standard headers/types under the new build setup.
Changes:
- Add
cxxStandardLibrary,cxxStandardLibraryStatic, andcxxAbiLibraryjob parameters to Linux arm/arm64/x64 (and linux_x64_sanitizer) entries in the platform matrix. - Update
clr-code-guide.mdguidance around standard header usage, Linux C++ library setup, and DAC/cDAC constraints.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| eng/pipelines/common/platform-matrix.yml | Adds C++ stdlib/ABI selection parameters to specific Linux build matrix legs. |
| docs/coding-guidelines/clr-code-guide.md | Revises CoreCLR guidance on standard headers/types and clarifies DAC/cDAC restrictions. |
| cxxStandardLibrary: libc++ | ||
| cxxStandardLibraryStatic: true | ||
| cxxAbiLibrary: libstdc++ |
| The C and C++ standard headers are available for usage in the CoreCLR code-base. However, there are restrictions on using the standard-provided APIs for code that will run as part of CoreCLR. | ||
|
|
||
| Code that will only run in other processes, such as `createdump` or other extraneous tools, do not have the same set of restrictions. | ||
| Code that will only run in other processes, such as `createdump` or other extraneous tools, have less restrictions. |
| ### <a name="2.11.4"></a> 2.11.4 Limit usage of standard template types in shipping executables | ||
|
|
||
| For Linux x64 and amd64 platforms, we build against a very old libstdc++, the version that shipped with Ubuntu 16.04. As a result, we strive to reduce our usage of template types (where code from the headers will be inserted into our binaries) in shipping executables and libraries. | ||
| ### <a name="2.11.4"></a> 2.11.4 Do not use C++ Standard Library types |
| Using types and algorithms from the C++ standard is supported within the CoreCLR code base; however, we do not support it in our DAC/cDAC tooling. Do not use C++ Standard-defined containers, smart pointers, etc. for any fields accessed by the DAC or cDAC. Only use our collections that have cDAC contracts when you need to expose them for diagnostic tooling. | ||
|
|
||
| For non-shipping native code, like the `superpmi` tools suite, standard headers can be used without limitation. | ||
| For cases where diagnostic tooling integration is not required, you may use C++ Standard-defined types and algorithms meeting the C++ standard version CoreCLR builds with (defined in [eng/native/configurecompiler.cmake](../../eng/native/configurecompiler.cmake)). |
There was a problem hiding this comment.
I would add a note that standard library must run in place where the following are satisfied:
- It is not permitted to run under
NOTHROW, unless the API is marked withnoexcept. - It is never permitted to run under
MODE_COOPERATIVE.
It is preferred to keep standard library code and related callbacks/lambdas used in algorithms etc., under the STANDARD_VM_CONTRACT contract.
There was a problem hiding this comment.
I'm curious about the reason here. It's straight to understand the noexcept requirement, but not straight about cooperative mode restriction.
And also, are there any STL component considered "trivial enough" for safe usage anywhere? For example, I can't imagine where <bits> can't be used.
There was a problem hiding this comment.
but not straight about cooperative mode restriction.
It is far too easy to reach for a standard library collection or algorithm and create a GC starvation issue. We're being selective about this because there is an inherent cost to consuming standard library APIs and not truly understanding how they will behave.
And also, are there any STL component considered "trivial enough" for safe usage anywhere?
No. Using more standard library collections and algorithms is, at least for now, going to be limited to actual cases where there is measurable benefits. We will not accept wholesale replacements of our built-in collections for say std::vector<> or arbitrary replacement of holders for std::unique_ptr<>. The group of maintainers needs to get comfortable with best practices and when and where we can modernize the C++ without creating a maintenance burden for servicing or unlocking undefined behavior that compilers can then optimize in unexpected ways.
Follow-up to #101088 and #101773
Update our build pipelines to build against a serviceable C++ standard library and update our guidelines to allow such usage.
Requires a PR to dotnet/dotnet to actually update the guidance. Opening this PR to validate here before opening the PR there.