doc: revamp macOS build doc

jarolrod commented at 9:26 pm on March 2, 2021: member

This PR makes the macOS build-docs more informative and adds in the following information:

Proper descriptions and delineation of required/optional dependencies
walk-through of optional dependencies
configuration walk-through
various other tidbits of information

This is a part of the efforts done in #20601 and #20610 to update the docs and introduce some consistency between them.

This update does not add instructions for arm-based M1 Macbooks as I do not have one to test with. It would be nice to have someone follow up with an update containing instructions for arm-based Macs.

Before/Master: render After/PR: render

hebasto commented at 9:29 pm on March 2, 2021: member

Why dropped “Usually, macOS installation already has a suitable SQLite installation.” ?

jarolrod commented at 9:32 pm on March 2, 2021: member

Why dropped “Usually, macOS installation already has a suitable SQLite installation.” ?

Since it was introduced in 10.14, which is our minimum supported macOS, I guess you’re right in that it can stay

in doc/build-osx.md:118 in 6d08ec2e71 outdated

137+
138+`berkeley-db4` is required to enable support for legacy wallets.
139+Skip if you don't intend to use legacy wallets.
140+
141+``` bash
142+brew install berkeley-db4

hebasto commented at 9:35 pm on March 2, 2021:

Package name berkeley-db4 seems old. Maybe use (here and in other places) berkeley-db@4?

jarolrod commented at 9:36 pm on March 2, 2021:

You’re right: https://formulae.brew.sh/formula/berkeley-db@4

Using the Formerly Known as name might not be so safe

in doc/build-osx.md:19 in 6d08ec2e71 outdated

15+-----------------------------------------------------------|------------|----------------------
16+[Xcode Tools](https://developer.apple.com/xcode/features/) | Build      | macOS build tools
17+[automake](https://formulae.brew.sh/formula/automake)      | Build      | Generate makefile
18+[libtool](https://formulae.brew.sh/formula/libtool)        | Build      | Shared library support
19+[pkg-config](https://formulae.brew.sh/formula/pkg-config)  | Build      | Configure compiler and linker flags
20+[git](https://formulae.brew.sh/formula/git)                | Clone      | Version control system

hebasto commented at 9:40 pm on March 2, 2021:

Technically, git is not a build dependency :)

DrahtBot added the label Docs on Mar 2, 2021

jarolrod force-pushed on Mar 3, 2021

jarolrod commented at 2:01 am on March 3, 2021: member

updated from 6d08ec2 -> 4780ea7, addressed @hebasto suggestions

changes:

use new ‘safe’ name for berekeley-db
git is not exactly a build dependency, so it has been removed
Various little text-fix ups found upon another read through

in doc/build-osx.md:15 in 4780ea7cc7 outdated

11+
12+The following dependencies are **required**:
13+
14+Library                                                    | Purpose    | Description
15+-----------------------------------------------------------|------------|----------------------
16+[Xcode Tools](https://developer.apple.com/xcode/features/) | Build      | macOS build tools

fanquake commented at 3:04 am on March 3, 2021:

What are the Xcode Tools? Having this here is going to make users think they need to install Xcode. Which unless it’s changed recently, is not required.

jarolrod commented at 9:14 pm on March 3, 2021:

removed in c180c911b88b2bd2baf2c9c2b24e276787ffb69b

in doc/build-osx.md:66 in 4780ea7cc7 outdated

67+``` bash
68 xcode-select --install
69 ```
70 
71-When the popup appears, click `Install`.
72+Upon running the command, you should see a a popup appear.

fanquake commented at 3:06 am on March 3, 2021:

a a

jarolrod commented at 9:14 pm on March 3, 2021:

fixed

in doc/build-osx.md:69 in 4780ea7cc7 outdated

76+### 2. Homebrew Package Manager
77 
78-## Dependencies
79-```shell
80-brew install automake libtool boost miniupnpc libnatpmp pkg-config python qt libevent qrencode
81+Homebrew is a package manager for macOS that allows one to install packages from the command line easily.

fanquake commented at 3:15 am on March 3, 2021:

I preferred the one liner with a link to https://docs.brew.sh/Installation. I don’t think we need a paragraph explaining brew, or listing the actual install invocation.

jarolrod commented at 9:14 pm on March 3, 2021:

