[Clang] Add `-fexperimental-library` flag to enable unstable and experimental features: follow-up fixes

[ldionne]

Summary

This is a follow-up for https://reviews.llvm.org/D120160 that addresses some of the post-merge feedback.

[ldionne]

Thanks a lot for the fixes @egorzhdan! I think this looks pretty good. Since LLVM 15 is coming up and we'd like to have this in its final state for libc++ purposes, I'll commandeer this to make a couple adjustments and I'll merge this after seeking more feedback on the overall design. Thanks for doing all the work!

[Mordante]

Thanks @egorzhdan for working on this, I seem to have overlooked this item in the review queue.
SGMT, but it seems the libc++ CI hasn't been triggered with this change. Maybe change one file in libc++ to give the CI a spin?

clang/docs/ClangCommandLineReference.rst

272

I'm not happy with the word "should", I don't want to decide what users should or should not do. Several of these experimental features are perfectly usable. If you can rebuild your entire software stack ABI and API stability might be less of an issue. (The lack of polish of some features might be a reason not to use them.)

clang/include/clang/Driver/Options.td

1188

Likewise regarding should.

[MaskRay]

clang/docs/ClangCommandLineReference.rst

270

The doc is auto-generated by tablegen (https://discourse.llvm.org/t/clang-driver-options-td-docs-usersmanual-rst-and-docs-clangcommandlinereference-rst/56540).
For lengthy documentation, use clang/docs/UsersManual.rst instead

[ldionne]

• Rebase
• Rename to -fexperimental-library
• Add tests
• Make sure we link against -lc++experimental

[ldionne]

clang/docs/ClangCommandLineReference.rst

270

Re-generated, thanks.

[MaskRay]

LGTM.

It may be related, @urnathan wants to add -std=c++{current,future} to GCC and may have opinions on the option name.

clang/lib/Driver/ToolChains/Clang.cpp

5840

Use Args.AddLastArg

[ldionne]

In D121141#3652616, @MaskRay wrote:

LGTM.

It may be related, @urnathan wants to add -std=c++{current,future} to GCC and may have opinions on the option name.

Interesting! @urnathan , is there any documentation/discussion on what -std=c++{current,future} would do? I think it's unrelated to this specific proposal, since -fexperimental-library is valid regardless of the Standard mode, however I still think it would make sense to align what Clang and GCC do. One idea we had floated around was -std=c++latest meaning the latest officially ratified Standard, and -std=c++next being the one currently cooking. For example, right now that would give us -std=c++latest == -std=c++20 and -std=c++next == -std=c++2b.

[ldionne]

Address review comment.

[MaskRay]

clang/include/clang/Driver/Options.td

1186

This can be simplified with OptInCC1FFlag (both driver/CC1 for the pos form, but driver-only for the neg form).
You'll need to set CoreOption to make the option available to clang-cl.

clang/lib/Driver/ToolChain.cpp

1016

There may be an archive ordering problem.

clang/lib/Driver/ToolChains/AIX.cpp

279

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/BareMetal.cpp

280

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/CloudABI.cpp

122

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/MipsLinux.cpp

117

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/OpenBSD.cpp

335

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/VEToolchain.cpp

151

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/lib/Driver/ToolChains/WebAssembly.cpp

448

There may be an archive ordering problem. -lc++experimental should probably be before -lc++abi

clang/test/Driver/experimental-library-flag.cpp

5

End full sentences with a period.

6

Suggest testing -lc++ as well

[Mordante]

LGTM, but please update the name of the flag in the title before landing.

[ldionne]

clang/include/clang/Driver/Options.td

1186

I was looking for documentation on OptInCC1FFlag, and I found:

// A boolean option which is opt-in in CC1. The positive option exists in CC1 and
// Args.hasArg(OPT_ffoo) can be used to check that the flag is enabled.
// This is useful if the option is usually disabled.
// Use this only when the option cannot be declared via BoolFOption.
multiclass OptInCC1FFlag<string name, string pos_prefix, string neg_prefix="",

It says to use BoolFOption is we can. So should I stick with BoolFOption?

clang/lib/Driver/ToolChain.cpp

1016

I'm not sure I follow -- what problem are you concerned about?

[ldionne]

The experimental-library-flag test is currently failing on Windows because on Windows, -stdlib=libc++ seems to be ignored and we don't add -lc++ or -lc++experimental. Does someone understand how things are supposed to work when using libc++ on Windows? @mstorsjo maybe?

[mstorsjo]

In D121141#3655323, @ldionne wrote:

The experimental-library-flag test is currently failing on Windows because on Windows, -stdlib=libc++ seems to be ignored and we don't add -lc++ or -lc++experimental. Does someone understand how things are supposed to work when using libc++ on Windows? @mstorsjo maybe?

Clarification - I presume it would fail when targeting MSVC, not when targeting mingw.

Yes, I think -stdlib=libc++ has no effect on MSVC targets currently, and you have to add the include directory and lib arguments when using it - I think @rnk, @hans or @thakis can confirm that.

@phosek has a patch to take the option into use there too, but it's essentially blocked by D103947 if I remember correctly. (The chain of dependencies that trigger that is a bit non-obvious, but I think it was the case that they build their Clang with -DCLANG_DEFAULT_CXX_STDLIB=libc++, and once that has an effect on the MSVC configs, a bunch of code in their build setup suddenly ends up using libc++ instead of MSVC STL, and there's a lot of code there that is built with _HAS_EXCEPTIONS=0 - hence libc++ needing to work in that configuration.)

