ICU-22876 add U_SHOW_CPLUSPLUS_HEADER_API for C++ header-only APIs

[markusicu]

This lets users who define U_SHOW_CPLUSPLUS_API=0 to not rely on unstable C++ DLL exports use C++ header-only APIs on top of stable C exports.

As discussed in the 2024-sep-12 ICU-TC meeting.

(FYI All of these visibility controls are marked @internal.)

Checklist

• Required: Issue filed: https://unicode-org.atlassian.net/browse/ICU-22876
• Required: The PR title must be prefixed with a JIRA Issue number.
• Required: The PR description must include the link to the Jira Issue, for example by completing the URL in the first checklist item
• Required: Each commit message must be prefixed with a JIRA Issue number.
• Issue accepted (done by Technical Committee after discussion)
• Tests included, if applicable
• API docs and/or User Guide docs changed or added, if applicable

[jira-pull-request-webhook]

Notice: the branch changed across the force-push!

• icu4c/source/common/unicode/utypes.h is different

View Diff Across Force-Push

~ Your Friendly Jira-GitHub PR Checker Bot

[richgillam]

Looks great.

By the way, I checked, and even though we prohibit use of C++ APIs, we (Apple) still (for some reason) explicitly define U_SHOW_CPLUSPLUS_API to be 1 in our own makefiles. I'm going to guess it's so that we could still run the C++ unit tests, since the C unit tests don't replicate all the checks that are in the C++ ones, but that's just a guess. There might be other reasons, and there might be things we could do to allow testing through the C++ interfaces without exposing them to the world (or maybe I'm wrong and this works fine as it is). @pedberg-icu might be able to fill in some background here.

[markusicu]

@richgillam I suggest you turn on U_SHOW_CPLUSPLUS_API only for integration testing ICU, and turn it off for anyone using ICU.

[pedberg-icu]

By the way, I checked, and even though we prohibit use of C++ APIs, we (Apple) still (for some reason) explicitly define U_SHOW_CPLUSPLUS_API to be 1 in our own makefiles. I'm going to guess it's so that we could still run the C++ unit tests, since the C unit tests don't replicate all the checks that are in the C++ ones, but that's just a guess. There might be other reasons, and there might be things we could do to allow testing through the C++ interfaces without exposing them to the world (or maybe I'm wrong and this works fine as it is). @pedberg-icu might be able to fill in some background here.

@richgillam As I recall, in the Apple makefiles, U_SHOW_CPLUSPLUS_API is set to 1 for when Apple builds ICU and runs unit tests. But when Apple clients are building against ICU headers, they are not getting the makefile override, and they normally get the default setting of U_SHOW_CPLUSPLUS_API in utypes.h, which Apple changes to be 0. And furthermore, if a client externally overrides U_SHOW_CPLUSPLUS_API to be 1, they will get all sorts of compile warnings about that resulting in code that is not binary-compatible across updates and cannot be used in production.

[richgillam]

@richgillam As I recall, in the Apple makefiles, U_SHOW_CPLUSPLUS_API is set to 1 for when Apple builds ICU and runs unit tests. But when Apple clients are building against ICU headers, they are not getting the makefile override, and they normally get the default setting of U_SHOW_CPLUSPLUS_API in utypes.h, which Apple changes to be 0. And furthermore, if a client externally overrides U_SHOW_CPLUSPLUS_API to be 1, they will get all sorts of compile warnings about that resulting in code that is not binary-compatible across updates and cannot be used in production.

@pedberg-icu Ah! That totally makes sense. I do see our local change to do that now. Thanks for the explanation!