contrib/devtools/README.md

   1 Contents
   2 ========
   3 This directory contains tools for developers working on this repository.
   4
   5 check-doc.py
   6 ============
   7
   8 Check if all command line args are documented. The return value indicates the
   9 number of undocumented args.
  10
  11 clang-format-diff.py
  12 ===================
  13
  14 A script to format unified git diffs according to [.clang-format](../../src/.clang-format).
  15
  16 For instance, to format the last commit with 0 lines of context,
  17 the script should be called from the git root folder as follows.
  18
  19 ```
  20 git diff -U0 HEAD~1.. | ./contrib/devtools/clang-format-diff.py -p1 -i -v
  21 ```
  22
  23 copyright\_header.py
  24 ====================
  25
  26 Provides utilities for managing copyright headers of `The Bitcoin Core
  27 developers` in repository source files. It has three subcommands:
  28
  29 ```
  30 $ ./copyright_header.py report <base_directory> [verbose]
  31 $ ./copyright_header.py update <base_directory>
  32 $ ./copyright_header.py insert <file>
  33 ```
  34 Running these subcommands without arguments displays a usage string.
  35
  36 copyright\_header.py report \<base\_directory\> [verbose]
  37 ---------------------------------------------------------
  38
  39 Produces a report of all copyright header notices found inside the source files
  40 of a repository. Useful to quickly visualize the state of the headers.
  41 Specifying `verbose` will list the full filenames of files of each category.
  42
  43 copyright\_header.py update \<base\_directory\> [verbose]
  44 ---------------------------------------------------------
  45 Updates all the copyright headers of `The Bitcoin Core developers` which were
  46 changed in a year more recent than is listed. For example:
  47 ```
  48 // Copyright (c) <firstYear>-<lastYear> The Bitcoin Core developers
  49 ```
  50 will be updated to:
  51 ```
  52 // Copyright (c) <firstYear>-<lastModifiedYear> The Bitcoin Core developers
  53 ```
  54 where `<lastModifiedYear>` is obtained from the `git log` history.
  55
  56 This subcommand also handles copyright headers that have only a single year. In
  57 those cases:
  58 ```
  59 // Copyright (c) <year> The Bitcoin Core developers
  60 ```
  61 will be updated to:
  62 ```
  63 // Copyright (c) <year>-<lastModifiedYear> The Bitcoin Core developers
  64 ```
  65 where the update is appropriate.
  66
  67 copyright\_header.py insert \<file\>
  68 ------------------------------------
  69 Inserts a copyright header for `The Bitcoin Core developers` at the top of the
  70 file in either Python or C++ style as determined by the file extension. If the
  71 file is a Python file and it has  `#!` starting the first line, the header is
  72 inserted in the line below it.
  73
  74 The copyright dates will be set to be `<year_introduced>-<current_year>` where
  75 `<year_introduced>` is according to the `git log` history. If
  76 `<year_introduced>` is equal to `<current_year>`, it will be set as a single
  77 year rather than two hyphenated years.
  78
  79 If the file already has a copyright for `The Bitcoin Core developers`, the
  80 script will exit.
  81
  82 gen-manpages.sh
  83 ===============
  84
  85 A small script to automatically create manpages in ../../doc/man by running the release binaries with the -help option.
  86 This requires help2man which can be found at: https://www.gnu.org/software/help2man/
  87
  88 git-subtree-check.sh
  89 ====================
  90
  91 Run this script from the root of the repository to verify that a subtree matches the contents of
  92 the commit it claims to have been updated to.
  93
  94 To use, make sure that you have fetched the upstream repository branch in which the subtree is
  95 maintained:
  96 * for `src/secp256k1`: https://github.com/bitcoin-core/secp256k1.git (branch master)
  97 * for `src/leveldb`: https://github.com/bitcoin-core/leveldb.git (branch bitcoin-fork)
  98 * for `src/univalue`: https://github.com/bitcoin-core/univalue.git (branch master)
  99 * for `src/crypto/ctaes`: https://github.com/bitcoin-core/ctaes.git (branch master)
 100
 101 Usage: `git-subtree-check.sh DIR (COMMIT)`
 102
 103 `COMMIT` may be omitted, in which case `HEAD` is used.
 104
 105 github-merge.py
 106 ===============
 107
 108 A small script to automate merging pull-requests securely and sign them with GPG.
 109
 110 For example:
 111
 112   ./github-merge.py 3077
 113
 114 (in any git repository) will help you merge pull request #3077 for the
 115 bitcoin/bitcoin repository.
 116
 117 What it does:
 118 * Fetch master and the pull request.
 119 * Locally construct a merge commit.
 120 * Show the diff that merge results in.
 121 * Ask you to verify the resulting source tree (so you can do a make
 122 check or whatever).
 123 * Ask you whether to GPG sign the merge commit.
 124 * Ask you whether to push the result upstream.
 125
 126 This means that there are no potential race conditions (where a
 127 pullreq gets updated while you're reviewing it, but before you click
 128 merge), and when using GPG signatures, that even a compromised GitHub
 129 couldn't mess with the sources.
 130
 131 Setup
 132 ---------
 133 Configuring the github-merge tool for the bitcoin repository is done in the following way:
 134
 135     git config githubmerge.repository bitcoin/bitcoin
 136     git config githubmerge.testcmd "make -j4 check" (adapt to whatever you want to use for testing)
 137     git config --global user.signingkey mykeyid (if you want to GPG sign)
 138
 139 optimize-pngs.py
 140 ================
 141
 142 A script to optimize png files in the bitcoin
 143 repository (requires pngcrush).
 144
 145 security-check.py and test-security-check.py
 146 ============================================
 147
 148 Perform basic ELF security checks on a series of executables.
 149
 150 symbol-check.py
 151 ===============
 152
 153 A script to check that the (Linux) executables produced by gitian only contain
 154 allowed gcc, glibc and libstdc++ version symbols. This makes sure they are
 155 still compatible with the minimum supported Linux distribution versions.
 156
 157 Example usage after a gitian build:
 158
 159     find ../gitian-builder/build -type f -executable | xargs python contrib/devtools/symbol-check.py
 160
 161 If only supported symbols are used the return value will be 0 and the output will be empty.
 162
 163 If there are 'unsupported' symbols, the return value will be 1 a list like this will be printed:
 164
 165     .../64/test_bitcoin: symbol memcpy from unsupported version GLIBC_2.14
 166     .../64/test_bitcoin: symbol __fdelt_chk from unsupported version GLIBC_2.15
 167     .../64/test_bitcoin: symbol std::out_of_range::~out_of_range() from unsupported version GLIBCXX_3.4.15
 168     .../64/test_bitcoin: symbol _ZNSt8__detail15_List_nod from unsupported version GLIBCXX_3.4.15
 169
 170 update-translations.py
 171 ======================
 172
 173 Run this script from the root of the repository to update all translations from transifex.
 174 It will do the following automatically:
 175
 176 - fetch all translations
 177 - post-process them into valid and committable format
 178 - add missing translations to the build system (TODO)
 179
 180 See doc/translation-process.md for more information.