Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add info about factors that affect dependency list #15222

Merged
merged 1 commit into from Feb 21, 2019

Conversation

@merland
Copy link
Contributor

@merland merland commented Jan 21, 2019

To simplify build instructions, the librsvg formula should be moved to the main brew install ... command, in my opinion.
It is not a big problem to install a single extra formula, and it will only be unused for some users.

An additional reason for this change is that I would like to add a comment (in a future PR) about making sure you have the latest version of all deps (in the case of preexisting formulae). That comment can be authored more clearly if this simplification PR is merged.

@merland merland changed the title Simplification of macOS build instructions docs: Simplification of macOS build instructions Jan 21, 2019
@matt-auckland
Copy link

@matt-auckland matt-auckland commented Jan 21, 2019

ACK - looks good to me

Loading

@hebasto
Copy link
Member

@hebasto hebasto commented Jan 21, 2019

This PR reduces clarity of the build instructions, IMO.
Slightly inclined to NACK.

Loading

@merland
Copy link
Contributor Author

@merland merland commented Jan 21, 2019

@hebasto Granted, some information is lost, but I felt it was not crucial to tell the user for what reason librsvg is needed. Do you think it is important? If so, why?

Loading

@fanquake fanquake added the Docs label Jan 21, 2019
@hebasto
Copy link
Member

@hebasto hebasto commented Jan 21, 2019

@merland

Do you think it is important?

Yes.

If so, why?

The task of any docs is to provide a user with clear and relevant info.

Loading

@merland
Copy link
Contributor Author

@merland merland commented Jan 21, 2019

@hebasto Then maybe the instructions should state exactly why every dependency is needed? :)
I think good instructions should tell you all you need to know, but nothing more. There is a link to dependencies.md for the more curious reader.

Loading

@Sjors
Copy link
Member

@Sjors Sjors commented Jan 21, 2019

I'm not a fan of removing this information. Currently https://github.com/bitcoin/bitcoin/blob/master/doc/dependencies.md points back to the OS specific build instructions for more information. macOS instructions are far less detailed than Linux at the moment, and I've often just looked there.

Maybe we can add a section where we briefly mention which dependencies can be avoided or added:

  • librsvg can be avoided if you don't need make deploy
  • miniupnpc can be avoided if you use ./configure --with-miniupnpc=no
  • berkeley-db4 can be avoided if you compile without wallet --disable-wallet, or you just use berkeley-db if you compile with --with-incompatible-bdb
  • protobuf can be avoided with --disable-bip70
  • qt with --disable-gui
  • when qrencode is absent, it won't add QR support, to explicitly complain in such a case: --with-qrencode
  • missing from the instructions: brew install zeromq is needed for --with-zmq

(not sure about the others)

I'm fine with including librsvg in the default instruction, since it's non-trivial to install the GUI without that, and I'm assuming the main target audience for these instructions are users, not developers.

Loading

@merland
Copy link
Contributor Author

@merland merland commented Jan 21, 2019

@Sjors
This makes a lot of sense, thank you! Hope it's ok if I update this PR with your suggestions, adding you as co-author.

Loading

@laanwj
Copy link
Member

@laanwj laanwj commented Jan 22, 2019

This PR reduces clarity of the build instructions, IMO.
Slightly inclined to NACK.

Agree, it slightly reduces the information for no good reason IMO.

Loading

@merland merland force-pushed the patch-2 branch 3 times, most recently from a0d6cd6 to 0c8cf22 Jan 22, 2019
@merland
Copy link
Contributor Author

@merland merland commented Jan 22, 2019

Updated. I added the info provided by @Sjors as a new column in doc/dependencies.md.
What do you think?

Loading

| zlib | [1.2.11](https://zlib.net/) | | | | No |
| Dependency | Version used | Minimum required | CVEs | Shared | [Bundled Qt library](https://doc.qt.io/qt-5/configure-options.html#third-party-libraries) |Notes|
| --- | --- | --- | --- | --- | --- | --- |
| Berkeley DB | [4.8.30](https://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html) | 4.8.x | No | | |Not needed if you compile with `--disable-wallet`, or `--with-incompatible-bdb`|
Copy link
Member

@hebasto hebasto Jan 22, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Building with --with-incompatible-bdb option does not make Berkeley DB dependency unneeded.

Loading

Copy link
Contributor Author

@merland merland Jan 22, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, thanks @hebasto. Did I misunderstand this bullet point, @Sjors ?
What is the best phrasing for this cell?

Loading

Copy link
Member

@hebasto hebasto Jan 22, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@merland

From Ubuntu & Debian Dependency Build Instructions:

Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install BerkeleyDB 5.1 or later. This will break binary wallet compatibility with the distributed executables, which are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, pass --with-incompatible-bdb to configure.

Loading

@DrahtBot
Copy link
Contributor

@DrahtBot DrahtBot commented Jan 22, 2019

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

Conflicts

Reviewers, this pull request conflicts with the following ones:

  • #14066 (gitian-linux: Build binaries for 64-bit POWER by luke-jr)

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.

Loading

@Sjors
Copy link
Member

@Sjors Sjors commented Jan 22, 2019

I don't think adding the extra column to the table in dependencies is the right approach.

Try adding a new section at the bottom instead "Configuration options". There you can explain the effect of each --disable option on which dependencies you need.

Regarding Berkeley DB: it's used by the wallet, so you don't need it at all if you compile with --disable-wallet. In addition, which often confuses people, the wallet is super picky about which BDB version it wants, which is why we still use 4.8. If you don't mind a potentially incompatible wallet file, then you can use newer versions too. That's when you need --with-incompatible-bdb. Again, too subtle to squeeze into a column.

P.S. I didn't know Github integrated so well with the Co-authored-by tag (no need by the way, though it's always nice).

Loading

@laanwj
Copy link
Member

@laanwj laanwj commented Jan 22, 2019

Still tend toward NACK.I think it's better to keep this information where it is and can be easily found.

Loading

@merland
Copy link
Contributor Author

@merland merland commented Jan 22, 2019

Thanks for weighing in, @laanwj. I see your point.
However, having a history as a technical writer (but also developer for many years), I tend to think mainly in terms of readability and simplicity for the majority of the readers.

As @Sjors writes above, the main target audience for these instructions is probably users, not developers. As a result, I think it makes a lot of sense to think along the lines of "convention over configuration" and hide complexities wherever possible. Taking away non-crucial info can greatly improve docs like these, sometimes.

Having said this, I admit that this PR (that started as a small simplification) may be growing over my head. I may not see the full implications of centralizing dependency info for several platforms into one place. Nonetheless, @Sjors' suggestion to extend dependencies.md sure seemed like an elegant and de-duplicating doc refactoring.

Loading

@merland merland changed the title docs: Simplification of macOS build instructions docs: Add info about factors that affect dependency list Jan 23, 2019
@merland
Copy link
Contributor Author

@merland merland commented Jan 23, 2019

Since I got some pushback against the change to simplicification of the build instructions, this PR has now "pivoted" into being about the added dependency info only.

@Sjors, I intentionally omitted the info about --with-incompatible-bdb, since I think it may confuse more than it helps the majority of the readers. Also, it is documented elsewhere.

Loading

Copy link
Member

@Sjors Sjors left a comment

Ok, so now it's strictly adding information, which should not be controversial.

Travis ran into a linter issue (some trailing whitespace, most code editors have an option to prevent that).

Loading

doc/dependencies.md Outdated Show resolved Hide resolved
Loading
doc/dependencies.md Outdated Show resolved Hide resolved
Loading
@Sjors
Copy link
Member

@Sjors Sjors commented Jan 23, 2019

ACK a59529e

Loading

@laanwj
Copy link
Member

@laanwj laanwj commented Jan 23, 2019

utACK a59529ed2c579d015e7867eb23ba353b7a616bec
looks good to me now

Loading

doc/dependencies.md Outdated Show resolved Hide resolved
Loading
doc/dependencies.md Outdated Show resolved Hide resolved
Loading
Co-authored-by: Sjors Provoost <sjors@sprovoost.nl>
@merland
Copy link
Contributor Author

@merland merland commented Jan 23, 2019

Updated after comments from @flack.
If anyone knows if a certain version of librsvg is reqiured, please comment.

Loading

Sjors
Sjors approved these changes Jan 23, 2019
Copy link
Member

@Sjors Sjors left a comment

re-ACK 55e05a8

Loading

@@ -17,6 +17,7 @@ These are the dependencies currently used by Bitcoin Core. You can find instruct
| libevent | [2.1.8-stable](https://github.com/libevent/libevent/releases) | 2.0.22 | No | | |
| libjpeg | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L65) |
| libpng | | | | | [Yes](https://github.com/bitcoin/bitcoin/blob/master/depends/packages/qt.mk#L64) |
| libsrvg | | | | | |
Copy link
Member

@Sjors Sjors Jan 23, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a bunch of CVE's for librsvg, though afaik they all involve a specially crafted SVG file. Since we don't let users open arbitrary images, I doubt they matter. So that also means we don't have to recommend a minimum version.

@laanwj thoughts on what to put in the CVE column in this case (current PR leaves it blank)? Either way I think that can wait for another PR.

Loading

Copy link
Member

@Sjors Sjors Jan 23, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of an abundance of caution, I would just set the minimum to 2.41.2 which fixes the most recent CVE. It's almost a year old, which is ancient for most macOS users :-)

However it seems our macOS Gitian build would then be in violation of that, since Bionic is still at 2.40, and they don't even list this CVE in their tracker.

Loading

Copy link
Member

@laanwj laanwj Jan 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right—if it's linked into bitcoin-qt itself—and not a side dependency used for tooling only—these kind of indirect vulnerabilities could still be a problem. In many cases exploitation involves multiple stages, where one exploit is able to insert something into memory which another bug will stumble over, eventually resulting in RCE. So in that case it should be mentioned.

Loading

@laanwj
Copy link
Member

@laanwj laanwj commented Feb 21, 2019

This is pretty useful info now, thanks!
utACK 55e05a8

Loading

@laanwj laanwj merged commit 55e05a8 into bitcoin:master Feb 21, 2019
0 of 2 checks passed
Loading
laanwj added a commit that referenced this issue Feb 21, 2019
55e05a8 Added some factors that affect the dependency list (Martin Erlandsson)

Pull request description:

  To simplify build instructions, the librsvg formula should be moved to the main `brew install ...` command, in my opinion.
  It is not a big problem to install a single extra formula, and it will only be unused for some users.

  An additional reason for this change is that I would like to add a comment (in a future PR) about making sure you have the latest version of all deps (in the case of preexisting formulae). That comment can be authored more clearly if this simplification PR is merged.

Tree-SHA512: e63284a4e0584f071a920f6b8ac46694de38e7b1df1e0dc2b00262c1487a2f2851fae721e8f4907a4aad0335f287e881974df6f9d05fe9b26f0ba71033dce145
@merland merland deleted the patch-2 branch Apr 15, 2019
deadalnix pushed a commit to Bitcoin-ABC/bitcoin-abc that referenced this issue Apr 2, 2020
Summary: Backport of core [[bitcoin/bitcoin#15222 | PR15222]].

Test Plan: Read the doc.

Reviewers: #bitcoin_abc, deadalnix

Reviewed By: #bitcoin_abc, deadalnix

Differential Revision: https://reviews.bitcoinabc.org/D5637
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

8 participants