Improving diagnostics when moving standard library headers


In libc++, we moved the <experimental/optional> header to <optional>. To guide users when they try to use <experimental/optional>, that file now contains:

    #error "<experimental/optional> has been removed. Use <optional> instead."

The problem is that it traps people using __has_include(<experimental/optional>) to detect whether they should be using std::experimental::optional or std::optional on the version of the standard library they're using. For example:

    #if __has_include(<experimental/optional>)
    # include <experimental/optional>
    # include <optional>

This is currently always broken, since <experimental/optional> is always provided, but including it is an error.

I believe a better situation would be to remove the header, but somehow have a way of providing a better compiler diagnostic than the default one when that header is included. The default diagnostic will just say “I can’t find this header!”, whereas we really want to say "This header has been moved over there". Ideally, this sort of feature would also be usable by other libraries, not just the standard library, but I’d welcome just about any solution for now.

My question: Do we have a way of achieving what I'm requesting today? If not, does anyone have ideas about how to achieve this? My guess is that a pragma in the header that's been moved would not work, because that means __has_include would have to know way more than it probably does today.


At least at a minimum could we have <experimental/optional> be:

#include <optional>
#error "<experimental/optional> has been removed. Use <optional> instead."

That way we can have <experimental/optional> for application users to move over to <optional>, but have library writers have a way to provide “backward” compatible libraries (ie, libraries that need to work on systems that do not yet have <optional>, where checking then using <experimental/optional> is a legit operation)?


Why would the user write the code in that way, though? Wouldn’t they want “has_include optional, include optional, else include experimental/optional”? to prefer the final/standardized version

Actually, the problem is deeper than this. Since we removed support for <experimental/optional> completely and is only provided in C++17 and above, we created a hole for users that want in C++14. They just can’t get it anymore, whereas previously they would have used <experimental/optional>. As much as I hate to say this, I think the answer to this question is just “you’re using experimental features, sorry if they go away.” Or, alternatively, we could keep providing <experimental/optional> in C++14 mode.

Given that the nature of the problem is different than what I initially thought, I don’t think it is worth pursuing any kind of compiler change to enable what I talked about in the original message.


Fair enough - yeah, I’d lodge a relatively uninformed vote for keeping experimental/optional available to C++14 users - but I don’t really know the details of the wording for experimental, cost involved in doing so, etc.

Would a better solution be to simply have <experimental/optional> #include (perhaps with some namespace-wrapping?), and in C++17+ mode have a #warning instead of that #error?

It seems that would create a good transition plan for everyone involved. So something like:


#if __cplusplus >=20170101

#warning “<experimental/optional> has been removed. Use instead.”





Then, in :


namespace std {


namespace experimental {


/// And So on?

Would a better solution be to simply have <experimental/optional> #include <optional> (perhaps with some namespace-wrapping?), and in C++17+ mode have a #warning instead of that #error?

Seems like a better fix, yes.

Would a better solution be to simply have <experimental/optional> #include <optional> (perhaps with some namespace-wrapping?), and in C++17+ mode have a #warning instead of that #error?

Seems like a better fix, yes.

Just to follow up on this. It’s been said before, but the problem is that std::experimental::optional and std::optional are not the same thing. std::experimental::optional is frozen in time, but std::optional will keep evolving. Hence, we would really need to keep providing two implementations that may start diverging with time. This is explained here:

I think what this means is simply that a library that tries to be cross-platform and stable through time can’t use experimental features in its interface, since those are not guaranteed to be stable. This is somewhat unfortunate, but it’s explicit in the fact that those features are “experimental”.

The other option would be to do like libstdc++: just keep std::experimental::optional around forever, and fork (i.e. copy-paste) that code into std::optional. Then, keep evolving std::optional and let it diverge from std::experimental::optional. It’s a valid choice to make, but it’s not what libc++ is doing because of the reasons explained in

I personally think that deprecating TSes (what libc++ does) is better in the long term — users pay a cost upfront when they need to update, but it’s better in the long run because they’re using the “real” standardized version of the feature.


I concur (which is unsurprising, because I initiated the discussion that
led to the current state, and wrote
deprecation.html )

-- Marshall

A nit: "May start diverging with time" is too optimistic.
"Have diverged, and will continue to diverge in the future" is the correct

-- Marshall