removed the install invocation in c180c911b88b2bd2baf2c9c2b24e276787ffb69b

I want this paragraph to just be a quick explanation that the commands use homebrew but they are free to use whatever package manager they use and adapt the commands. I added the following line to make this clearer:

0Otherwise, you can adapt the commands to your package manager of choice.

fanquake commented at 3:46 am on March 3, 2021: member

It seems sub optimal that we are basically just copy pasting blocks of dependencies throughout all the build docs. Isn’t the point of dependencies.md to list the dependencies, what they are, and when they are required?

I think the same can be said for all of the “configuration” blocks. These seem to get repeated (across lots of docs) in varying combinations and levels of verbosity, and I’d think a lot of the time they might just be downright confusing to a first time builder.

This also includes the parts where configure output is basically pasted verbatim into documentation. i.e upnp or libnatpmp options. Can’t we just tell users to look at configure --help? This means they’ll always be getting accurate information; rather than something pasted into a build doc that now may have drifted from what actually happens.

jarolrod commented at 4:03 am on March 3, 2021: member

It seems sub optimal that we are basically just copy pasting blocks of dependencies throughout all the build docs. Isn’t the point of dependencies.md to list the dependencies, what they are, and when they are required?

Not exactly copy-pasting. Naming and links are different. I don’t think it would be ‘better’ to point to dependencies.md and have the user figure out how that dependency correlates to their system.

I think the same can be said for all of the “configuration” blocks. These seem to get repeated (across lots of docs) in varying combinations and levels of verbosity, and I’d think a lot of the time they might just be downright confusing to a first time builder.

Just trying to improve that situation across the build docs so that it’s informative in the right ways to get someone up and running with a couple of examples that are relevant.

This also includes the parts where configure output is basically pasted verbatim into documentation. i.e upnp or libnatpmp options. Can’t we just tell users to look at configure --help? This means they’ll always be getting accurate information; rather than something pasted into a build doc that now may have drifted from what actually happens.

Well I was thinking that the build docs can be a one-stop place on how to get up and running. I think it would be way more confusing for a first time builder to have to hop through 3 different files and try to piece together the right information.

The information doesn’t need to drift away from what’s happening if it’s maintained.

DrahtBot commented at 8:45 am on March 3, 2021: member

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

Conflicts

No conflicts as of last run.

DrahtBot added the label Needs rebase on Mar 3, 2021

doc: revamp macOS build doc

This pr makes the macOS build docs more informative and adds in the following information:
- Proper descriptions and delineation of required/optional dependencies
- walk-through of optional dependencies
- configuration walk-through
- various other tid-bits of information

c180c911b8

jarolrod force-pushed on Mar 3, 2021

jarolrod commented at 9:22 pm on March 3, 2021: member

Updated from 4780ea7 -> c180c91, rebased to resolve conflict with #21346 and addressed some of @fanquake suggestions.

changes:

updated references of qt to qt@5
Removed confusing Xcode Tools dependency
Removed specific configuration to port mapping and zmq in favor of pointing the user to check out ./configure -help

Justification: I guess, following from fanquake’s comment , this may need some more justification. I simply think that this adds value and the format can help a first-time builder get up and running. I certainly don’t want to waste reviewer time or contribute something that would be an annoyance to maintain. If this PR falls into that, then it’s ok if its closed.

DrahtBot removed the label Needs rebase on Mar 3, 2021

DrahtBot commented at 4:49 pm on March 15, 2021: member

🕵️ @harding has been requested to review this pull request as specified in the REVIEWERS file.

fanquake approved

fanquake commented at 3:35 am on March 18, 2021: member

ACK c180c911b88b2bd2baf2c9c2b24e276787ffb69b - I still think these are getting too verbose and we’re duplicating information all over the place; dependencies, configure options, combinations of options etc. However if people are happy to maintain them, I guess it’s fine for now, and this revamping has already happened for some of the other build READMEs.

fanquake merged this on Mar 18, 2021

fanquake closed this on Mar 18, 2021

sidhujag referenced this in commit 8318ad1ca6 on Mar 18, 2021

jarolrod deleted the branch on Mar 25, 2021

DrahtBot locked this on Aug 16, 2022

doc: revamp macOS build doc #21343

Conflicts