[MaskRay]

clang/include/clang/Driver/Options.td

1186

OK. Using BoolFOption is fine as we can express the ExperimentalLibrary logic in the tablegen file. I just feel that the boilerplate is a bit higher than OptInCC1FFlag.

clang/lib/Driver/ToolChain.cpp

1016

https://lld.llvm.org/ELF/warn_backrefs.html

When these -l options are used to link archives (.a), they should be added in a dependency order.

-lc++experimental presumably uses symbols from -lc++abi and must precede -lc++abi.
-lc++abi uses symbols from -lunwind and must precede -lunwind.

For macOS and Windows, the order usually doesn't matter.

[phosek]

In D121141#3656100, @mstorsjo wrote:

In D121141#3655323, @ldionne wrote:

The experimental-library-flag test is currently failing on Windows because on Windows, -stdlib=libc++ seems to be ignored and we don't add -lc++ or -lc++experimental. Does someone understand how things are supposed to work when using libc++ on Windows? @mstorsjo maybe?

Clarification - I presume it would fail when targeting MSVC, not when targeting mingw.

Yes, I think -stdlib=libc++ has no effect on MSVC targets currently, and you have to add the include directory and lib arguments when using it - I think @rnk, @hans or @thakis can confirm that.

@phosek has a patch to take the option into use there too, but it's essentially blocked by D103947 if I remember correctly. (The chain of dependencies that trigger that is a bit non-obvious, but I think it was the case that they build their Clang with -DCLANG_DEFAULT_CXX_STDLIB=libc++, and once that has an effect on the MSVC configs, a bunch of code in their build setup suddenly ends up using libc++ instead of MSVC STL, and there's a lot of code there that is built with _HAS_EXCEPTIONS=0 - hence libc++ needing to work in that configuration.)

That's correct, I implemented the support for -stdlib=libc++ on MSVC targets in D101479, but that change caused a number of build failures including the compiler-rt due to _HAS_EXCEPTIONS=0 so relanding that change is blocked on D103947.

[ldionne]

In D121141#3658946, @phosek wrote:

That's correct, I implemented the support for -stdlib=libc++ on MSVC targets in D101479, but that change caused a number of build failures including the compiler-rt due to _HAS_EXCEPTIONS=0 so relanding that change is blocked on D103947.

Awesome, thanks both for the additional context. I'll try to take a look at D103947 soon. In the meantime, I'll mark the test as XFAIL on Windows just to unblock this patch, because it absolutely needs to land for LLVM 15.

clang/lib/Driver/ToolChain.cpp

1016

Got it, thanks. In this case, however, we're only linking against libc++, not libc++abi. So presumably there isn't any potential issue here? However, I agree that the other places where I had -lc++experimental after -lc++abi are a problem, and I am fixing those.

clang/test/Driver/experimental-library-flag.cpp

6

IMO this is not the right place to test this -- this should only be testing stuff that is specific to -fexperimental-library.

[ldionne]

Address most review feedback.

[ldionne]

Windows seems to have been "fixed" (a band-aid really), and the Linux failure seems unrelated, so I'll ship this now.

[ldionne]

I saw that this change broke llvm-clang-x86_64-sie-ubuntu-fast, and I am following up with the bot owner to understand what's special about their target. I'm not being notified of any other failures so far.

[ldionne]

I just got notified of a failure on clang-ppc64-aix. I'll take a look first thing tomorrow morning.

clang/docs/ClangCommandLineReference.rst

#include files may be "skipped" due to include guard optimization
              or #pragma once. This flag makes -H show also such includes.
 
 .. option:: -fsystem-module
 
 Build this module as a system module. Only used with -emit-module
 
 .. option:: -fuse-cuid=<arg>
 
 Method to generate ID's for compilation units for single source offloading languages CUDA and HIP: 'hash' (ID's generated by hashing file path and command line options) \| 'random' (ID's generated as random numbers) \| 'none' (disabled). Default is 'hash'. This option will be overridden by option '-cuid=\[ID\]' if it is specified.
 
 .. option:: --gcc-toolchain=<arg>
 
 Search for GCC installation in the specified directory on targets which commonly use GCC. The directory usually contains 'lib{,32,64}/gcc{,-cross}/$triple' and 'include'. If specified, sysroot is skipped for GCC detection. Note: executables (e.g. ld) used by the compiler are not overridden by the selected GCC installation
 
 .. option:: -gcodeview
 
 Generate CodeView debug information
 
 .. option:: -gcodeview-ghash, -gno-codeview-ghash

 .. option:: -fescaping-block-tail-calls, -fno-escaping-block-tail-calls
 
 .. option:: -fexceptions, -fno-exceptions
 
 Enable support for exception handling
 
 .. option:: -fexec-charset=<arg>
 
+.. option:: -fexperimental-library, -fno-experimental-library
+
+Control whether unstable and experimental library features are enabled. This option enables various library features that are either experimental (also known as TSes), or have been but are not stable yet in the selected Standard Library implementation. It is not recommended to use this option in production code, since neither ABI nor API stability are guaranteed. This is intended to provide a preview of features that will ship in the future for experimentation purposes
+
 .. option:: -fexperimental-new-constant-interpreter
 
 Enable the experimental new constant interpreter
 
 .. option:: -fextdirs=<arg>, --extdirs <arg>, --extdirs=<arg>
 
 .. option:: -fextend-arguments=<arg>
 

 Turn on loop unroller
 
 .. option:: -funsafe-math-optimizations, -fno-unsafe-math-optimizations
 
 .. option:: -funsigned-bitfields
 
 .. option:: -funsigned-char, -fno-unsigned-char, --unsigned-char
 
-.. option:: -funstable, -fno-unstable
-
-Enable unstable and experimental features
-
 .. option:: -funwind-tables, -fno-unwind-tables
 
 .. option:: -fuse-cxa-atexit, -fno-use-cxa-atexit
 
 .. option:: -fuse-init-array, -fno-use-init-array
 
 .. option:: -fuse-ld=<arg>
 

clang/include/clang/Basic/Features.def

 FEATURE(cxx_rvalue_references, LangOpts.CPlusPlus11)
 FEATURE(cxx_strong_enums, LangOpts.CPlusPlus11)
 FEATURE(cxx_static_assert, LangOpts.CPlusPlus11)
 FEATURE(cxx_thread_local,
         LangOpts.CPlusPlus11 &&PP.getTargetInfo().isTLSSupported())
 FEATURE(cxx_trailing_return, LangOpts.CPlusPlus11)
 FEATURE(cxx_unicode_literals, LangOpts.CPlusPlus11)
 FEATURE(cxx_unrestricted_unions, LangOpts.CPlusPlus11)
-FEATURE(cxx_unstable, LangOpts.Unstable)
 FEATURE(cxx_user_literals, LangOpts.CPlusPlus11)
 FEATURE(cxx_variadic_templates, LangOpts.CPlusPlus11)
 // C++14 features
 FEATURE(cxx_aggregate_nsdmi, LangOpts.CPlusPlus14)
 FEATURE(cxx_binary_literals, LangOpts.CPlusPlus14)
 FEATURE(cxx_contextual_conversions, LangOpts.CPlusPlus14)
 FEATURE(cxx_decltype_auto, LangOpts.CPlusPlus14)
 FEATURE(cxx_generic_lambdas, LangOpts.CPlusPlus14)

 FEATURE(is_trivially_copyable, LangOpts.CPlusPlus)
 FEATURE(is_union, LangOpts.CPlusPlus)
 FEATURE(modules, LangOpts.Modules)
 FEATURE(safe_stack, LangOpts.Sanitize.has(SanitizerKind::SafeStack))
 FEATURE(shadow_call_stack,
         LangOpts.Sanitize.has(SanitizerKind::ShadowCallStack))
 FEATURE(tls, PP.getTargetInfo().isTLSSupported())
 FEATURE(underlying_type, LangOpts.CPlusPlus)
+FEATURE(experimental_library, LangOpts.ExperimentalLibrary)
 
 // C11 features supported by other languages as extensions.
 EXTENSION(c_alignas, true)
 EXTENSION(c_alignof, true)
 EXTENSION(c_atomic, true)
 EXTENSION(c_generic_selections, true)
 EXTENSION(c_static_assert, true)
 EXTENSION(c_thread_local, PP.getTargetInfo().isTLSSupported())

clang/include/clang/Basic/LangOptions.def

 LANGOPT(MSBitfields       , 1, 0, "Microsoft-compatible structure layout")
 LANGOPT(Freestanding, 1, 0, "freestanding implementation")
 LANGOPT(NoBuiltin         , 1, 0, "disable builtin functions")
 LANGOPT(NoMathBuiltin     , 1, 0, "disable math builtin functions")
 LANGOPT(GNUAsm            , 1, 1, "GNU-style inline assembly")
 LANGOPT(Coroutines        , 1, 0, "C++20 coroutines")
 LANGOPT(DllExportInlines  , 1, 1, "dllexported classes dllexport inline methods")
 LANGOPT(RelaxedTemplateTemplateArgs, 1, 0, "C++17 relaxed matching of template template arguments")
-LANGOPT(Unstable          , 1, 0, "Enable unstable and experimental features")
+LANGOPT(ExperimentalLibrary, 1, 0, "enable unstable and experimental library features")
 
 LANGOPT(DoubleSquareBracketAttributes, 1, 0, "'[[]]' attributes extension for all language standard modes")
 
 COMPATIBLE_LANGOPT(RecoveryAST, 1, 1, "Preserve expressions in AST when encountering errors")
 COMPATIBLE_LANGOPT(RecoveryASTType, 1, 1, "Preserve the type in recovery expressions")
 
 BENIGN_LANGOPT(ThreadsafeStatics , 1, 1, "thread-safe static initializers")
 LANGOPT(POSIXThreads      , 1, 0, "POSIX thread support")

clang/include/clang/Driver/Options.td

def offload_EQ : CommaJoined<["--"], "offload=">, Flags<[NoXarchOption]>,
   HelpText<"Specify comma-separated list of offloading target triples (CUDA and HIP only)">;
 
 // C++ Coroutines TS
 defm coroutines_ts : BoolFOption<"coroutines-ts",
   LangOpts<"Coroutines">, Default<cpp20.KeyPath>,
   PosFlag<SetTrue, [CC1Option], "Enable support for the C++ Coroutines TS">,
   NegFlag<SetFalse>>;
 
-defm unstable : BoolFOption<"unstable",
-  LangOpts<"Unstable">, DefaultFalse,
-  PosFlag<SetTrue, [CC1Option, CoreOption], "Enable unstable and experimental features">,
+defm experimental_library : BoolFOption<"experimental-library",
+  LangOpts<"ExperimentalLibrary">, DefaultFalse,
+  PosFlag<SetTrue, [CC1Option, CoreOption], "Control whether unstable and experimental library features are enabled. "
+          "This option enables various library features that are either experimental (also known as TSes), or have been "
+          "but are not stable yet in the selected Standard Library implementation. It is not recommended to use this option "
+          "in production code, since neither ABI nor API stability are guaranteed. This is intended to provide a preview "
+          "of features that will ship in the future for experimentation purposes">,
   NegFlag<SetFalse>>;
 
 def fembed_offload_object_EQ : Joined<["-"], "fembed-offload-object=">,
   Group<f_Group>, Flags<[NoXarchOption, CC1Option]>,
   HelpText<"Embed Offloading device-side binary into host object file as a section.">,
   MarshallingInfoStringVector<CodeGenOpts<"OffloadObjects">>;
 def fembed_bitcode_EQ : Joined<["-"], "fembed-bitcode=">,
     Group<f_Group>, Flags<[NoXarchOption, CC1Option, CC1AsOption]>, MetaVarName<"<option>">,

clang/lib/Driver/ToolChain.cpp

void ToolChain::AddCXXStdlibLibArgs(const ArgList &Args,
                                     ArgStringList &CmdArgs) const {
   assert(!Args.hasArg(options::OPT_nostdlibxx) &&
          "should not have called this");
   CXXStdlibType Type = GetCXXStdlibType(Args);
 
   switch (Type) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
 
   case ToolChain::CST_Libstdcxx:
     CmdArgs.push_back("-lstdc++");
     break;
   }
 }
 

clang/lib/Driver/ToolChains/AIX.cpp

 void AIX::AddCXXStdlibLibArgs(const llvm::opt::ArgList &Args,
                               llvm::opt::ArgStringList &CmdArgs) const {
   switch (GetCXXStdlibType(Args)) {
   case ToolChain::CST_Libstdcxx:
     llvm::report_fatal_error("linking libstdc++ unimplemented on AIX");
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
     CmdArgs.push_back("-lc++abi");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     return;
   }
 
   llvm_unreachable("Unexpected C++ library type; only libc++ is supported.");
 }
 
 ToolChain::CXXStdlibType AIX::GetDefaultCXXStdlibType() const {
   return ToolChain::CST_Libcxx;

clang/lib/Driver/ToolChains/BareMetal.cpp

 }
 
 void BareMetal::AddCXXStdlibLibArgs(const ArgList &Args,
                                     ArgStringList &CmdArgs) const {
   switch (GetCXXStdlibType(Args)) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
     CmdArgs.push_back("-lc++abi");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
   case ToolChain::CST_Libstdcxx:
     CmdArgs.push_back("-lstdc++");
     CmdArgs.push_back("-lsupc++");
     break;
   }
   CmdArgs.push_back("-lunwind");
 }

clang/lib/Driver/ToolChains/Clang.cpp

