Skip to content

doc: note the Windows CRLF/BerkeleyDB build failure in CLAUDE.md - #3268

Open
PrestackI wants to merge 1 commit into
gridcoin-community:developmentfrom
PrestackI:doc/windows-contributors-build-note
Open

doc: note the Windows CRLF/BerkeleyDB build failure in CLAUDE.md#3268
PrestackI wants to merge 1 commit into
gridcoin-community:developmentfrom
PrestackI:doc/windows-contributors-build-note

Conversation

@PrestackI

Copy link
Copy Markdown
Contributor

CLAUDE.md documents only the Linux-native build. On Windows that path fails in a way whose cause is not obvious, and nothing in the tracked docs warns about it.

The failure

src/bdb53/dist/configure is a POSIX shell script. .gitattributes marks the tree * text=auto with no eol=lf override for src/bdb53, so a clone made with Git-for-Windows' default core.autocrlf=true checks that script out with CRLF. The bundled BerkeleyDB build then dies on it.

Two details make it easy to misdiagnose, and the wording here is deliberate about both:

  • It is not a configure-time failure. BerkeleyDB is wired through ExternalProject_Add with a CONFIGURE_COMMAND (src/bdb53/CMakeLists.txt:67-70), and an ExternalProject's configure step runs at build time. cmake -B build returns 0; cmake --build build is what fails. A contributor whose configure succeeded would otherwise conclude the note does not apply to them.
  • It does not block all compilation. leveldb and secp256k1 are plain add_subdirectory targets with no dependency on BerkeleyDB_Project, so under -j they compile concurrently with the failure.

The change

Adds a short ### Windows Contributors subsection after the Linux-native build block, pointing at a WSL-native clone as the fix.

It also scopes the two existing Windows references, which currently mislead:

  • doc/build.md ("Linux Native") is named as the reference for the normal development flow.
  • doc/build-windows-wsl.md is scoped to the win64 case only. Its sole build command is ./build_targets.sh TARGET=win64 and it verifies build_win64/src/gridcoinresearchd.exe — it produces no build/ tree, so it does not serve the ctest --test-dir build loop that CLAUDE.md documents directly below.
  • doc/build-msys2.md is deliberately not linked: it is a three-line deprecation stub that redirects to the WSL guide, and MSYS2 builds against a Windows-filesystem checkout, i.e. it reproduces the very failure being described.

The gridcoin-gui-wsl skill is mentioned for Qt GUI iteration, qualified as GUI-only since it configures -DENABLE_TESTS=OFF.

Scope

Markdown only — 17 added lines in one file, nothing removed. No source, CMake, test, workflow, or lint configuration is touched.

Not verified

The quoted error string Syntax error: newline unexpected was not reproduced end-to-end. The CRLF cause is confirmed directly (od -c on the checked-out file shows #!/bin/sh\r\n), but the exact message is a dash/ash rendering and may differ under another shell. Happy to soften it to "a shell syntax error" if a maintainer prefers not to assert a specific string.

If src/bdb53/** eol=lf is ever added to .gitattributes, this subsection becomes obsolete and should be deleted rather than updated.

CLAUDE.md documents only the Linux-native build. On Windows that path fails
in a way whose cause is not obvious: `src/bdb53/dist/configure` is a POSIX
shell script, and `.gitattributes` marks it `text=auto`, so a clone with
Git-for-Windows' default `core.autocrlf=true` checks it out with CRLF.

`cmake -B build` still succeeds — BerkeleyDB is wired through
`ExternalProject_Add` with a `CONFIGURE_COMMAND`, which runs at build time —
so the failure surfaces from `cmake --build build` instead, which makes it
easy to misattribute.

Add a short Windows Contributors subsection pointing at the WSL-native
clone as the fix, and scope the two existing Windows references: doc/build.md
for the native flow, and doc/build-windows-wsl.md only for the win64
cross-compile, since that guide produces build_win64/*.exe rather than the
build/ tree the Tests section uses.
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.

1 participant