libnvme: add check-public-headers test

Add tools/check-public-headers.py, a companion to the existing
check-public-symbols.py, that verifies every symbol exported in a
version script has a prototype declared in one of the installed
headers.

The check reads all *.ld files, extracts their global: symbols, then
scans each installed header for a matching identifier followed by '('.
Conditional headers (MI, fabrics) are silently skipped when absent,
matching the same build conditionality as install_headers().

Register the script as a meson test alongside check-public-symbols so
it runs automatically under 'meson test'.

Signed-off-by: Martin Belanger <[email protected]>
Assisted-by: Claude Sonnet 4.6 <[email protected]>

Author: Martin Belanger

libnvme/test/meson.build

@@ -15,6 +15,14 @@ if python3_prog.found()
             meson.project_source_root() / 'libnvme',
         ],
     )
+    test(
+        'libnvme - check-public-headers',
+        python3_prog,
+        args: [
+            files('../tools/check-public-headers.py'),
+            meson.project_source_root() / 'libnvme',
+        ],
+    )
 endif
 
 # These tests all require interaction with a real NVMe device, so we don't

libnvme/tools/check-public-headers.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: LGPL-2.1-or-later
+#
+# This file is part of libnvme.
+# Copyright (c) 2025, Dell Technologies Inc. or its subsidiaries.
+#
+# Authors: Martin Belanger <[email protected]>
+#
+# Verify that every symbol exported in a version script has a prototype
+# declared in one of the installed header files.
+#
+# A __public function that appears in a .ld version script but not in any
+# installed header is technically callable by external code, but callers have
+# no declaration to include — they would need to write their own prototype or
+# use dlsym(), which defeats the purpose of a stable public API.
+#
+# Usage (standalone):
+#   python3 tools/check-public-headers.py [LIBNVME-SOURCE-ROOT]
+#
+# The source root defaults to the parent directory of this script.
+
+import re
+import sys
+import pathlib
+
+ROOT = pathlib.Path(sys.argv[1]) if len(sys.argv) > 1 else \
+       pathlib.Path(__file__).resolve().parent.parent
+
+SRC_DIR = ROOT / 'src'
+
+LD_FILES = [
+    SRC_DIR / 'libnvme.ld',
+    SRC_DIR / 'libnvmf.ld',
+    SRC_DIR / 'accessors.ld',
+    SRC_DIR / 'accessors-fabrics.ld',
+]
+
+# Mirrors the install_headers() calls in src/meson.build.
+# Conditional headers (fabrics, MI) are included here and silently skipped
+# if they don't exist, matching the same conditionality as the build.
+INSTALLED_HEADERS = [
+    # base — always installed
+    SRC_DIR / 'nvme' / 'accessors.h',
+    SRC_DIR / 'nvme' / 'endian.h',
+    SRC_DIR / 'nvme' / 'filters.h',
+    SRC_DIR / 'nvme' / 'ioctl.h',
+    SRC_DIR / 'nvme' / 'lib-types.h',
+    SRC_DIR / 'nvme' / 'lib.h',
+    SRC_DIR / 'nvme' / 'linux.h',
+    SRC_DIR / 'nvme' / 'nvme-cmds.h',
+    SRC_DIR / 'nvme' / 'nvme-types.h',
+    SRC_DIR / 'nvme' / 'tree.h',
+    SRC_DIR / 'nvme' / 'types.h',
+    SRC_DIR / 'nvme' / 'util.h',
+    # fabrics — conditional on want_fabrics
+    SRC_DIR / 'nvme' / 'accessors-fabrics.h',
+    SRC_DIR / 'nvme' / 'fabrics.h',
+    SRC_DIR / 'nvme' / 'nbft-types.h',
+    SRC_DIR / 'nvme' / 'nbft.h',
+    # MI — conditional on want_mi
+    SRC_DIR / 'nvme' / 'mi-types.h',
+    SRC_DIR / 'nvme' / 'mi.h',
+]
+
+# ---------------------------------------------------------------------------
+# Collect all symbols listed in the version scripts
+# ---------------------------------------------------------------------------
+ld_syms = {}   # symbol -> Path of the .ld file that declares it
+
+for ld_path in LD_FILES:
+    if not ld_path.exists():
+        continue
+    for line in ld_path.read_text().splitlines():
+        m = re.match(r'^\s+([a-z]\w+);', line)
+        if m:
+            ld_syms[m.group(1)] = ld_path
+
+# ---------------------------------------------------------------------------
+# Collect all names that appear as a prototype/declaration in installed headers
+# ---------------------------------------------------------------------------
+# Match any identifier immediately followed by '(' — this catches both
+# single-line and multi-line function declarations, and macro definitions
+# that alias a function name.  The libnvme_*/libnvmf_* namespace is long
+# enough that false positives from comments are not a practical concern.
+header_syms = set()
+
+for hdr_path in INSTALLED_HEADERS:
+    if not hdr_path.exists():
+        continue
+    for m in re.finditer(r'\b([a-z_]\w+)\s*\(', hdr_path.read_text()):
+        header_syms.add(m.group(1))
+
+# ---------------------------------------------------------------------------
+# Report exported symbols with no prototype in any installed header
+# ---------------------------------------------------------------------------
+errors = 0
+
+for sym, ld_path in sorted(ld_syms.items()):
+    if sym not in header_syms:
+        print(f'ERROR: {sym}() is exported in {ld_path.name} '
+              f'but has no prototype in any installed header')
+        errors += 1
+
+if errors:
+    print(f'\n{errors} error(s) found.')
+    sys.exit(1)
+
+print(f'OK: all {len(ld_syms)} exported symbols have prototypes '
+      f'in installed headers.')