automate checking API tags vs. ifdef guards


For the BRS task "Check non-stable API macros (U_HIDE_DRAFT_API and others)" =


  • Write a script like the header test (or extend that one).

  • Make it work. Add it to a build bot.

  • For each public header file:

  • Write a temporary .cpp file with one line like #include "unicode/locid.h"

  • Preprocess it (only) preserving comments. ~/icu$ clang++ -Imine/src/icu4c/source/common -C -E -o testinclude-normal.i testinclude.cpp

  • For each of {draft, deprecated, internal, system, obsolete} preprocess it again with the corresponding ifdef guard set to "hide". For example, for draft: clang++ -Imine/src/icu4c/source/common -C -E -DU_HIDE_DRAFT_API=1 -o testinclude-draft.i testinclude.cpp

  • Check that the hide-draft output contains no @draft. grep '@draft' testinclude-draft.i should be empty.

  • Diff the normal vs. hide output. diff -u testinclude-normal.i testinclude-draft.i > diff-draft.txt

  • Check that this diff does not contain any of the other API tags. egrep '^-.*@(stable|deprecated|internal|system|obsolete)' -A 3 diff-draft.txt should be empty.

In this case, right now, the output is not empty but rather

In other words, this constant is guarded by U_HIDE_DRAFT_API but should be guarded by U_HIDE_INTERNAL_API.

Issue: There are some APIs (some enums, enum constants, virtual methods) that we cannot guard with ifdefs.

Solution for this: Add another ifdef guard like U_FORCE_HIDE_DRAFT_API which cannot be used for real, but which we can add for documentation and to make the grep above come out empty by setting this guard also on the preprocessor command line.


Markus Scherer
October 2, 2019, 4:19 PM

Submitted follow-up ticket for @internal tags.

Shane Carr
October 1, 2019, 1:39 AM

Reminder to please close this ticket if work is done.

Your pinned fields
Click on the next to a field label to start pinning.


Markus Scherer


Markus Scherer




Time Needed


Fix versions