[Clang] Add `-funstable` flag to enable unstable and experimental features

[egorzhdan]

Summary

This new flag enables __has_feature(cxx_unstable) that would replace libc++ macros for individual unstable/experimental features, e.g. _LIBCPP_HAS_NO_INCOMPLETE_RANGES or _LIBCPP_HAS_NO_INCOMPLETE_FORMAT.

This would make it easier and more convenient to opt-in into all libc++ unstable features at once.

[zoecarver]

This looks great, thanks Egor!

[ldionne]

Oops, this seems to have happened while I was on vacation. I wanted to have a wider discussion here before shipping the patch. Let's have it now and we can make post-commit changes depending on where the discussion leads.

So, what we're trying to achieve here is to provide a user-controlled flag to enable things that are not "production ready". This includes:

• TSes (since we remove them after shipping the "real thing" for two releases)
• Standardized features that we implement only in part (for example <ranges>, where we don't yet have a fully coherent thing to ship, so we'd rather not pretend that we ship it in a stable way yet)
• Standardized features that we know for a fact are about to be broken by the Standard itself (this happened with <ranges> and <format> recently)

The problem this solves is that in the current state of things, we end up simply not shipping those features at all by fear that users are going to start depending on them, and then we'll break them. We want to be able to ship these features without actually committing to their stability.

We considered a few alternative directions for this patch, which we rejected:

• -fexperimental: We decided not to go with this because we wanted to convey the fact that said features were unstable, and hence dangerous to use in production code
• -std=c++latest: This would be close to what MSVC does. We decided not to go down this route because we felt like it didn't properly convey the notion of instability. Instead, we felt that -std=c++latest could/should be a simple alias for whatever the latest known standard is (which is not part of this patch).

Does anyone have thoughts?

clang/include/clang/Basic/LangOptions.def

153

The documentation of this option should be way more beefy. Something like:

Enable unstable and experimental language and library features.

This option enables various language and library features that are either experimental (also known as TSes), or have been standardized but are not stable yet. This option should not be used in production code, since neither ABI nor API stability are guaranteed.

We should also provide documentation inside clang/docs/ClangCommandLineReference.rst.

clang/lib/Driver/ToolChains/Clang.cpp

5728

We should also be adding -lc++experimental if the standard library is libc++.

[Mordante]

Thanks for implementing this @egorzhdan! Thanks @ldionne for the notification.

-funstable is an option that controls multiple flags therefore I think it would be good to have a separate flag to opt-in for unstable/incomplete libc++ features. That makes it easier to _only_ opt-in to these features. Then -funstable can also enable that flag. Maybe -funstable-libc++ and adding a feature libcxx_unstable that we can use in libc++ to detect that the flag was set.

clang/include/clang/Basic/LangOptions.def

153

+1

clang/lib/Driver/ToolChains/Clang.cpp

5727

Is this option still useful? In LLVM 14 the <coroutine> header is no longer experimental. The experimental header will soon be removed.

[egorzhdan]

Apologies for landing this too quickly! I'll adjust this logic in a separate patch: https://reviews.llvm.org/D121141

In D120160#3352399, @Mordante wrote:

-funstable is an option that controls multiple flags therefore I think it would be good to have a separate flag to opt-in for unstable/incomplete libc++ features. That makes it easier to _only_ opt-in to these features.

@Mordante could you please elaborate a little bit, are you proposing a separate flag that would be equivalent to -Xcc -funstable (essentially to enable LangOpts.Unstable but not the rest of the flags) and have a different spelling to indicate that it is specific to libc++?

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)

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(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">,
+  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>">,
     HelpText<"Embed LLVM bitcode (option: off, all, bitcode, marker)">,
     Values<"off,all,bitcode,marker">, NormalizedValuesScope<"CodeGenOptions">,

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");
+  }
+
   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/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();