Modernize the template to C23: opaque API, cross-compilation, and three bug fixes

[christiangda]

Brings the template up to a real C23 baseline, fixes three genuine bugs in the
list, makes the types opaque, and adds cross-compilation.

Warning

Breaking. The public API changed shape — see Migration.

🐞 Bugs fixed

Three were live in the library, all now covered by regression tests:

Bug	Effect
list_append on an empty list linked the node to itself	One-element lists were circular; list_destroy never returned. Masked because the old suite only ever appended ten at a time
list_prepend_value/list_append_value did node->data = malloc(size); node->data = value;	Leaked the buffer and aliased caller-owned memory instead of copying
list_pop left tail at the freed node	The next append wrote through a stale pointer

Two more in the build:

• $(BUILD) expands to build, which was also a phony target — make merged
  them, so every rule ordered after | $(BUILD) silently inherited
  static shared. make test was linking a shared library it never used.
• make CFLAGS=-O0 dropped -std=c23, -Iinclude and every warning. A
  command-line variable suppresses plain assignments to it in the makefile; the
  project's flags are appended with override now.

🔒 Opaque types

List and Node are incomplete outside the implementation. Three things that
compiled before are now compile errors — verified, not assumed:

same node appended twice -> list_size = 2
  head == tail ? yes   head->next == head ? yes (self-cycle)
raw malloc'd node accepted by list_prepend? yes

That is the old build. The same program now fails with invalid use of incomplete typedef 'List'.

Hiding the layout forced the read API that was missing all along — previously
the only way to read an element was list->head->data, so the struct layout
was part of the ABI. It also paid for itself: each element's bytes now live in
the same allocation as its node via a flexible array member, halving the
malloc/free traffic. No caller had to change, which is the point.

🆕 C23

-std=c23 (not the c2x draft spelling), nullptr, bool/static_assert/
typeof/alignas with no supporting headers, constexpr, [[nodiscard]]
throughout, [[noreturn]], [[reproducible]], and ckd_add from
<stdckdint.h> guarding the allocation size.

Two things worth flagging from the attributes work:

• [[reproducible]]/[[unsequenced]] are function-type attributes, so they
  go after the parameter list. The leading position is a constraint violation.
• They are also the two Clang does not implement. The header feature-detects
  them with __has_c_attribute, testing for non-zero rather than
  >= 202311L — Clang reports the C++ paper dates for the other five, so a
  date comparison would disable [[nodiscard]] on a compiler that has it.

docs/C23.md has the full write-up and a support matrix measured on real
toolchains.

🌍 Cross-compilation

The Makefile picked the shared-library extension from uname -s, i.e. the host.
Building for Linux from macOS produced liblinkedlist.dylib with
-install_name. It now asks $(CC) -dumpmachine.

make CROSS_COMPILE=aarch64-linux-gnu-
make CROSS_COMPILE=arm-none-eabi- static
make toolchain            # show what got resolved
make test CROSS_COMPILE=aarch64-linux-gnu- RUNNER="qemu-aarch64 -L /usr/aarch64-linux-gnu"

Unrecognised targets still get a static archive; make shared refuses with an
explanation rather than guessing. make test/memcheck explain themselves on a
cross build instead of failing with "cannot execute binary file".

🧪 Tests

Rewritten against the public API only — enforced, since list->head no longer
compiles. 17 tests, 220 checks.

Bare assert is gone: assert(list_append(...)) compiles the call away
entirely under -DNDEBUG, so the suite would pass while testing nothing.

🛠️ Tooling

• clangd drives IntelliSense; the cpptools engine and its Tag Parser
  fallback are off because they cannot parse C23 attributes in C. cpptools stays
  for the debugger. launch.json version corrected to 0.2.0.
• New: .clang-format, compile_flags.txt, Doxyfile, .editorconfig,
  .vscode/extensions.json.
• Static and shared libraries, install/uninstall with PREFIX/DESTDIR,
  sanitize, memcheck, format, docs, toolchain.
• Warning set now -Werror -Wconversion -Wshadow -Wcast-qual -Wstrict-prototypes -Wvla; clean under both compilers.
• CI matrix over Ubuntu GCC 14 / Clang 18 / macOS Apple Clang, plus separate
  format, valgrind, doxygen and cross-compile jobs. The macOS leg is what
  exercises the __has_c_attribute fallback.

📖 Docs

README rewritten as open-source documentation: badges, full Makefile reference
(every target, every overridable variable, worked recipes), C23 feature table,
API reference, cross-compilation guide, and an honest caveats section — starting
with the fact that a singly linked list is usually the wrong data structure.

Migration

Before	After
list_append_value(l, &v, sizeof v)	list_append(l, &v, sizeof v)
list_node_new + list_append	list_append — nodes are no longer a caller concern
list->head->data	list_at(l, 0, &size) or list_first/node_value
Node *n = list_pop(l)	list_pop(l, &out, sizeof out) or list_drop(l)
list_node_destroy(n)	gone — nothing to own

Zero-size elements are now rejected: they came back from list_at as a non-null
pointer to nothing, indistinguishable from a real element.

✅ Verified locally

gcc-16 and clang, plain and under ASan+UBSan, leaks reporting 0 leaks,
clang-format, Doxygen, staged install/uninstall, incremental rebuild, and the
README example compiling clean under -Werror. Cross-compilation logic checked
against stub toolchains reporting aarch64-unknown-linux-gnu and
arm-none-eabi.

🤖 CI — all 7 jobs green

Job	Result
clang-format	✅
test (ubuntu, gcc-14)	✅
test (ubuntu, clang-19)	✅
test (macos, Apple Clang)	✅
cross-compile (aarch64-linux-gnu)	✅ built aarch64 ELF, 220 checks under qemu
valgrind	✅
doxygen	✅

The first run failed and was worth it — it disproved two assumptions I had
written into the docs, both since fixed:

• GCC 14 reports the draft __STDC_VERSION__. -std=c23 there defines
  202000L, not 202311L; GCC only bumped the macro in 15. My guard rejected
  the newest compiler in Ubuntu 24.04 LTS. Now allowed via a narrow
  __GNUC__ >= 14 clause — narrow because GCC 13 also reports 202000L for
  -std=c2x and lacks constexpr entirely.
• Clang 18 has -std=c23 but not C23 constexpr. It reports the full
  202311L and still fails on constexpr size_t ITEM_COUNT = 10;. That landed
  in Clang 19, so 19 is the stated minimum and CI installs it from
  apt.llvm.org.

Also pinned clang-format==22.1.8 from PyPI — CI had been running 18 against a
tree formatted with 22, and they disagree.

🤖 Generated with Claude Code