if (Arg *A = Args.getLastArg(options::OPT_fconstexpr_depth_EQ)) {
     CmdArgs.push_back(A->getValue());
   }
 
   if (Arg *A = Args.getLastArg(options::OPT_fconstexpr_steps_EQ)) {
     CmdArgs.push_back("-fconstexpr-steps");
     CmdArgs.push_back(A->getValue());
   }
 
-  if (Args.hasArg(options::OPT_funstable)) {
-    CmdArgs.push_back("-funstable");
-    if (!Args.hasArg(options::OPT_fno_coroutines_ts))
-      CmdArgs.push_back("-fcoroutines-ts");
-    CmdArgs.push_back("-fmodules-ts");
-  }
+  Args.AddLastArg(CmdArgs, options::OPT_fexperimental_library);
 
   if (Args.hasArg(options::OPT_fexperimental_new_constant_interpreter))
     CmdArgs.push_back("-fexperimental-new-constant-interpreter");
 
   if (Arg *A = Args.getLastArg(options::OPT_fbracket_depth_EQ)) {
     CmdArgs.push_back("-fbracket-depth");
     CmdArgs.push_back(A->getValue());
   }

clang/lib/Driver/ToolChains/CloudABI.cpp

void CloudABI::addLibCxxIncludePaths(const llvm::opt::ArgList &DriverArgs,
   addSystemInclude(DriverArgs, CC1Args, P.str());
 }
 
 void CloudABI::AddCXXStdlibLibArgs(const ArgList &Args,
                                    ArgStringList &CmdArgs) const {
   CmdArgs.push_back("-lc++");
   CmdArgs.push_back("-lc++abi");
   CmdArgs.push_back("-lunwind");
+  if (Args.hasArg(options::OPT_fexperimental_library))
+    CmdArgs.push_back("-lc++experimental");
 }
 
 Tool *CloudABI::buildLinker() const {
   return new tools::cloudabi::Linker(*this);
 }
 
 bool CloudABI::isPIEDefault(const llvm::opt::ArgList &Args) const {
   // Only enable PIE on architectures that support PC-relative

clang/lib/Driver/ToolChains/CrossWindows.cpp

AddClangCXXStdlibIncludeArgs(const llvm::opt::ArgList &DriverArgs,
 
   if (GetCXXStdlibType(DriverArgs) == ToolChain::CST_Libcxx)
     addSystemInclude(DriverArgs, CC1Args, SysRoot + "/usr/include/c++/v1");
 }
 
 void CrossWindowsToolChain::
 AddCXXStdlibLibArgs(const llvm::opt::ArgList &Args,
                     llvm::opt::ArgStringList &CmdArgs) const {
-  if (GetCXXStdlibType(Args) == ToolChain::CST_Libcxx)
+  if (GetCXXStdlibType(Args) == ToolChain::CST_Libcxx) {
     CmdArgs.push_back("-lc++");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
+  }
 }
 
 clang::SanitizerMask CrossWindowsToolChain::getSupportedSanitizers() const {
   SanitizerMask Res = ToolChain::getSupportedSanitizers();
   Res |= SanitizerKind::Address;
   Res |= SanitizerKind::PointerCompare;
   Res |= SanitizerKind::PointerSubtract;
   return Res;

clang/lib/Driver/ToolChains/Darwin.cpp

case ToolChain::CST_Libstdcxx:
 
     if (!IsBaseFound) {
       getDriver().Diag(diag::warn_drv_libstdcxx_not_found);
     }
 
     break;
   }
 }
