#28690 build: Introduce internal kernel library

ReviewabilityReviewsAgreementSize
#28690 sedited build: Introduce internal kernel libraryWaiting on author2 (+2)Mild114 + 12 tests
  • Clarifies internal library boundaries by giving the kernel and its utilities dedicated build targets
  • Prevents node targets and the standalone kernel library from duplicating kernel source lists
  • Ready for review
  • Unaddressed objection: consumer-oriented targets encourage unnatural libraries (stickies-v)
  • Support for improved library boundaries and successful Guix builds (hebasto, janb84, w0xlt)
  • Verified by running bindings in an external test application (Sjors)
  • Verified shared library builds and source reuse under CMake (BrandonOdiwuor)
  • 114 lines added or modified outside tests
  • 12 lines added or modified in tests
  • 122 lines removed in total
  • 6 files, 2 commits
Build and CI#29 of 56
P3 · cleanup
  • P3 because it improves CMake target structure and reduces symbol leakage across targets
  • It refactors internal build definitions without fixing build breakages or platform failures
  • Ranking pass: Moved down from 14: build-target restructuring with no stated breakage fixed; deferrable relative to concrete platform and release fixes
Ranking notes
Kernel (libbitcoinkernel)#11 of 18
P2 · cleanup
  • P2 because it isolates kernel sources and trims utility dependencies away from node code
  • It completes the intended internal library architecture needed to decouple the kernel cleanly
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

This pull request creates an internal `bitcoin_kernel` static library and an associated `bitcoin_util_kernel` library in CMake. Source files containing validation, mempool, and chainstate logic are moved out of `bitcoin_node` and `bitcoin_common` into this internal kernel library, and external `libbitcoinkernel` pulls source files from it. Allowed dependency relationships between these libraries are added to `contrib/devtools/check-deps.sh` and documented in `doc/design/libraries.md`.

Problem: The internal build system did not have a dedicated internal kernel static library, requiring targets like `bitcoin_node` and `bitcoin_common` to compile kernel sources directly while the standalone `libbitcoinkernel` duplicated those source lists. Additionally, `libbitcoin_util` contained modules unneeded by the kernel, complicating dependency boundaries.

Evidence of importance:

  • The author states this PR "completes the internal library design as laid out in doc/design/libraries.md" and separates utility modules so kernel only depends on required utilities (PR description).
  • Commit 6b9f4a5075 notes that reusing the source file list facilitates compiling the external kernel library with appropriate symbol visibility alongside internal dependents.

Scope: Build system changes across CMake configuration files, architectural documentation, and the dependency checker script.

Reviewability

Paused · Waiting on author

Open objection from stickies-v with no author reply for 44 days; review would repeat what has been asked.

Waiting on (from the thread read):

  • author: response to stickies-v's proposal for content-oriented rather than consumer-oriented libraries 2026-09-18

Agreement

Mild

objection that needs an answer has none yet (stickies-v)

Thread notes: Added stickies-v's approach objection against consumer-oriented library organization (util_kernel), changing their stance to objection; the PR is currently waiting on the author's response.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
hebasto (member)objection, approachCircular dependency between libbitcoin_crypto and libbitcoin_util via memory_cleanse symbol.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2023-10-27: 'There still exist a circle dependency between libbitcoin_crypto and libbitcoin_util. In particular, the former depends on the memory_cleanse symbol.'
Status from: 2023-12-06: hebasto: 'Approach ACK 2086d1d4c3f40cce34647995ead4bff22967ffd8.'
ryanofsky (member)objection, approachLayering violation where a util header depends on a common header.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2023-12-05: 'It seems like a bug to have a util header depending on a common header.'
Status from: 2023-12-06: ryanofsky: 'Code review ACK 34970bde23dd87fc0fea5a1970880761f7184774. Main change since last review is no longer moving the spanpars'
achow101 (member)objection, approachUnnecessary linking of bitcoin_kernel into bitcoin-cli.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2026-03-30: 'I would be surprised if bitcoin-cli needed to be linked with the kernel. It appears to build without this.'
Status from: 2026-04-22: sedited: 'Addressed @achow101's comments 1, and 2, dropped left over kernel library links where they are no longer needed.'
achow101 (member)objection, approachUnnecessary linking of bitcoin_kernel into bitcoin-wallet.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2026-03-30: 'It would be surprising to me if bitcoin-wallet needs the kernel. It builds without this.'
Status from: 2026-04-22: sedited: 'Addressed @achow101's comments 1, and 2, dropped left over kernel library links where they are no longer needed.'
ajtowns (member)objection, approachAdds library complexity, backwards dependency edges from common/wallet to kernel, and fails to update design doc and check-deps.sh.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2026-04-27: 'Should be updating the design doc, and it would be nicer if this was reducing the complexity of all our libraries rather than adding another one to menagerie.'
Status from: 2026-04-28: sedited: 'Addressed @ajtowns' comment, adding some more edges that were documented by check-deps, and a new libbitcoinkernel node '
maflcko (member)objection, correctnessCMake configuration failure during cross compilation due to missing Boost::headers target.fixed · fix pushed · Resolved. · v1, not yet re-checkedchangedyes2026-07-09: 'CMake Error at src/CMakeLists.txt:127 (target_link_libraries): Target "bitcoin_kernel" links to: Boost::headers but the target was not found.'
Status from: 2026-07-09: sedited: 'Fixed previously silent merge conflict.'
w0xlt (contributor)objection, correctnessBreaks build when Bitcoin Core is consumed as a CMake subproject due to CMAKE_SOURCE_DIR pointing to the parent project directory.fixed · fix pushed · Resolved. · v1, not yet re-checkedansweredyes2026-07-21: 'Would PROJECT_SOURCE_DIR be more appropriate here? When Bitcoin Core is used as a subproject, CMAKE_SOURCE_DIR points to the parent project’s source directory.'
Status from: 2026-07-22: w0xlt: 'ACK 9b88b1b64b85e50a8371c611d093b7528ebd6e63'
stickies-v (member)objection, approachConsumer-oriented library organization creates unnatural libraries, encourages kitchen-sink behaviour, and introduces awkward targets like util_kernel.open · v1, not yet re-checkedansweredno2026-09-18: 'The consumer-oriented approach makes for libraries that don't feel natural and encourage kitchen-sink behaviour.'

Support:

  • hebasto (member) (Concept ACK, 2023-10-27) [read: libbitcoin_crypto, libbitcoin_util]: Improving internal library boundaries.
  • stickies-v (member) (Concept ACK, 2023-11-16) [read]: Supports the approach and provided a scripted-diff check.
  • theuni (member) (Concept ACK, 2023-11-22) [read: crypto]: Noted standalone crypto library benefits without nasty dependencies.
  • kashifs (contributor) (Concept ACK, 2023-11-26): Reviewed code and design in preparation for PR Review Club. [not substantive]
  • ryanofsky (member) (ACK, 2023-11-28) [read]: Changes seem good, safe, and workable.
  • pablomartin4btc (member) (Concept ACK, 2023-12-05): Concept support following Review Club notes. [not substantive]
  • ismaelsadeeq (member) (Concept ACK, 2023-12-06): Light review found it looks good. [not substantive]
  • hebasto (member) (Approach ACK, 2023-12-06) [tested: libbitcoin_util]: Verified reduction in undefined symbols in libbitcoin_util.
  • ryanofsky (member) (ACK, 2023-12-06) [read: spanparsing]: Confirmed resolution of spanparsing/layering issue.
  • yuvicc (contributor) (Concept ACK, 2025-07-12) [read: doc/design/libraries.md]: Supports removing redundant consensus library and updating libraries.md.
  • yuvicc (contributor) (ACK, 2025-11-05): ACK on rebased commits. [not substantive]
  • janb84 (member) (ACK, 2025-12-08) [tested]: Ran builds and verified reproducible Guix output across architectures.
  • Sjors (member) (Concept ACK, 2026-03-21) [tested]: Tested with a PoC iOS app exercising 100% of kernel API bindings without issues.
  • BrandonOdiwuor (contributor) (Approach ACK, 2026-03-24) [tested: CMake]: Tested shared library builds and source reuse from internal static libraries under CMake.
  • w0xlt (contributor) (ACK, 2026-05-21): Reviewed and ACKed code. [not substantive]
  • janb84 (member) (ACK, 2026-07-09): ACK following transitive library declarations cleanup. [not substantive]
  • w0xlt (contributor) (ACK, 2026-07-22) [read: kernel util]: ACK after fixing PROJECT_SOURCE_DIR and moving unused sources out of kernel util.
  • yuvicc (contributor) (ACK, 2026-09-08): re-ACK after dropping redundant ws2_32 link. [not substantive]
  • w0xlt (contributor) (ACK, 2026-09-08): re-ACK after rebase and cleanup. [not substantive]

Participants:

  • hebasto (member, support, 7 statements 2023-10-21 to 2023-12-10): Provided MSVC/UBSan fixes, raised circular dependency concern, then Approach ACKed.
  • stickies-v (member, objection, 4 statements 2023-11-16 to 2026-09-18): Objected to consumer-oriented library organization (util_kernel) and proposed content-oriented libraries.
  • theuni (member, support, 2 statements 2023-11-22 to 2023-11-26): Concept ACK; supported hex_base in crypto for standalone use.
  • kashifs (contributor, support, 1 statements 2023-11-26 to 2023-11-26): Concept ACK in preparation for PR Review Club.
  • ryanofsky (member, support, 13 statements 2023-11-28 to 2026-04-22): Reviewed and ACKed code; questioned library boundaries and util/common layering.
  • maflcko (member, objection, 8 statements 2023-11-30 to 2026-07-09): Questioned header lists, hex_base in crypto, and reported CI Boost::headers build failure.
  • pablomartin4btc (member, support, 1 statements 2023-12-05 to 2023-12-05): Concept ACK.
  • ismaelsadeeq (member, support, 1 statements 2023-12-06 to 2023-12-06): Concept ACK.
  • fanquake (member, neutral, 2 statements 2025-05-16 to 2025-05-16): Commented on removing clientversion dependency.
  • yuvicc (contributor, support, 5 statements 2025-07-12 to 2026-09-08): Concept ACK and multiple re-ACKs across rebases.
  • janb84 (member, support, 7 statements 2025-12-08 to 2026-07-09): Guix verified, suggested linking cleanup, and re-ACKed.
  • Sjors (member, support, 1 statements 2026-03-21 to 2026-03-21): Concept ACK; tested kernel bindings with external iOS app.
  • BrandonOdiwuor (contributor, support, 1 statements 2026-03-24 to 2026-03-24): Approach ACK; verified CMake build targets and source reuse.
  • achow101 (member, objection, 2 statements 2026-03-30 to 2026-03-30): Objected to redundant linking of bitcoin_kernel into bitcoin-cli and bitcoin-wallet.
  • ajtowns (member, objection, 6 statements 2026-04-27 to 2026-04-28): Criticized increasing library complexity, backwards dependency edges, and missing check-deps/doc updates.
  • w0xlt (contributor, support, 8 statements 2026-05-21 to 2026-09-08): Pointed out CMAKE_SOURCE_DIR subproject issue and unused sources, then re-ACKed.

Files

12 lines under test/bench/ci.

  • src/CMakeLists.txt +54/-37
  • src/kernel/CMakeLists.txt +16/-69
  • src/util/CMakeLists.txt +25/-12
  • doc/design/libraries.md +17/-4
  • contrib/devtools/check-deps.sh +12/-0
  • src/wallet/CMakeLists.txt +2/-0

Card

The short text the ranking pass compares across PRs.

This pull request introduces an internal libbitcoin_kernel static library and splits out a libbitcoin_util_kernel library in CMake to house utilities required by kernel code. Previously, kernel files were compiled directly into bitcoin_node and bitcoin_common, while the external libbitcoinkernel target maintained a duplicate list of source files. The change unifies these sources under explicit internal library targets, aligns the build system with the design in doc/design/libraries.md, and adds dependency rules to check-deps.sh.

Data

dossier JSON · extract JSON · model ledger, generated 2026-09-19T01:21, confidence high, input hash a57a12c1ad7f426a
thread read through 2026-09-18 (120 statements), head 54ecfc9692
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: Build system, Needs rebase

Categories

Build and CI

P3 · cleanup (ranking pass: Moved down from 14: build-target restructuring with no stated breakage fixed; deferrable relative to concrete platform and release fixes)

The change refactors CMake static library targets to establish dedicated internal libraries for the kernel and kernel utilities. While it formalizes target boundaries and reduces symbol leakage, it does not fix a platform failure or release-integrity issue, making it a worthwhile internal build improvement.

Membership: Carries the 'Build system' label and primarily modifies CMake build files ('src/CMakeLists.txt', 'src/kernel/CMakeLists.txt', 'src/util/CMakeLists.txt').

Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 2

Kernel (libbitcoinkernel)

P2 · cleanup

Separating kernel sources and paring down utility dependencies advances the core work of removing node dependencies from kernel code. The author notes that this 'completes the internal library design as laid out in doc/design/libraries.md' and facilitates cleanly compiling the external kernel library alongside internal dependents.

Membership: Extracts validation, mempool, and chainstate sources into a dedicated internal kernel library and isolates kernel-specific utility dependencies.

Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 2