doc: Document compiler configuration for native depends packages #33902

willcl-ark · 2025-11-18T15:23:18Z

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.

DrahtBot · 2025-11-18T15:23:25Z

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.

hebasto

Concept ACK. Thanks!

willcl-ark · 2025-11-18T15:27:42Z

Forgot to say, very happy to drop the second commit if wanted.

hebasto · 2025-11-18T15:30:20Z

depends/README.md

+To ensure both native and target use Clang:
+
+```
+make build_CC=clang build_CXX=clang++ host_CC=clang host_CXX=clang++


How is this better than make build_CC=clang build_CXX=clang++ CC=clang CXX=clang++?

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?

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

make CC=clang CXX=clang++

Only in rare cases (#33902 (comment), #33902 (comment), #33902 (comment)) does this need to be extended to:

make CC=clang CXX=clang++ build_CC=clang build_CXX=clang++

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.

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:

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

Using CC=clang CXX=clang++:

build_CC=clang build_CXX=clang++ CC=clang CXX=clang++ -C depends/ -j12 build_TAR=gtar gmake: Entering directory '/bitcoin/depends' Extracting native_capnp... /bitcoin/depends/sources/capnproto-cxx-1.2.0.tar.gz: OK Preprocessing native_capnp... Configuring native_capnp... -- The CXX compiler identification is Clang 21.1.4 <snip> done Configuring boost... -- The CXX compiler identification is Clang 21.1.4 -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done -- Check for working CXX compiler: /usr/sbin/clang++ - skipped -- Detecting CXX compile features -- Detecting CXX compile features - done -- Boost: using system layout: include, bin, lib/, lib//cmake

maflcko

lgtm

review ACK 1757764 🌴

Show signature

Signature:

untrusted 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}"
RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
trusted comment: review ACK 17577646f77e20783ffdd9f322f85e96da2265 🌴
b6tuB1ff+N8xGzUilBsW1CSxIOpk4gK7SE473C8JMS+vg4aU5H4YbP04c0HL3NEDxTZkxKFJBRcJ9RVAQ9t7DQ==

hebasto · 2025-11-19T10:10:51Z

depends/README.md

+Example that may not work as expected (native tools still use GCC):
+
+```
+make CC=clang CXX=clang++


7f17cf6:

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.

hebasto · 2025-11-19T10:16:49Z

depends/README.md

+
+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.
+
+Example that may not work as expected (native tools still use GCC):


7f17cf6

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.

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, ....)

If using something like a Nix devShell with no gcc available at all, compilation just fails too.

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.

depends/README.md

hebasto · 2025-11-19T11:32:10Z

depends/README.md


-    apt install bison g++ ninja-build pkgconf python3 xz-utils
+```
+apt install bison g++ ninja-build pkgconf python3 xz-utils


Other native package, not only native_qt, require g++.

I agree, but going to leave that from this PR for now.

hebasto

ACK b1b559f.

depends/README.md

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.

As we are touching the file use modern codeblock syntax throughout.

hebasto

re-ACK 7dd714a.

maflcko · 2025-11-19T16:20:31Z

re-ACK 7dd714a 🔔

Show signature

Signature:

untrusted 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}"
RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
trusted comment: re-ACK 7dd714ae71fd18eda82ab4b43d4cecc047b87a2d 🔔
GdGC0CV1oagJPrWcSYTtdbnzJVbACdpgtwV3w0kHQgMB3ZEIhZNTp9Mr5d0DHvusR7eUHFQEauWPXPwpa0cUDw==

maflcko · 2025-11-19T16:21:06Z

Could use doc: or build: prefix in title?

fanquake

See #33902 (comment).

hebasto reviewed Nov 18, 2025

View reviewed changes

maflcko approved these changes Nov 18, 2025

View reviewed changes

DrahtBot requested a review from hebasto November 18, 2025 15:53

hebasto reviewed Nov 19, 2025

View reviewed changes

DrahtBot requested a review from hebasto November 19, 2025 10:17

hebasto reviewed Nov 19, 2025

View reviewed changes

depends/README.md Outdated Show resolved Hide resolved

DrahtBot requested a review from hebasto November 19, 2025 10:27

willcl-ark force-pushed the doc-depends-cc branch from 1757764 to b1b559f Compare November 19, 2025 11:00

hebasto reviewed Nov 19, 2025

View reviewed changes

hebasto approved these changes Nov 19, 2025

View reviewed changes

depends/README.md Outdated Show resolved Hide resolved

depends/README.md Outdated Show resolved Hide resolved

depends/README.md Outdated Show resolved Hide resolved

DrahtBot requested a review from maflcko November 19, 2025 11:38

willcl-ark added 2 commits November 19, 2025 11:45

doc: Detail compiler configuration for depends

75155c0

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.

doc: modernise depends/README.md

7dd714a

As we are touching the file use modern codeblock syntax throughout.

willcl-ark force-pushed the doc-depends-cc branch from b1b559f to 7dd714a Compare November 19, 2025 11:45

DrahtBot added the CI failed label Nov 19, 2025

hebasto approved these changes Nov 19, 2025

View reviewed changes

DrahtBot removed the CI failed label Nov 19, 2025

willcl-ark changed the title ~~Document compiler configuration for native depends packages~~ doc: Document compiler configuration for native depends packages Nov 19, 2025

DrahtBot added the Docs label Nov 19, 2025

fanquake requested changes Nov 21, 2025

View reviewed changes

DrahtBot mentioned this pull request Nov 22, 2025

depends: Switch from multilib to platform-specific toolchains #32162

Open


		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.

		Example that may not work as expected (native tools still use GCC):

doc: Document compiler configuration for native depends packages #33902

Are you sure you want to change the base?

doc: Document compiler configuration for native depends packages #33902

Conversation

willcl-ark commented Nov 18, 2025

Uh oh!

DrahtBot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage & Benchmarks

Reviews

Conflicts

Uh oh!

hebasto left a comment

Choose a reason for hiding this comment

Uh oh!

willcl-ark commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hebasto Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maflcko left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hebasto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hebasto left a comment

Choose a reason for hiding this comment

Uh oh!

maflcko commented Nov 19, 2025

Uh oh!

maflcko commented Nov 19, 2025

Uh oh!

fanquake left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

DrahtBot commented Nov 18, 2025 •

edited

Loading

hebasto Nov 19, 2025 •

edited

Loading