+
 void DarwinClang::AddCXXStdlibLibArgs(const ArgList &Args,
                                       ArgStringList &CmdArgs) const {
   CXXStdlibType Type = GetCXXStdlibType(Args);
 
   switch (Type) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
 
   case ToolChain::CST_Libstdcxx:
     // Unfortunately, -lstdc++ doesn't always exist in the standard search path;
     // it was previously found in the gcc lib dir. However, for all the Darwin
     // platforms we care about it was -lstdc++.6, so we search for that
     // explicitly if we can't see an obvious -lstdc++ candidate.
 

clang/lib/Driver/ToolChains/FreeBSD.cpp

void FreeBSD::AddCXXStdlibLibArgs(const ArgList &Args,
                                   ArgStringList &CmdArgs) const {
   CXXStdlibType Type = GetCXXStdlibType(Args);
   unsigned Major = getTriple().getOSMajorVersion();
   bool Profiling = Args.hasArg(options::OPT_pg) && Major != 0 && Major < 14;
 
   switch (Type) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back(Profiling ? "-lc++_p" : "-lc++");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
 
   case ToolChain::CST_Libstdcxx:
     CmdArgs.push_back(Profiling ? "-lstdc++_p" : "-lstdc++");
     break;
   }
 }
 

clang/lib/Driver/ToolChains/Fuchsia.cpp

void Fuchsia::AddClangCXXStdlibIncludeArgs(const ArgList &DriverArgs,
   }
 }
 
 void Fuchsia::AddCXXStdlibLibArgs(const ArgList &Args,
                                   ArgStringList &CmdArgs) const {
   switch (GetCXXStdlibType(Args)) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
 
   case ToolChain::CST_Libstdcxx:
     llvm_unreachable("invalid stdlib name");
   }
 }
 
 SanitizerMask Fuchsia::getSupportedSanitizers() const {

clang/lib/Driver/ToolChains/Hexagon.cpp

 void HexagonToolChain::AddCXXStdlibLibArgs(const ArgList &Args,
                                            ArgStringList &CmdArgs) const {
   CXXStdlibType Type = GetCXXStdlibType(Args);
   switch (Type) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
     CmdArgs.push_back("-lc++abi");
     CmdArgs.push_back("-lunwind");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
 
   case ToolChain::CST_Libstdcxx:
     CmdArgs.push_back("-lstdc++");
     break;
   }
 }
 

clang/lib/Driver/ToolChains/MipsLinux.cpp

 void MipsLLVMToolChain::AddCXXStdlibLibArgs(const ArgList &Args,
                                             ArgStringList &CmdArgs) const {
   assert((GetCXXStdlibType(Args) == ToolChain::CST_Libcxx) &&
          "Only -lc++ (aka libxx) is supported in this toolchain.");
 
   CmdArgs.push_back("-lc++");
   CmdArgs.push_back("-lc++abi");
   CmdArgs.push_back("-lunwind");
+  if (Args.hasArg(options::OPT_fexperimental_library))
+    CmdArgs.push_back("-lc++experimental");
 }
 
 std::string MipsLLVMToolChain::getCompilerRT(const ArgList &Args,
                                              StringRef Component,
                                              FileType Type) const {
   SmallString<128> Path(getDriver().ResourceDir);
   llvm::sys::path::append(Path, SelectedMultilib.osSuffix(), "lib" + LibSuffix,
                           getOS());

clang/lib/Driver/ToolChains/NaCl.cpp

 }
 
 void NaClToolChain::AddCXXStdlibLibArgs(const ArgList &Args,
                                         ArgStringList &CmdArgs) const {
   // Check for -stdlib= flags. We only support libc++ but this consumes the arg
   // if the value is libc++, and emits an error for other values.
   GetCXXStdlibType(Args);
   CmdArgs.push_back("-lc++");
+  if (Args.hasArg(options::OPT_fexperimental_library))
+    CmdArgs.push_back("-lc++experimental");
 }
 
 void NaClToolChain::addLibCxxIncludePaths(
     const llvm::opt::ArgList &DriverArgs,
     llvm::opt::ArgStringList &CC1Args) const {
   const Driver &D = getDriver();
 
   SmallString<128> P(D.Dir + "/../");

clang/lib/Driver/ToolChains/OpenBSD.cpp

 }
 
 void OpenBSD::AddCXXStdlibLibArgs(const ArgList &Args,
                                   ArgStringList &CmdArgs) const {
   bool Profiling = Args.hasArg(options::OPT_pg);
 
   CmdArgs.push_back(Profiling ? "-lc++_p" : "-lc++");
   CmdArgs.push_back(Profiling ? "-lc++abi_p" : "-lc++abi");
   CmdArgs.push_back(Profiling ? "-lpthread_p" : "-lpthread");
+  if (Args.hasArg(options::OPT_fexperimental_library))
+    CmdArgs.push_back("-lc++experimental");
 }
 
 std::string OpenBSD::getCompilerRT(const ArgList &Args, StringRef Component,
                                    FileType Type) const {
   if (Component == "builtins") {
     SmallString<128> Path(getDriver().SysRoot);
     llvm::sys::path::append(Path, "/usr/lib/libcompiler_rt.a");
     return std::string(Path.str());

clang/lib/Driver/ToolChains/VEToolchain.cpp

void VEToolChain::AddCXXStdlibLibArgs(const ArgList &Args,
 
   CmdArgs.push_back("-lc++");
   CmdArgs.push_back("-lc++abi");
   CmdArgs.push_back("-lunwind");
   // libc++ requires -lpthread under glibc environment
   CmdArgs.push_back("-lpthread");
   // libunwind requires -ldl under glibc environment
   CmdArgs.push_back("-ldl");
+
+  if (Args.hasArg(options::OPT_fexperimental_library))
+    CmdArgs.push_back("-lc++experimental");
 }
 
 llvm::ExceptionHandling
 VEToolChain::GetExceptionModel(const ArgList &Args) const {
   // VE uses SjLj exceptions.
   return llvm::ExceptionHandling::SjLj;
 }

clang/lib/Driver/ToolChains/WebAssembly.cpp

 
 void WebAssembly::AddCXXStdlibLibArgs(const llvm::opt::ArgList &Args,
                                       llvm::opt::ArgStringList &CmdArgs) const {
 
   switch (GetCXXStdlibType(Args)) {
   case ToolChain::CST_Libcxx:
     CmdArgs.push_back("-lc++");
     CmdArgs.push_back("-lc++abi");
+    if (Args.hasArg(options::OPT_fexperimental_library))
+      CmdArgs.push_back("-lc++experimental");
     break;
   case ToolChain::CST_Libstdcxx:
     CmdArgs.push_back("-lstdc++");
     break;
   }
 }
 
 SanitizerMask WebAssembly::getSupportedSanitizers() const {

clang/test/Driver/experimental-library-flag.cpp

+// RUN: %clangxx -fexperimental-library -stdlib=libc++ -### %s 2>&1 | FileCheck --check-prefixes=CHECK,CHECK-LIBCXX %s
+// RUN: %clangxx -fexperimental-library -stdlib=libstdc++ -### %s 2>&1 | FileCheck --check-prefixes=CHECK,CHECK-LIBSTDCXX %s
+// RUN: %clangxx -fexperimental-library -stdlib=libc++ -nostdlib++ -### %s 2>&1 | FileCheck --check-prefixes=CHECK,CHECK-NOSTDLIB %s
+
+// -fexperimental-library must be passed to CC1
+// CHECK: -fexperimental-library
+
+// Depending on the stdlib in use, we should (or not) pass -lc++experimental
+// CHECK-LIBCXX: -lc++experimental
+// CHECK-LIBSTDCXX-NOT: -lc++experimental
+// CHECK-NOSTDLIB-NOT: -lc++experimental

clang/test/Driver/unstable-flag.cpp

-// RUN: %clang -funstable -### %s 2>&1 | FileCheck %s
-
-// CHECK: -funstable
-// CHECK: -fcoroutines-ts
-// CHECK: -fmodules-ts

clang/test/Lexer/has_feature_cxx_unstable.cpp

-// RUN: %clang_cc1 -funstable -E %s -o - | FileCheck --check-prefix=CHECK-UNSTABLE %s
-// RUN: %clang_cc1 -E %s -o - | FileCheck --check-prefix=CHECK-NO-UNSTABLE %s
-
-#if __has_feature(cxx_unstable)
-int has_cxx_unstable();
-#else
-int has_no_cxx_unstable();
-#endif
-// CHECK-UNSTABLE: int has_cxx_unstable();
-// CHECK-NO-UNSTABLE: int has_no_cxx_unstable();

clang/test/Lexer/has_feature_experimental_library.cpp

+// RUN: %clang_cc1 -E -fexperimental-library %s -o - | FileCheck --check-prefix=CHECK-EXPERIMENTAL %s
+// RUN: %clang_cc1 -E %s -o - | FileCheck --check-prefix=CHECK-NO-EXPERIMENTAL %s
+
+#if __has_feature(experimental_library)
+int has_experimental_library();
+#else
+int has_no_experimental_library();
+#endif
+// CHECK-EXPERIMENTAL: int has_experimental_library();
+// CHECK-NO-EXPERIMENTAL: int has_no_experimental_library();