diff --git a/contrib/devtools/README.md b/contrib/devtools/README.md index 1d2ae3e726fcc..c1cc2f9cc522a 100644 --- a/contrib/devtools/README.md +++ b/contrib/devtools/README.md @@ -1,5 +1,5 @@ Contents -=========== +======== This directory contains tools for developers working on this repository. check-doc.py @@ -8,6 +8,93 @@ check-doc.py Check if all command line args are documented. The return value indicates the number of undocumented args. +clang-format-diff.py +=================== + +A script to format unified git diffs according to [.clang-format](../../src/.clang-format). + +Requires `clang-format`, installed e.g. via `brew install clang-format` on macOS. + +For instance, to format the last commit with 0 lines of context, +the script should be called from the git root folder as follows. + +``` +git diff -U0 HEAD~1.. | ./contrib/devtools/clang-format-diff.py -p1 -i -v +``` + +copyright\_header.py +==================== + +Provides utilities for managing copyright headers of `The PIVX +developers` in repository source files. It has three subcommands: + +``` +$ ./copyright_header.py report [verbose] +$ ./copyright_header.py update +$ ./copyright_header.py insert +``` +Running these subcommands without arguments displays a usage string. + +copyright\_header.py report \ [verbose] +--------------------------------------------------------- + +Produces a report of all copyright header notices found inside the source files +of a repository. Useful to quickly visualize the state of the headers. +Specifying `verbose` will list the full filenames of files of each category. + +copyright\_header.py update \ [verbose] +--------------------------------------------------------- +Updates all the copyright headers of `The PIVX developers` which were +changed in a year more recent than is listed. For example: +``` +// Copyright (c) - The PIVX developers +``` +will be updated to: +``` +// Copyright (c) - The PIVX developers +``` +where `` is obtained from the `git log` history. + +This subcommand also handles copyright headers that have only a single year. In +those cases: +``` +// Copyright (c) The PIVX developers +``` +will be updated to: +``` +// Copyright (c) - The PIVX developers +``` +where the update is appropriate. + +copyright\_header.py insert \ +------------------------------------ +Inserts a copyright header for `The PIVX developers` at the top of the +file in either Python or C++ style as determined by the file extension. If the +file is a Python file and it has `#!` starting the first line, the header is +inserted in the line below it. + +The copyright dates will be set to be `-` where +`` is according to the `git log` history. If +`` is equal to ``, it will be set as a single +year rather than two hyphenated years. + +If the file already has a copyright for `The PIVX developers`, the +script will exit. + +gen-manpages.sh +=============== + +A small script to automatically create manpages in ../../doc/man by running the release binaries with the -help option. +This requires help2man which can be found at: https://www.gnu.org/software/help2man/ + +With in-tree builds this tool can be run from any directory within the +repostitory. To use this tool with out-of-tree builds set `BUILDDIR`. For +example: + +```bash +BUILDDIR=$PWD/build contrib/devtools/gen-manpages.sh +``` + github-merge.py =============== @@ -40,43 +127,44 @@ Configuring the github-merge tool for the PIVX repository is done in the followi git config githubmerge.repository PIVX-Project/PIVX git config githubmerge.testcmd "make -j4 check" (adapt to whatever you want to use for testing) - git config --global user.signingkey mykeyid (if you want to GPG sign) - -optimize-pngs.py -================ - -A script to optimize png files in the PIVX -repository (requires pngcrush). + git config --global user.signingkey mykeyid -fix-copyright-headers.py -=========================== +Authentication (optional) +-------------------------- -Every year newly updated files need to have its copyright headers updated to reflect the current year. -If you run this script from src/ it will automatically update the year on the copyright header for all -.cpp and .h files if these have a git commit from the current year. +The API request limit for unauthenticated requests is quite low, but the +limit for authenticated requests is much higher. If you start running +into rate limiting errors it can be useful to set an authentication token +so that the script can authenticate requests. -For example a file changed in 2014 (with 2014 being the current year): -```// Copyright (c) 2009-2013 The Bitcoin developers``` +- First, go to [Personal access tokens](https://github.com/settings/tokens). +- Click 'Generate new token'. +- Fill in an arbitrary token description. No further privileges are needed. +- Click the `Generate token` button at the bottom of the form. +- Copy the generated token (should be a hexadecimal string) -would be changed to: -```// Copyright (c) 2009-2014 The Bitcoin developers``` +Then do: -logprint-scanner.py -=================== -LogPrint and LogPrintf are known to throw exceptions when the number of arguments supplied to the -LogPrint(f) function is not the same as the number of format specifiers. + git config --global user.ghtoken "pasted token" -Ideally, the presentation of this mismatch would be at compile-time, but instead it is at run-time. +Create and verify timestamps of merge commits +--------------------------------------------- +To create or verify timestamps on the merge commits, install the OpenTimestamps +client via `pip3 install opentimestamps-client`. Then, dowload the gpg wrapper +`ots-git-gpg-wrapper.sh` and set it as git's `gpg.program`. See +[the ots git integration documentation](https://github.com/opentimestamps/opentimestamps-client/blob/master/doc/git-integration.md#usage) +for further details. -This script scans the src/ directory recursively and looks in each .cpp/.h file and identifies all -errorneous LogPrint(f) calls where the number of arguments do not match. +optimize-pngs.py +================ -The filename and line number of the errorneous occurence is given. +A script to optimize png files in the PIVX +repository (requires pngcrush). -The script returns with the number of erroneous occurences as an error code to help facilitate -integration with a continuous integration system. +security-check.py and test-security-check.py +============================================ -The script can be ran from any working directory inside the git repository. +Perform basic ELF security checks on a series of executables. symbol-check.py =============== @@ -87,7 +175,7 @@ still compatible with the minimum supported Linux distribution versions. Example usage after a gitian build: - find ../gitian-builder/build -type f -executable | xargs python contrib/devtools/symbol-check.py + find ../gitian-builder/build -type f -executable | xargs python3 contrib/devtools/symbol-check.py If only supported symbols are used the return value will be 0 and the output will be empty. @@ -109,3 +197,14 @@ It will do the following automatically: - add missing translations to the build system (TODO) See doc/translation-process.md for more information. + +circular-dependencies.py +======================== + +Run this script from the root of the source tree (`src/`) to find circular dependencies in the source code. +This looks only at which files include other files, treating the `.cpp` and `.h` file as one unit. + +Example usage: + + cd .../src + ../contrib/devtools/circular-dependencies.py {*,*/*,*/*/*}.{h,cpp}