refactor: #pragma once in every header

[balbasty]

Sweep 1 of the two mechanical sweeps deferred until the macro work (#90, #91) merged. Sweep 2 is #146, now merged.

Rebased onto de288a9 — #146 (<fastfields/…>, same header preambles) and #143 (FF_INDEX32) both landed underneath this branch. Resolved by taking main's tree wholesale for include/, src/, tests/ and CLAUDE.md, then re-running the sweep script over the merged base. No hand-editing of headers; a clean --check is the evidence.

The first commit on this branch proposed #ifndef guards everywhere. The repo owner chose #pragma once instead, which is what the branch now delivers — the net diff against main is the pragma sweep alone.

What the tree looked like

Re-counted on the merged base (the brief's pre-merge figures were 88/8/7/6 across 109 headers):

style	count
#ifndef guard only	94
#pragma once only	12
both	5
neither	6
total	117

Split by provenance, not by any decision — the 12 pragma-only headers are all impl/cuda/, i.e. all of fastfields-cuda-impl; the 6 unguarded ones are the pure umbrella headers in impl/kernels/.

The convention

#pragma once on line 1 of every header, no #ifndef include guards.

Line 1 with no exception for a licence or provenance comment: "is line 1 #pragma once" needs no judgement to apply and none to check, and it is what the twelve headers already using the pragma did. Attribution comments keep their text and sit one line lower.

#pragma once is not ISO C++, but clang, g++, nvcc and MSVC all support it, so it costs nothing against the stated Windows goal. The historical hazard — that it keys on file identity, which was ambiguous when every cross-repo dependency was a symlink — is gone: main has no .gitmodules, no gitlinks and no symlinks.

104 of the 116 non-vendored headers changed. The 12 that did not are the impl/cuda/ headers that already had the pragma on line 1.

The one exception: core/dlpack.h

Untouched, and confirmed after the rebase: still #ifndef DLPACK_DLPACK_H_ / #define DLPACK_DLPACK_H_, zero occurrences of #pragma once, byte-identical to main.

It is vendored verbatim, and that macro is what lets our copy and a system DLPack header carrying the same guard collapse into one inclusion — which #pragma once cannot do, because those are two distinct files. The script never touches it; --check treats it as exempt but still verifies it kept the guard, and fails loudly if the path disappears rather than silently dropping the exemption when files move.

Is anything else vendored?

Seven other headers carry third-party provenance. I checked each rather than assuming, and all seven get the pragma:

file	provenance
impl/kernels/atomic.h	"CUDA portion copied from PyTorch/ATen"
impl/kernels/parallel.h	"adapted from PyTorch/ATen's ParallelNative"
impl/kernels/parallel_impl.h	ditto
impl/kernels/threadpool.h	YasserAsmi/wstpool (MIT)
impl/kernels/threadpool.inl	"some of this is copied from pytorch/aten"
impl/cuda/utils.h	two helpers "(Copied from PyTorch)"
impl/kernels/distance/mesh.h	InteractiveComputerGraphics/TriangleMeshDistance

The test that settles it is not how much text came from upstream but whether the file carries an upstream guard macro to interoperate with — that is the entire reason dlpack.h keeps its guard. None of the seven does: each is guarded by a name this project invented (FF_ATOMIC, FF_PARALLEL_H, FF_THREADPOOL_H, …), or — impl/cuda/utils.h — by nothing at all, since it already used the pragma. They are also re-namespaced into ff:: via FF_NAMESPACE_BEGIN, use this project's FF_CUHOST/FF_CUDEV qualifiers and include project headers, so no upstream copy could substitute for them and none is on any include path. There is nothing for a guard to interoperate with. Copyright notices are untouched either way — this is include mechanics, not attribution.

dlpack.h remains the only verbatim third-party file in the tree.

Removing a guard is not automatically inert — audited, not assumed

A guard macro can be tested from outside the header that defines it (#ifdef FF_SPLINE), and then deleting its #define silently changes what compiles. That is the one way a sweep like this breaks something with no diagnostic, so it is a step in the script, not a spot check: it greps the whole repository for every guard macro before removing any, and refuses to run if one is mentioned in a compiled source outside its own header. --check runs the same audit, so a future header that starts testing a guard name turns it red.

Re-run against the merged tree (post-#143, post-#146): all 99 guard macros are referenced exactly once, by their own #ifndef. No #ifdef/#if defined on a guard name anywhere in include/, src/ or tests/. #143's new build-time macro FF_INDEX32 is not a header guard and is untouched.

The only mentions anywhere else are inert text — tools/consolidate.sh quoting header text it generated, one prose line in MIGRATION-PROVENANCE.md, and the script's own docstring. Those are reported, not blocking, since they cannot affect what compiles.

What is not a header guard, and survives

Only a guard bracketing the whole file is removed. Partial-file #ifndef blocks stay, and two families matter:

• FF_LIB_BOUND_SPLINE_T — eight api/*.h headers wrap the shared bound_t/spline_t declarations in it so they can be co-included. This is exactly the job #pragma once cannot do (one macro, eight files), and it is depended on downstream: fastfields-dlpack/src/ext.cpp includes all eight and has a comment saying so. Verified untouched.
• FF_POSDEF_MAX_NBATCH, FF_PP_MAX_NBATCH, FF_RESIZE_MAX_NBATCH, FF_RESTRICT_MAX_NBATCH, FF_SPLINC_MAX_NBATCH, FF_AUTOCAST_PINNED_HOST — #ifndef X / #define X <value> overridable build knobs.

The guard finder only accepts an #ifndef that is the file's first directive, whose #define has an empty replacement list, and whose #endif is the file's last directive — so none of the above can be mistaken for a guard. It scans directives with comments blanked and tracks conditional nesting, rather than pattern-matching line 1.

Also fixed, because the sweep deleted the lines

• impl/kernels/pushpull/nd.h closed with #endif FF_PUSHPULL_ND — extra tokens after #endif, ill-formed and diagnosed under -pedantic;
• impl/cpu/distance_mesh.h closed with a comment naming FF_DISTANCE_MESH while its guard was FF_CPU_DISTANCE_MESH;
• impl/kernels/distance.h had no trailing newline.

The 6 unguarded headers were harmless today — nothing but #include lines, so double inclusion was a no-op — but one added definition away from not being.

Reproducibility

tools/normalise-header-guards.py is committed, as tools/rename-macros.py and tools/normalise-include-delimiters.py were:

git checkout HEAD~1 -- include && python3 tools/normalise-header-guards.py
git diff # empty

Verified, including after the rebase — which is how the merge was resolved.

$ python3 tools/normalise-header-guards.py --check
0 header(s) would change
every header opens with #pragma once and carries no whole-file guard;
include/fastfields/core/dlpack.h keeps its upstream guard.

Everything --check verifies is per-file content rather than path (the sole exception being the one-entry vendored list, which fails loudly rather than silently if that file moves), so it keeps working if headers move between directories.

Not wired into CI, matching the precedent set by rename-macros.py. One-line follow-up if you want it as a gate.

Validation

• tools/test-baseline.sh --tree . --legs all --check tools/test-baseline.expected — row-for-row match, 59,886 checks / 13 suites / 0 failures, unmoved. (--legs default,lib cannot be --checked against the recorded file: the script compares whole reports and refuses a leg subset as "NOT COMPARABLE".)
• tools/rename-macros.py --check clean; tools/normalise-include-delimiters.py --check clean (refactor: spell the public interface <fastfields/...> #146's convention still holds after the rebase).
• make CXX=clang++ clean.
• CUDA is compile+link only with no GPU in CI, so build-cuda — now both the index32 and index64 legs from build: make the 32-bit index axis a per-backend option (FF_INDEX32), default unchanged #143, i.e. every header compiled in two CUDA configurations — and compile-probe-cuda are the bar. No runtime claim is made.

Notes

• CLAUDE.md records the rule beside the FF_-prefix rule, including the dlpack.h exception and its reason, the adaptation-vs-vendored test, and the partial-#ifndef carve-out, so nobody "fixes" any of them later.
• Touches only include/, CLAUDE.md and one new file in tools/ — no build files, so it stays clear of build: make the 32-bit index axis a per-backend option (FF_INDEX32), default unchanged #143's territory.

[balbasty]

ok. clang-format should be run for information alone, not make the CI fail (we know we are not linted)