doc: add LLVM instruction for macOS

Sjors commented at 2:35 pm on April 22, 2024: member

#29208 bumped clang to 14, which users of old macOS versions need to install manually. This PR adds instructions.

Xcode 14.3.1 ships clang 14.0.3 (14.0.0 is broken, see #29918): https://en.wikipedia.org/wiki/Xcode#Xcode_11.0_-_14.x_(since_SwiftUI_framework)

The system requirements for that is macOS Ventura 13.0 or later: https://developer.apple.com/documentation/xcode-release-notes/xcode-14_3_1-release-notes#

Homebrew itself officially supports macOS 12 or later, but may still work on macOS 11: https://docs.brew.sh/Installation

Fwiw macOS 11 Big Sur last got an update in September 2023, so Apple has not entirely written it off: https://en.wikipedia.org/wiki/MacOS_Big_Sur

DrahtBot commented at 2:35 pm on April 22, 2024: contributor

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

Code Coverage

For detailed information about the code coverage, see the test coverage report.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	maflcko, TheCharlatan
Concept ACK	ismaelsadeeq

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

DrahtBot added the label Docs on Apr 22, 2024

Sjors commented at 2:43 pm on April 22, 2024: member

I tested these instructions by installing llvm 14.0.6 on macOS 14.4.1.

I don’t have a macOS 11 or 12 machine, so have not tested those. So there may be other issues, which we’ll just have to find out if someone runs into them.

in doc/build-osx.md:57 in c8cf11f964 outdated

50@@ -51,6 +51,18 @@ To install, run the following from your terminal:
51 brew install automake libtool boost pkg-config libevent
52 ```
53 
54+For macOS 11 (Big Sur) and 12 (Monterey) you need to install a more recent version of llvm.
55+
56+``` bash
57+brew install llvm@14

maflcko commented at 2:53 pm on April 22, 2024:

I’d say to use the latest llvm. However, I presume you wanted to avoid a too recent llvm breaking on the old operating systems? Seems fine either way.

Sjors commented at 2:56 pm on April 22, 2024:

a too recent llvm breaking on the old operating systems

Exactly. Either llvm itself or Homebrew’s build scripts might not work for some reason, so this seems safer.

fanquake commented at 5:54 am on April 23, 2024:

Why would LLVM not work? We use the near latest release of LLVM to build the macOS release binaries. There’s no point making this LLVM 14 just to “bump it” almost immediately. We should just point to the latest version unless there’s an actual reason not to.

maflcko commented at 6:54 am on April 23, 2024:

I guess someone will need to test either way. Once they have tested with brew install llvm vs brew install llvm@_version_, this can be bumped to the maximum working _version_ (or none at all).

Sjors commented at 6:55 am on April 23, 2024:

Why would LLVM not work?

I have no way to test it. Since Homebrew itself does not support macOS 11 it’s reasonable to expect that their newer formulas break, while the old ones might be fine.

This instruction is specifically for old versions of macOS. For newer versions we still have them use the latest thing.

I could change the instruction to say they can try “llvm@14 or higher” if the default llvm fails (but I’d rather give first time installers a clear recommendation).

TheCharlatan commented at 9:51 am on April 24, 2024:

I tested this without specifying a llvm version on macos 12.7.4 monterey. It did resolve the compilation errors. I would prefer this without a version, since it is yet another thing to keep track of in our versioning zoo, and I don’t think it is preferable for developers to be instructed to use an older compiler. Also not sure if the guide should cover an OS version that is no longer supported by its package manager. If something eventually breaks for a developer, this could be revisited.

Sjors commented at 7:24 pm on April 24, 2024:

After a full day my Big Sur 11.7 virtual box also managed to complete brew install llvm without needing a version :-) Will update the PR tomorrow.

maflcko approved

maflcko commented at 2:53 pm on April 22, 2024: member

lgtm

TheCharlatan commented at 2:56 pm on April 22, 2024: contributor

Will test shortly.

maflcko added the label Needs backport (27.x) on Apr 22, 2024

ismaelsadeeq commented at 3:03 pm on April 22, 2024: member

Concept ACK, I ran into this issue sometime ago

in doc/build-osx.md:54 in c8cf11f964 outdated

