#28690 build: Introduce internal kernel library
https://github.com/bitcoin/bitcoin/pull/28690 · · +126/-122 in 6 files, 2 commits · labels: Build system
Goal
- Prevent the kernel library build definitions from diverging from core node builds
- Stop the kernel from pulling in unwanted node utilities such as networking and process execution
This PR introduces an internal `libbitcoin_kernel` static library target and a companion `bitcoin_util_kernel` target containing only the utility modules needed by the kernel. The external `libbitcoinkernel` shared library is updated to re-use source lists from these internal static targets rather than maintaining an independent list of sources. It also updates dependency-checking scripts and documentation to reflect the new library boundaries.
Problem: Currently, `libbitcoinkernel` manually duplicates a large list of source files also compiled for `bitcoind` and `bitcoin_node`, making build configurations prone to drift. Additionally, the broad `util` library pulls in unnecessary dependencies (like socket and process execution helpers) that the kernel should not rely on.
Category: Build and CI (#18 of 55)
P3 · cleanup
- P3 because it organizes internal build targets without altering release outputs
- Cleans up dependency tracking without fixing an active build breakage
It reorganizes internal static library targets and de-duplicates source lists between external and internal targets, reducing CMake maintenance friction.
Membership: Modifies CMakeLists.txt across src, kernel, and util, and updates contrib/devtools/check-deps.sh
Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 1
Category: Kernel (libbitcoinkernel) (#6 of 18)
P3 · decoupling
- P2 because it enforces kernel isolation from unwanted node utilities at the build level
- Helps safeguard library modularity and unblocks extracting the kernel into a standalone repo
As stated by the author, 'this is more about establishing a moat to prevent new entanglements on the build system level.' It solidifies the boundary around the kernel but provides internal architectural cleanup rather than direct new user-facing functionality.
Membership: Introduces libbitcoin_kernel internal library and separates kernel utility dependencies
Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 2
Reviewability: Ready
- Ready to review now
- Branch is rebased with passing CI and incorporates the latest suggestions
The PR is clean against master, passes CI, and latest commits have received multiple re-ACKs.
Author status: active
Resolved concerns:
- Redundant linkage of `bitcoin_kernel` to `bitcoin-cli` and `bitcoin-wallet` was pointed out by achow101 and removed by the author.
- Concerns around introducing additional utility libraries versus migrating unused utilities to `common` were raised by ryanofsky and ajtowns; author provided rationale around build-time boundary enforcement, updated documentation, and reviewers did not push back.
- Missing dependency allowances in `contrib/devtools/check-deps.sh` and documentation in `doc/design/libraries.md` were flagged by ajtowns and resolved in subsequent pushes.
- CMake configuration error when cross-compiling without Boost headers was reported by maflcko and resolved using `TARGET_NAME_IF_EXISTS`.
Agreement: Strong
- Strong consensus on establishing explicit internal targets for the kernel
- Verified on multiple platforms with Guix reproducible builds (janb84)
- Verified compatibility with a downstream proof-of-concept iOS app (Sjors)
- Debated library structure options and settled them without blocking objections (ryanofsky, ajtowns)
- Re-approved after the latest push (yuvicc, w0xlt)
Strong consensus with multiple ACKs; design questions by ajtowns and ryanofsky were addressed and settled.
The PR has substantial review from 16 contributors over an extended period, multiple tested ACKs on recent head revisions, and all technical suggestions have been addressed.
- janb84 and yuvicc provided explicit re-ACKs on recent commits
- w0xlt verified CMake targets and provided re-ACK
- Earlier topology questions from ajtowns were answered and accompanied by doc and script updates
Objections:
| Reviewer | Kind | Harm | Status | Blocking | Author replied | Quote |
|---|---|---|---|---|---|---|
| ajtowns | approach | Adds another library to the existing menagerie and creates dependency edges from common and wallet into the kernel | resolved | no | yes | 2026-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... Adding deps from common/util/wallet to the kernel seems backwards to me.' Settled: 2026-04-28: author updated libraries.md and check-deps, explained rationale regarding policy dependencies, and ajtowns did not object further |
| achow101 | interface | Unnecessary linking of kernel target into bitcoin-cli and bitcoin-wallet | resolved | no | yes | 2026-03-30: 'I would be surprised if bitcoin-cli needed to be linked with the kernel. It appears to build without this.' Settled: 2026-04-22: 'dropped left over kernel library links where they are no longer needed.' |
| hebasto | correctness | circular dependency between libbitcoin_crypto and libbitcoin_util on memory_cleanse | resolved | no | yes | 2023-10-27: 'There still exist a circle dependency between libbitcoin_crypto and libbitcoin_util. In particular, the former depends on the memory_cleanse symbol.' Settled: 2023-10-30: 'Addressed @hebasto's comment, moved cleanse files to crypto library.' |
| ryanofsky | correctness | layering violation where a util header depends on a common header | resolved | no | yes | 2023-12-05: 'It seems like a bug to have a util header depending on a common header.' Settled: 2023-12-06: 'Addressed @ryanofsky's comment, undo changes to the spanparsing module.' |
| maflcko | correctness | CI build failure during CMake generation due to missing Boost::headers target for bitcoin_kernel | resolved | yes | yes | 2026-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.' Settled: 2026-07-09: 'Fixed previously silent merge conflict.' |
| w0xlt | correctness | CMAKE_SOURCE_DIR breaks builds when Bitcoin Core is used as a CMake subproject | resolved | no | yes | 2026-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.' Settled: 2026-07-22: 'switched to PROJECT_SOURCE_DIR.' |
Support:
- janb84: Verified reproducible Guix builds across architectures and approved the CMake refactoring
- w0xlt: Reviewed CMake source properties, proposed improvements, and verified builds
- yuvicc: Tested and re-ACKed the CMake target split and cleanup
- BrandonOdiwuor: Verified CMake build targets and source reuse for external shared library
- Sjors: Tested kernel API bindings against an external iOS application
- hebasto: tested undefined symbols in libbitcoin_util and Approach ACKed
Participants: hebasto (objection), stickies-v (support), theuni (support), kashifs (support), ryanofsky (objection), maflcko (objection), pablomartin4btc (support), ismaelsadeeq (support), fanquake (neutral), yuvicc (support), janb84 (support), Sjors (support), BrandonOdiwuor (support), achow101 (objection), ajtowns (objection), w0xlt (objection)
State derived from the lists: substantive support, no open objection (janb84, w0xlt, yuvicc, BrandonOdiwuor, Sjors, hebasto)
Review verdicts (DrahtBot): 2 (+2)
- ACK: yuvicc, w0xlt
- Stale ACK: ryanofsky, janb84
- Approach ACK: hebasto, BrandonOdiwuor
- Concept ACK: stickies-v, theuni, kashifs, pablomartin4btc, ismaelsadeeq, Sjors
Dependencies
Enables:
- Enables future decoupling of mempool and validation from node internals
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
This PR introduces the internal static library target `libbitcoin_kernel` alongside `bitcoin_util_kernel`, formalizing the CMake build boundaries for the libbitcoinkernel project. It eliminates duplication between the internal source lists and the external shared library target, while restricting kernel code from accessing non-kernel utilities like sockets and process execution. The PR has gathered broad review and multiple ACKs across several years of development, with all major topology and interface concerns resolved.