From 4b0e623ed1513e35ece6ff55681a172c76c4c2d7 Mon Sep 17 00:00:00 2001 From: Jeremy Koritzinsky Date: Fri, 14 Aug 2026 16:18:17 -0700 Subject: [PATCH] Update guidelines for C++ standard library usage and build against libc++ w/ libstdc++ ABI for linux arm/arm64/x64 --- docs/coding-guidelines/clr-code-guide.md | 12 ++++++------ eng/pipelines/common/platform-matrix.yml | 9 +++++++++ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/coding-guidelines/clr-code-guide.md b/docs/coding-guidelines/clr-code-guide.md index 11b79fea262300..cc552292e8c8da 100644 --- a/docs/coding-guidelines/clr-code-guide.md +++ b/docs/coding-guidelines/clr-code-guide.md @@ -1260,7 +1260,9 @@ See the big block comment at the start of [src\inc\contract.h][contract.h]. 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. + +For Linux builds, we build against an older C++ runtime to support older Linux distributions, but we bundle a newer C++ Standard Library implementation. This means CoreCLR code can use new C++ library features, but there may be some corners where particular features are not supported and fail at link time. Those features are not supported in CoreCLR code and should be avoided. ### 2.11.1 Do not use wchar_t @@ -1276,13 +1278,11 @@ For example, `std::vector::at()` should not be used as it may throw an `std:: The POSIX API `setenv` is not thread safe with `getenv` and can lead to crashes. CoreCLR provides a `PAL_getenv` API that is thread-safe. This API should be used instead when on non-Windows platforms. -### 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. +### 2.11.4 Do not use C++ Standard Library types -This rule applies to both `coreclr` as well as shipping external executables like `createdump`. +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)). ## 2.12 Is your code DAC compliant? diff --git a/eng/pipelines/common/platform-matrix.yml b/eng/pipelines/common/platform-matrix.yml index 447e4c5c1f164f..233b74edf1f16a 100644 --- a/eng/pipelines/common/platform-matrix.yml +++ b/eng/pipelines/common/platform-matrix.yml @@ -43,6 +43,9 @@ jobs: buildConfig: ${{ parameters.buildConfig }} helixQueueGroup: ${{ parameters.helixQueueGroup }} crossBuild: true + cxxStandardLibrary: libc++ + cxxStandardLibraryStatic: true + cxxAbiLibrary: libstdc++ ${{ insert }}: ${{ parameters.jobParameters }} # Linux arm64 @@ -69,6 +72,9 @@ jobs: buildConfig: ${{ parameters.buildConfig }} helixQueueGroup: ${{ parameters.helixQueueGroup }} crossBuild: true + cxxStandardLibrary: libc++ + cxxStandardLibraryStatic: true + cxxAbiLibrary: libstdc++ ${{ insert }}: ${{ parameters.jobParameters }} # Linux musl x64 @@ -230,6 +236,9 @@ jobs: buildConfig: ${{ parameters.buildConfig }} helixQueueGroup: ${{ parameters.helixQueueGroup }} crossBuild: true + cxxStandardLibrary: libc++ + cxxStandardLibraryStatic: true + cxxAbiLibrary: libstdc++ ${{ insert }}: ${{ parameters.jobParameters }} - ${{ if containsValue(parameters.platforms, 'linux_x64_sanitizer') }}: