doc: Document compiler configuration for native depends packages #33902

pull willcl-ark wants to merge 2 commits into bitcoin:master from willcl-ark:doc-depends-cc changing 1 files +130 −30
  1. willcl-ark commented at 3:23 pm on November 18, 2025: member

    Fixes: #33859

    Previously one had to read the Makefile (and various *.mk configuration files) to see how to correctly override CC and CXX when building native depends packages.

    Detail this in README.md to make it clearer.

  2. DrahtBot commented at 3:23 pm on November 18, 2025: contributor

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33902.

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    ACK hebasto, maflcko

    If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #32162 (depends: Switch from multilib to platform-specific toolchains by hebasto)

    If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

  3. hebasto commented at 3:26 pm on November 18, 2025: member
    Concept ACK. Thanks!
  4. willcl-ark commented at 3:27 pm on November 18, 2025: member
    Forgot to say, very happy to drop the second commit if wanted.
  5. in depends/README.md:188 in 7f17cf6d61 outdated 
    155+```
156+
157+To ensure both native and target use Clang:
158+
159+```
160+make build_CC=clang build_CXX=clang++ host_CC=clang host_CXX=clang++
    hebasto commented at 3:30 pm on November 18, 2025:
    How is this better than make build_CC=clang build_CXX=clang++ CC=clang CXX=clang++?
    willcl-ark commented at 3:36 pm on November 18, 2025:

    They should be exactly equivalent.

    I used my version as I had just described build_CC and host_CC and it would seem a little odd (to me) to exemplify with build_CC and CC, although as I re-read it now this example appears in the CC, CXX section.

    I think therefore I should set make build_CC=clang build_CXX=clang++ CC=clang CXX=clang++ as the primary example for this section, and perhaps use make build_CC=clang build_CXX=clang++ host_CC=clang host_CXX=clang++ as an “ultimately explicit” final variation?

    hebasto commented at 10:21 am on November 19, 2025:

    In most situations where the compiler needs to be specified, users simply run:

    0make CC=clang CXX=clang++

    Only in rare cases (https://github.com/bitcoin/bitcoin/pull/33902#discussion_r2541427389, #33902 (review), #33902 (review)) does this need to be extended to:

    0make CC=clang CXX=clang++ build_CC=clang build_CXX=clang++
    fanquake commented at 1:18 pm on November 21, 2025:

    Only in rare cases

    I don’t think wanting to build without having a GCC installation should be considered rare? Other than the clang-only Nix example linked too above, we are actively trying to make that “normal” for some of our builds, i.e #30206.

    fanquake commented at 1:24 pm on November 21, 2025:

    They should be exactly equivalent.

    Unfortunately this isn’t the case. make build_CC=clang build_CXX=clang++ host_CC=clang host_CXX=clang++ doesn’t work properly on a machine with no g++, because Boosts CMake will still try and find g++, and fail. Arguably this is also a CMake issue that we should fix/workaround in some way, because there’s no reason for Boost to try and find a compiler, when we aren’t compiling anything, and only need to copy headers. In this case, you do need to use make build_CC=clang build_CXX=clang++ CC=clang CXX=clang++.

    For example, on a Chimera Linux machine:

     0gmake build_CC=clang build_CXX=clang++ host_CC=clang host_CXX=clang++ -C depends/ -j12 build_TAR=gtar
 1gmake: Entering directory '/bitcoin/depends'
 2Extracting native_capnp...
 3/bitcoin/depends/sources/capnproto-cxx-1.2.0.tar.gz: OK
 4Preprocessing native_capnp...
 5Configuring native_capnp...
 6-- The CXX compiler identification is Clang 21.1.4
 7-- Detecting CXX compiler ABI info
 8<snip>
 9done
10Configuring boost...
11CMake Error at /usr/share/cmake-4.1/Modules/CMakeDetermineCXXCompiler.cmake:47 (message):
12  Could not find compiler set in environment variable CXX:
13
14  g++.
15
16Call Stack (most recent call first):
17  CMakeLists.txt:13 (project)
18
19
20CMake Error: CMAKE_CXX_COMPILER not set, after EnableLanguage
21-- Configuring incomplete, errors occurred!
22gmake: *** [funcs.mk:344: /bitcoin/depends/aarch64-unknown-linux-musl/.boost_stamp_configured] Error 1

    Using CC=clang CXX=clang++:

     0build_CC=clang build_CXX=clang++ CC=clang CXX=clang++ -C depends/ -j12 build_TAR=gtar
 1gmake: Entering directory '/bitcoin/depends'
 2Extracting native_capnp...
 3/bitcoin/depends/sources/capnproto-cxx-1.2.0.tar.gz: OK
 4Preprocessing native_capnp...
 5Configuring native_capnp...
 6-- The CXX compiler identification is Clang 21.1.4
 7<snip>
 8done
 9Configuring boost...
10-- The CXX compiler identification is Clang 21.1.4
11-- Detecting CXX compiler ABI info
12-- Detecting CXX compiler ABI info - done
13-- Check for working CXX compiler: /usr/sbin/clang++ - skipped
14-- Detecting CXX compile features
15-- Detecting CXX compile features - done
16-- Boost: using system layout: include, bin, lib/, lib//cmake
  6. maflcko approved
  7. maflcko commented at 3:53 pm on November 18, 2025: member

    lgtm

    review ACK 17577646f77e20783ffdd9f322f85e96da2265 🌴

    Signature:

    0untrusted comment: signature from minisign secret key on empty file; verify via: minisign -Vm "${path_to_any_empty_file}" -P RWTRmVTMeKV5noAMqVlsMugDDCyyTSbA3Re5AkUrhvLVln0tSaFWglOw -x "${path_to_this_whole_four_line_signature_blob}"
1RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
2trusted comment: review ACK 17577646f77e20783ffdd9f322f85e96da2265 🌴
3b6tuB1ff+N8xGzUilBsW1CSxIOpk4gK7SE473C8JMS+vg4aU5H4YbP04c0HL3NEDxTZkxKFJBRcJ9RVAQ9t7DQ==
  8. DrahtBot requested review from hebasto on Nov 18, 2025
  9. in depends/README.md:186 in 17577646f7 
    181+Setting `CC` and `CXX` environment variables will override target compilers but **NOT** native tool compilers. Native tools will still use the default GCC unless explicitly overridden with `build_*` variables.
182+
183+Example that may not work as expected (native tools still use GCC):
184+
185+```
186+make CC=clang CXX=clang++
    hebasto commented at 10:10 am on November 19, 2025:

    7f17cf6d6164460086afebbb0f921a7af4475bf9:

    This example uses Makefile variable CC and CXX, but the section title refers to “Environment Variables”. Both approaches work, of course, but the section could be made clearer.

  10. in depends/README.md:183 in 17577646f7 
    178+
179+### Environment Variables (CC, CXX)
180+
181+Setting `CC` and `CXX` environment variables will override target compilers but **NOT** native tool compilers. Native tools will still use the default GCC unless explicitly overridden with `build_*` variables.
182+
183+Example that may not work as expected (native tools still use GCC):
    hebasto commented at 10:16 am on November 19, 2025:

    7f17cf6d6164460086afebbb0f921a7af4475bf9

    This comes across as a bit discouraging and confusing. When I say “I build depends with Clang”, I’m referring to the host-specific packages. I’m not concerned about which compiler is used for the native tools, as long as they build without issues.

    maflcko commented at 10:31 am on November 19, 2025:

    I’m not concerned about which compiler is used for the native tools, as long as they build without issues.

    at least for me the issue was that they did not build at all, because the gcc version was ancient on OpenSuse Leap (or Alma Linux 8, ….)

    willcl-ark commented at 10:36 am on November 19, 2025:
    If using something like a Nix devShell with no gcc available at all, compilation just fails too.
    hebasto commented at 10:39 am on November 19, 2025:

    I’m not concerned about which compiler is used for the native tools, as long as they build without issues.

    at least for me the issue was that they did not build at all, because the gcc version was ancient on OpenSuse Leap (or Alma Linux 8, ….)

    The same issue occurs on NetBSD.

  11. DrahtBot requested review from hebasto on Nov 19, 2025
  12. in depends/README.md:181 in 17577646f7 
    176+make HOST=x86_64-pc-linux-gnu host_CC=clang host_CXX=clang++
177+```
178+
179+### Environment Variables (CC, CXX)
180+
181+Setting `CC` and `CXX` environment variables will override target compilers but **NOT** native tool compilers. Native tools will still use the default GCC unless explicitly overridden with `build_*` variables.
    hebasto commented at 10:27 am on November 19, 2025:

    I’m not entirely convinced by the phrasing “Native tools will still use the default GCC…”. They may instead use whatever the system’s default cc and c++, but I haven’t tested this.

    UPDATE: nm, it is hardcoded in depends/builders/default.mk.

    UPDATE 2: However, the default compiler is Clang on some systems, such as macOS, FreeBSD and OpenBSD.

    willcl-ark commented at 11:01 am on November 19, 2025:
    Have attempted to make different defafults clearer in 34c424ea500
    willcl-ark commented at 11:46 am on November 19, 2025:
    Reolving this based on wording in 75155c073d7.
  13. DrahtBot requested review from hebasto on Nov 19, 2025
  14. willcl-ark force-pushed on Nov 19, 2025
  15. in depends/README.md:18 in b1b559f83f outdated 
    15 
16 Skip the following packages if you don't intend to use the GUI and will build with [`NO_QT=1`](#dependency-options):
17 
18-    apt install bison g++ ninja-build pkgconf python3 xz-utils
19+```
20+apt install bison g++ ninja-build pkgconf python3 xz-utils
    hebasto commented at 11:32 am on November 19, 2025:
    Other native package, not only native_qt, require g++.
    willcl-ark commented at 11:45 am on November 19, 2025:
    I agree, but going to leave that from this PR for now.
  16. in depends/README.md:152 in b1b559f83f 
    147+### Native Tools (build\_\* variables)
148+
149+These control compilers used to compile tools that run natively on the build machine during compilation:
150+
151+- `build_CC`: C compiler for native tools (default: `gcc` on Linux, `clang` on macOS/BSD)
152+- `build_CXX`: C++ compiler for native tools (default: `g++` on Linux, `clang++` on macOS/BSD)
    hebasto commented at 11:33 am on November 19, 2025: 
    0- `build_CC`: C compiler for native tools (default: `gcc` on Linux, `clang` on macOS/FreeBSD/OpenBSD)
1- `build_CXX`: C++ compiler for native tools (default: `g++` on Linux, `clang++` on macOS/FreeBSD/OpenBSD)
    willcl-ark commented at 11:45 am on November 19, 2025:
    Taken in 75155c073d7
  17. in depends/README.md:157 in b1b559f83f 
    152+- `build_CXX`: C++ compiler for native tools (default: `g++` on Linux, `clang++` on macOS/BSD)
153+- `build_AR`, `build_RANLIB`, etc.: Other native build tools
154+
155+This separation allows cross-compilation where build and target architecture differ. These include Cap'n Proto code generators (`native_capnp`), Qt build tools (`native_qt`), and multiprocess utilities (`native_libmultiprocess`).
156+
157+You might want to override native tool compilers when your default build compiler (set in ./depends/builders/*.mk) is not available. For example when using a linux host without gcc/g++.
    hebasto commented at 11:35 am on November 19, 2025: 
    0You might want to override native tool compilers when your default build compiler (set in `./depends/builders/*.mk`) is not available. For example, when using a Linux host without gcc/g++.
    willcl-ark commented at 11:46 am on November 19, 2025:
    Taken in 75155c073d7
  18. in depends/README.md:159 in b1b559f83f 
    154+
155+This separation allows cross-compilation where build and target architecture differ. These include Cap'n Proto code generators (`native_capnp`), Qt build tools (`native_qt`), and multiprocess utilities (`native_libmultiprocess`).
156+
157+You might want to override native tool compilers when your default build compiler (set in ./depends/builders/*.mk) is not available. For example when using a linux host without gcc/g++.
158+
159+Example using Clang for native build tools on linux:
    hebasto commented at 11:36 am on November 19, 2025: 
    0Example using Clang for native build tools on Linux:
    willcl-ark commented at 11:46 am on November 19, 2025:
    Taken in 75155c073d7
  19. hebasto approved
  20. hebasto commented at 11:38 am on November 19, 2025: member
    ACK b1b559f83f629c7d0976c05d07cbc6ec04e84095.
  21. DrahtBot requested review from maflcko on Nov 19, 2025
  22. doc: Detail compiler configuration for depends 
    Previously one had to read the Makefile (and various *.mk configuration
files) to see how to correctly override CC and CXX when building native
depends packages.

Detail this in README.md to make it clearer.
    75155c073d
  23. doc: modernise depends/README.md 
    As we are touching the file use modern codeblock syntax throughout.
    7dd714ae71
  24. willcl-ark force-pushed on Nov 19, 2025
  25. DrahtBot added the label CI failed on Nov 19, 2025
  26. hebasto approved
  27. hebasto commented at 11:46 am on November 19, 2025: member
    re-ACK 7dd714ae71fd18eda82ab4b43d4cecc047b87a2d.
  28. DrahtBot removed the label CI failed on Nov 19, 2025
  29. maflcko commented at 4:20 pm on November 19, 2025: member

    re-ACK 7dd714ae71fd18eda82ab4b43d4cecc047b87a2d 🔔

    Signature:

    0untrusted comment: signature from minisign secret key on empty file; verify via: minisign -Vm "${path_to_any_empty_file}" -P RWTRmVTMeKV5noAMqVlsMugDDCyyTSbA3Re5AkUrhvLVln0tSaFWglOw -x "${path_to_this_whole_four_line_signature_blob}"
1RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
2trusted comment: re-ACK 7dd714ae71fd18eda82ab4b43d4cecc047b87a2d 🔔
3GdGC0CV1oagJPrWcSYTtdbnzJVbACdpgtwV3w0kHQgMB3ZEIhZNTp9Mr5d0DHvusR7eUHFQEauWPXPwpa0cUDw==
  30. maflcko commented at 4:21 pm on November 19, 2025: member
    Could use doc: or build: prefix in title?
  31. willcl-ark renamed this:
    Document compiler configuration for native depends packages
    doc: Document compiler configuration for native depends packages
    on Nov 19, 2025
  32. DrahtBot added the label Docs on Nov 19, 2025
  33. fanquake changes_requested
  34. fanquake commented at 1:26 pm on November 21, 2025: member
    See #33902 (review).


willcl-ark DrahtBot hebasto fanquake maflcko


maflcko

Labels
Docs

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-11-23 21:13 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me