[all-commits] [llvm/llvm-project] 6a10d1: [clang][docs] assert.h is not a good candidate for...

[Ian Anderson via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 6a10d1dab01f424a5baaabde150d26acfd8fe48e
      https://github.com/llvm/llvm-project/commit/6a10d1dab01f424a5baaabde150d26acfd8fe48e
  Author: Ian Anderson <iana at apple.com>
  Date:   2025-10-30 (Thu, 30 Oct 2025)

  Changed paths:
    M clang/docs/Modules.rst

  Log Message:
  -----------
  [clang][docs] assert.h is not a good candidate for a textual header (#165057)

The C standard behavior of `assert` cannot be accomplished with clang
modules, either as a normal modular header, or a textual header.

As a normal modular header:
#define NDEBUG
#include <assert.h>
This pattern doesn't work, NDEBUG has to be passed on the command line
to take effect, and then will effect all `assert`s in the includer.

As a textual header:
#define NDEBUG
#include <modular_header_that_has_an_assert.h>
This pattern doesn't work for similar reasons,
modular_header_that_has_an_assert.h captured the value of NDEBUG when
its module built and won't pick it up from the includer. -DNDEBUG can be
passed when building the module, but will similarly effect the entire
module. This has the additional problem that every module will contain a
declaration for `assert`, which can possibly conflict with each other if
they use different values of NDEBUG.

So really <assert.h> just doesn't work properly with clang modules.
Avoid the issue by not mentioning it in the Modules documentation, and
use "X macros" as the example for textual headers.

Don't use [extern_c] in the example modules, that should very rarely be
used. Don't put multiple `header` declarations in a submodule, that has
the confusing effect of "fusing" the headers. e.g. <sys/errno.h> does
not include <errno.h>, but if it's in the same submodule, then an
`#include <sys/errno.h>` will mysteriously also include <errno.h>.



To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications