Add useful test compilation documentation #23896

pull blueredpen wants to merge 3 commits into bitcoin:master from blueredpen:patch-1 changing 1 files +36 −1
  1. blueredpen commented at 4:51 PM on December 29, 2021: none

    I found this great resource which shed more light on how to compile the tests: https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests

    <!-- *** Please remove the following help text before submitting: *** Pull requests without a rationale and clear improvement may be closed immediately. GUI-related pull requests should be opened against https://github.com/bitcoin-core/gui first. See CONTRIBUTING.md -->

    <!-- Please provide clear motivation for your patch and explain how it improves Bitcoin Core user experience or Bitcoin Core developer experience significantly: * Any test improvements or new tests that improve coverage are always welcome. * All other changes should have accompanying unit tests (see `src/test/`) or functional tests (see `test/`). Contributors should note which tests cover modified code. If no tests exist for a region of modified code, new tests should accompany the change. * Bug fixes are most welcome when they come with steps to reproduce or an explanation of the potential issue as well as reasoning for the way the bug was fixed. * Features are welcome, but might be rejected due to design or scope issues. If a feature is based on a lot of dependencies, contributors should first consider building the system outside of Bitcoin Core, if possible. * Refactoring changes are only accepted if they are required for a feature or bug fix or otherwise improve developer experience significantly. For example, most "code style" refactoring changes require a thorough explanation why they are useful, what downsides they have and why they *significantly* improve developer experience or avoid serious programming bugs. Note that code style is often a subjective matter. Unless they are explicitly mentioned to be preferred in the [developer notes](/doc/developer-notes.md), stylistic code changes are usually rejected. -->

    <!-- Bitcoin Core has a thorough review process and even the most trivial change needs to pass a lot of eyes and requires non-zero or even substantial time effort to review. There is a huge lack of active reviewers on the project, so patches often sit for a long time. -->

  2. Add useful test compilation documentation
    I found this great resource which shed more light on how to compile the tests:
https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests
    3a39b9518e
  3. DrahtBot added the label Docs on Dec 29, 2021
  4. DrahtBot added the label Tests on Dec 29, 2021
  5. brunoerg commented at 7:03 PM on December 29, 2021: member

    Concept NACK. The documentation should be enough to run the tests, I think if a website has useful tips about it, then, it would be better to include the tips in the docs, instead of a reference to an external website.

  6. blueredpen commented at 9:14 PM on December 29, 2021: none

    @brunoerg I disagree. The website makes it very clear the step-by-step instructions one needs to follow in order to build Bitcoin from source and then run the unit tests. It contains a lot more detail than the docs in the README.md file and is much easier to follow, in my opinion.

    Could we keep the website as a link at the bottom of the page as-is? @jonatack what do you think about this change to the README.md?

  7. hebasto commented at 9:21 PM on December 29, 2021: member

    Documentation in this repo should be concise and include only required steps.

  8. blueredpen commented at 9:23 PM on December 29, 2021: none

    That website is super concise and easy-to-follow. I'm not able to compile the tests by following the README.md because it leaves-out key details (for ex. building BerkeleyDB).

  9. brunoerg commented at 10:15 PM on December 29, 2021: member

    @brunoerg I disagree. The website makes it very clear the step-by-step instructions one needs to follow in order to build Bitcoin from source and then run the unit tests. It contains a lot more detail than the docs in the README.md file and is much easier to follow, in my opinion.

    Could we keep the website as a link at the bottom of the page as-is?

    @jonatack what do you think about this change to the README.md? @jonatack's articles are really good. However, if you're not able to compile the tests successfully yet sounds like the doc could be not enough for it. So, if the article covers a required step or information that is not covered by the doc, we could add it to the doc instead of putting a reference to the article.

  10. blueredpen commented at 10:53 PM on December 29, 2021: none

    I think the README.md file needs to be replaced by Jon's article. README.md contains quite a number of very specific points, like adding tests and debugging segmentation faults, but Jon's article is much easier to understand. I can go back and revise README.md to contain Jon's article and supplement the final version with the specifics outlined currently in README.md.

  11. Add more details cb15cf8ba6
  12. More changes and details b14b884a7b
  13. fanquake commented at 11:55 PM on December 29, 2021: member

    Thanks, but we're not going to make these changes. The test README is not the place for instructions on installing dependencies (some of which are incorrect. i.e Protobuf is not required), or compiling Bitcoin Core. The compilation documentation is in the build-* docs.

    If you're running into an issue compiling, after following our build documentation, feel free to open an issue with steps to reproduce.

  14. fanquake closed this on Dec 29, 2021
  15. blueredpen commented at 12:01 AM on December 30, 2021: none

    @fanquake I'm unable to run the unit tests by follow the doc as it stands. For example, it makes no mention of running autogen.sh or the directory I should be running the commands in.

    That article that I'm referencing gave me everything I need to run the tests successfully. Could we improve the current README.md documents to reflect the necessary details in order to be able to run the tests?

    Even adding a small blurb at the end of the README.md, like in the first commit of this PR, would be sufficient.

  16. fanquake commented at 12:07 AM on December 30, 2021: member

    For example, it makes no mention of running autogen.sh

    I'd suggest reading the relevant build-*.md documentation for whichever platform you are using, as how to compile the code is already well documented, and in most cases, instructions on how to run the (unit) tests are mentioned. We aren't going to add duplicate dependency installation / compilation instructions to this README.

  17. blueredpen commented at 1:04 AM on December 30, 2021: none

    Will check it out, thanks.

  18. ghost commented at 1:32 AM on December 30, 2021: none

    I'm unable to run the unit tests by follow the doc as it stands. For example, it makes no mention of running autogen.sh or the directory I should be running the commands in.

    That article that I'm referencing gave me everything I need to run the tests successfully.

    I agree documentation in this repository can be improved and I have used https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests for help lot of times.

  19. jonatack commented at 1:14 PM on January 10, 2022: member

    some of which are incorrect. i.e Protobuf is not required @fanquake thanks for the feedback! Indeed, the dependencies section of https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests was in need of an update. Done in https://github.com/jonatack/jonatack.github.io/commit/057c3aa9bb673f334c292441b83631c3b014664b. Future suggestions/corrections welcome.

  20. in src/test/README.md:137 in b14b884a7b 
     130 | @@ -100,3 +131,7 @@ gdb src/test/test_bitcoin core
 131 |  
 132 |  (gbd) bt  # produce a backtrace for where a segfault occurred
 133 |  ```
 134 | +
 135 | +#### Additional guide
 136 | +Below is a great guide on how to run the tests if you're not able to compile the tests successfully yet:
 137 | +https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests
    hebasto commented at 1:23 PM on January 10, 2022:

    NACK on adding links to personal sites, blogs etc.

    Although, https://jonatack.github.io/articles/how-to-compile-bitcoin-core-and-run-the-tests indeed is a great piece to read for newbies.

    jonatack commented at 1:35 PM on January 10, 2022:

    Yes. And it's easier to maintain/update as an external resource.

  21. MarcoFalke commented at 1:59 PM on January 10, 2022: member

    Agree with everyone else, if there is something required missing from our docs, it should be added here. The docs here should be both sufficient and self-contained.

  22. DrahtBot locked this on Jan 10, 2023
Contributors
blueredpenbrunoerghebastofanquakeghostjonatackMarcoFalke
Labels
DocsTests
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: 2026-04-13 18:14 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me