1  Contents
  2  ========
  3  This directory contains tools for developers working on this repository.
  4  
  5  deterministic-fuzz-coverage
  6  ===========================
  7  
  8  A tool to check for non-determinism in fuzz coverage. To get the help, run:
  9  
 10  ```
 11  cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- --help
 12  ```
 13  
 14  To execute the tool, compilation has to be done with the build options:
 15  
 16  ```
 17  -DCMAKE_C_COMPILER='clang' -DCMAKE_CXX_COMPILER='clang++' -DBUILD_FOR_FUZZING=ON -DCMAKE_CXX_FLAGS='-fprofile-instr-generate -fcoverage-mapping'
 18  ```
 19  
 20  Both llvm-profdata and llvm-cov must be installed. Also, the qa-assets
 21  repository must have been cloned. Finally, a fuzz target has to be picked
 22  before running the tool:
 23  
 24  ```
 25  cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- $PWD/build_dir $PWD/qa-assets/fuzz_corpora fuzz_target_name
 26  ```
 27  
 28  deterministic-unittest-coverage
 29  ===========================
 30  
 31  A tool to check for non-determinism in unit-test coverage. To get the help, run:
 32  
 33  ```
 34  cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- --help
 35  ```
 36  
 37  To execute the tool, compilation has to be done with the build options:
 38  
 39  ```
 40  -DCMAKE_C_COMPILER='clang' -DCMAKE_CXX_COMPILER='clang++' -DCMAKE_CXX_FLAGS='-fprofile-instr-generate -fcoverage-mapping'
 41  ```
 42  
 43  Both llvm-profdata and llvm-cov must be installed.
 44  
 45  ```
 46  cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- $PWD/build_dir <boost unittest filter>
 47  ```
 48  
 49  clang-format-diff.py
 50  ===================
 51  
 52  A script to format unified git diffs according to [.clang-format](../../src/.clang-format).
 53  
 54  Requires `clang-format`, installed e.g. via `brew install clang-format` on macOS,
 55  or `sudo apt install clang-format` on Debian/Ubuntu.
 56  
 57  For instance, to format the last commit with 0 lines of context,
 58  the script should be called from the git root folder as follows.
 59  
 60  ```
 61  git diff -U0 HEAD~1.. | ./contrib/devtools/clang-format-diff.py -p1 -i -v
 62  ```
 63  
 64  gen-manpages.py
 65  ===============
 66  
 67  A small script to automatically create manpages in ../../doc/man by running the release binaries with the -help option.
 68  This requires help2man which can be found at: https://www.gnu.org/software/help2man/
 69  
 70  This script assumes a build directory named `build` as suggested by example build documentation.
 71  To use it with a different build directory, set `BUILDDIR`.
 72  For example:
 73  
 74  ```bash
 75  BUILDDIR=$PWD/my-build-dir contrib/devtools/gen-manpages.py
 76  ```
 77  
 78  headerssync-params.py
 79  =====================
 80  
 81  A script to generate optimal parameters for the headerssync module (stored in src/kernel/chainparams.cpp). It takes no command-line
 82  options, as all its configuration is set at the top of the file. It runs many times faster inside PyPy. Invocation:
 83  
 84  ```bash
 85  pypy3 contrib/devtools/headerssync-params.py
 86  ```
 87  
 88  gen-bitcoin-conf.sh
 89  ===================
 90  
 91  Generates a bitcoin.conf file in `share/examples/` by parsing the output from `bitcoind --help`. This script is run during the
 92  release process to include a bitcoin.conf with the release binaries and can also be run by users to generate a file locally.
 93  When generating a file as part of the release process, make sure to commit the changes after running the script.
 94  
 95  This script assumes a build directory named `build` as suggested by example build documentation.
 96  To use it with a different build directory, set `BUILDDIR`.
 97  For example:
 98  
 99  ```bash
100  BUILDDIR=$PWD/my-build-dir contrib/devtools/gen-bitcoin-conf.sh
101  ```
102  
103  circular-dependencies.py
104  ========================
105  
106  Run this script from the root of the source tree (`src/`) to find circular dependencies in the source code.
107  This looks only at which files include other files, treating the `.cpp` and `.h` file as one unit.
108  
109  Example usage:
110  
111      cd .../src
112      ../contrib/devtools/circular-dependencies.py {*,*/*,*/*/*}.{h,cpp}