50@@ -51,6 +51,18 @@ To install, run the following from your terminal:
51 brew install automake libtool boost pkg-config libevent
52 ```
53 
54+For macOS 11 (Big Sur) and 12 (Monterey) you need to install a more recent version of llvm.

maflcko commented at 3:59 pm on April 22, 2024:

nit: According to Wikipedia, Big Sur is “Unsupported as of September 26, 2023.” (https://en.wikipedia.org/wiki/MacOS_Big_Sur)

Maybe just say macOS Monterey 12 (and earlier), or drop Big Sur?

Sjors commented at 4:45 pm on April 22, 2024:

That’s not that long ago though, and we have OSX_MIN_VERSION=11.0 for now.

“earlier” only means 11, so naming it explicitly seems more clear

maflcko commented at 5:42 am on April 23, 2024:

Sure, makes sense. It is just a nit, and I guess the text will be removed after a bump of OSX_MIN_VERSION anyway.

fanquake commented at 5:53 am on April 23, 2024:

That’s not that long ago though, and we have OSX_MIN_VERSION=11.0 for now.

Just because we build release binaries that support that operating system, does not mean you need to be able to compile on that system (regardless of using the system compiler).

Sjors commented at 6:51 am on April 23, 2024:

That’s also true, though so far I haven’t seen evidence that compilation is impossible.

Homebrews main motivation for dropping macOS 11 seems to be support requests. From their install script:

This installation may not succeed. After installation, you will encounter build failures with some formulae. Please create pull requests instead of asking for help on Homebrew's GitHub, Twitter or any other official channels. You are responsible for resolving any issues you experience while you are running this

So far I haven’t seen a report of anyone even trying to compile on that version recently, let alone feel overwhelmed by their support requests :-)

DrahtBot added the label CI failed on Apr 22, 2024

DrahtBot removed the label CI failed on Apr 23, 2024

Sjors commented at 6:51 pm on April 23, 2024: member

I spun up a VM with macOS 11 Big Sur and installed the command line tools (I had to download them from Apple, because xcode-select --install got stuck, but that might be a VirtualBox issue).

I then installed Homebrew and did brew install llvm, which should install llvm 18. The openssl@3 install failed due to one broken test (update: worked fine on the second try). openssl@3 is needed by a lot of other things, like brew install ccache (which also needs llvm@17 at the moment).

I’ll continue to test, but the VM is excruciatingly slow…

Will update to drop the @14 if that works.

(feel free to mark as draft, I can’t find the button)

fanquake marked this as a draft on Apr 24, 2024

Sjors commented at 9:52 am on April 25, 2024: member

I was able to build bitcoind (didn’t try QT) with llvm@17, but not with the current llvm 18.1.4. See log: https://gist.github.com/Sjors/194eb5d67e2e1132df7ff86f103ba16b

It’s probably fine to drop @14 anyway, and maybe suggest trying lower versions if building fails. But it would be nice if there’s a simple fix for this.

Regarding QT, interestingly Homebrew seems to handle that differently on old macOS versions than on new ones:

qt@5: A full installation of Xcode.app is required to compile this software. Installing just the Command Line Tools is not sufficient.

I didn’t need to install Xcode on macOS 13.6.6. People can either do that or use depends (update: I tested the latter, and ran into a similar error for the default llvm, while it worked fine for llvm@17).

Sjors force-pushed on Apr 29, 2024

Sjors marked this as ready for review on Apr 29, 2024

Sjors commented at 8:26 am on April 29, 2024: member

I dropped the @14 from the default instruction, but added a hint to try @17 if that fails. That worked when I tested and I don’t expect Homebrew formulas for older versions to change much moving forward, nor llvm 17 itself.

Sjors force-pushed on Apr 29, 2024

DrahtBot added the label CI failed on Apr 29, 2024

DrahtBot commented at 8:27 am on April 29, 2024: contributor

🚧 At least one of the CI tasks failed. Make sure to run all tests locally, according to the documentation.

Possibly this is due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

Leave a comment here, if you need help tracking down a confusing failure.

Debug: https://github.com/bitcoin/bitcoin/runs/24365135335

doc: add LLVM instruction for macOS < 13 22574046c9

Sjors force-pushed on Apr 29, 2024

maflcko commented at 8:34 am on April 29, 2024: member

utACK 22574046c90c0662f3aa9b1baea074aff54f92a9

DrahtBot requested review from ismaelsadeeq on Apr 29, 2024

DrahtBot removed the label CI failed on Apr 29, 2024

TheCharlatan approved

TheCharlatan commented at 1:26 pm on April 30, 2024: contributor

ACK 22574046c90c0662f3aa9b1baea074aff54f92a9

fanquake merged this on May 2, 2024

fanquake closed this on May 2, 2024

fanquake referenced this in commit 475aac41fb on May 2, 2024

fanquake removed the label Needs backport (27.x) on May 2, 2024

fanquake commented at 7:30 am on May 2, 2024: member

Backported in #29888.

doc: add LLVM instruction for macOS < 13 #29934

Code Coverage

Reviews