Skip to content

DOC: Describe the CMake build and how to run the memory checks - #119

Open
hjmjohnson wants to merge 2 commits into
masterfrom
pr/docs-build-and-memory-checking
Open

hjmjohnson wants to merge 2 commits into
masterfrom
pr/docs-build-and-memory-checking

Conversation

@hjmjohnson

@hjmjohnson hjmjohnson commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

Re-submission of #58, reverted from master on 2026-09-24 so it can be
reviewed before merging. After review it also labels nifti_dsets_test
as NEEDS_DATA (the same line #89 adds), so the documented offline test
run passes.

Base: master. Independent: nothing has to land before it.

Commits
  • BUG: Label nifti2 dsets_test as needing the downloaded test data
  • DOC: Describe the CMake build and how to run the memory checks

Ordering for all the re-submitted work is tracked in #84.

@hjmjohnson
hjmjohnson marked this pull request as ready for review September 24, 2026 12:18
@hjmjohnson
hjmjohnson force-pushed the pr/docs-build-and-memory-checking branch from 6ca9685 to 7af234f Compare October 6, 2026 14:34

@gdevenyi gdevenyi left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review by Google Carbon

Verdict: Request Changes

Updating README.md with modern CMake, offline testing, ASan+UBSan, and Valgrind/Docker instructions is very helpful! However, testing the exact commands in README.md against current master surfaced one broken workflow and two sanitizer/valgrind flag gaps:

  1. Offline workflow (-DDOWNLOAD_TEST_DATA=OFF + ctest -LE NEEDS_DATA) currently fails on master (README.md:97-98): On master (50a9216), nifti2/CMakeLists.txt:165 (${TEST_PREFIX}_dsets_test) is missing PROPERTIES LABELS NEEDS_DATA, so running the documented cmake -S . -B build -DDOWNLOAD_TEST_DATA=OFF && cmake --build build -j && ctest --test-dir build -LE NEEDS_DATA fails on nifti2_dsets_test! Either include that 1-line set_tests_properties(${TEST_PREFIX}_dsets_test PROPERTIES LABELS NEEDS_DATA) fix here or merge PR #89 first.
  2. Missing -DCMAKE_SHARED_LINKER_FLAGS in the ASan/UBSan snippet (README.md:108-110): Right above at line 96, -DBUILD_SHARED_LIBS=ON is recommended; combining -DBUILD_SHARED_LIBS=ON with the ASan snippet fails to link libznz.so/libniftiio.so on Linux GCC unless -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined" is also passed (or -DCMAKE_C_FLAGS is used for both compile & link via CMAKE_SHARED_LINKER_FLAGS).
  3. Valgrind snippet (README.md:117) reuses Release build from line 91: Running ctest --test-dir build -T memcheck against the -DCMAKE_BUILD_TYPE=Release directory omits debug line numbers (-g) in Valgrind backtraces, and ctest -T memcheck requires MEMORYCHECK_COMMAND (valgrind) to have been present when cmake configured DartConfiguration.tcl (configuring a dedicated -B build-memcheck -DCMAKE_BUILD_TYPE=Debug as done in the Docker snippet on line 142 avoids both traps).

Comment thread README.md Resolved
Comment thread README.md
```sh
cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-sanitize-recover=all" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Google Carbon] Please also include -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined" here so users who add -DBUILD_SHARED_LIBS=ON (from line 96) don't hit undefined __asan_* / __ubsan_* symbols when linking the shared libraries on Linux GCC.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could not reproduce this: CMake puts CMAKE_C_FLAGS on the link line of C shared libraries as well as executables, so -fsanitize=address,undefined already reaches libznz.so. The documented snippet with -DBUILD_SHARED_LIBS=ON built and passed its tests with GCC 14 on Debian and with Apple clang, where the dylib link line shows the flag, so I left it unchanged.

Comment thread README.md Resolved
hjmjohnson and others added 2 commits November 17, 2026 16:33
nifti_dsets_test reads nifti_regress_data like its neighbors, but was
the one test in that block without the NEEDS_DATA label.  A build with
-DDOWNLOAD_TEST_DATA=OFF therefore failed it under
"ctest -LE NEEDS_DATA", the documented way to test without network
access.
The build instructions in README.md were two lines about 'make all',
which builds a subset of the tree with a Makefile nothing else in the
project uses.  They now describe the CMake build the CI and the install
rules actually use, and note that the Makefile is unmaintained and does
not cover nifti2 or cifti.

A new section records how to run the sanitizers and valgrind, including
three things that each cost an afternoon to work out:

  * valgrind's memcheck needs --trace-children=yes here, because most of
    the tests are shell scripts that exec the tools.  Without it valgrind
    inspects the shell, sees nothing and reports a clean run;
  * ctest -T memcheck exits 0 even when valgrind reports defects, so the
    logs have to be read;
  * valgrind refuses to start without the C library's debug symbols, and
    on distributions that ship a stripped ld.so with no debuginfo package
    -- Arch and its derivatives -- it cannot be run at all, DEBUGINFOD_URLS
    included, because those builds are not on any debuginfod server.  A
    container recipe is given.

Every command in the new sections was run against this tree.
@hjmjohnson
hjmjohnson force-pushed the pr/docs-build-and-memory-checking branch from 7af234f to c43e4d2 Compare November 17, 2026 22:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants