LBRYCommunity/lbrycrd
1
0
Fork 0
Code Issues 29 Pull requests 1 Projects Releases 32 Packages Wiki Activity

Merge #12759: [Docs] Improve formatting of developer notes

Browse source 
0bd2ec5 Improve formatting of developer notes (Evan Klitzke)

Pull request description:

  The developer notes file has gotten pretty large and unwieldly. This reorganizes some content, most notably by adding a TOC to the page. Compare how the page looks in [my branch](https://github.com/eklitzke/bitcoin/blob/developer-notes/doc/developer-notes.md) vs [master](https://github.com/eklitzke/bitcoin/blob/master/doc/developer-notes.md).

  I know there's long-term interest in moving a lot of this content to the bitcoin-core/docs repo on GitHub, but this makes things better now.

  The TOC format here is a semi-standard extension to Markdown files that you may have seen on GitHub pages in other projects. The `<!-- markdown-toc -->` comments used by these tools to know where the TOC starts/ends. The following tools all understand this format:

   * [Sphinx](http://www.sphinx-doc.org/en/master/)
   * [Pandoc](https://pandoc.org/)
   * [markdown-toc.el](https://github.com/ardumont/markdown-toc) (what I used)
   * various plugins for [vim](https://github.com/mzlogin/vim-markdown-toc) and other editors

  I used this TOC extension at a previous job, and my observation is that it's fine if people just edit the TOC manually. It's just text and it's not a huge deal if it gets a little out of sync. It can also be regenerated at any time by anyone with any of these tools.

Tree-SHA512: 298d1605ea5e8bfc0f75e70570c23ebd6891e4ffcdedd24fefadc23edd6e4b96509d8d102209868468a1b3ddbe2c3b8462698cdda8b9421348b5bc6f7b8d0cb8
This commit is contained in:
Wladimir J. van der Laan 2018-03-29 15:37:20 +02:00
commit d3908e2cee
No known key found for this signature in database
GPG key ID: 1E4AED62986CD25D
1 changed files with 66 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
doc/developer-notes.md
View file

@ -1,6 +1,43 @@
Developer Notes Developer Notes
=============== ===============
<!-- markdown-toc start -->
**Table of Contents**
- [Developer Notes](#developer-notes)
- [Coding Style](#coding-style)
- [Doxygen comments](#doxygen-comments)
- [Development tips and tricks](#development-tips-and-tricks)
- [Compiling for debugging](#compiling-for-debugging)
- [Compiling for gprof profiling](#compiling-for-gprof-profiling)
- [debug.log](#debuglog)
- [Testnet and Regtest modes](#testnet-and-regtest-modes)
- [DEBUG_LOCKORDER](#debug_lockorder)
- [Valgrind suppressions file](#valgrind-suppressions-file)
- [Compiling for test coverage](#compiling-for-test-coverage)
- [Locking/mutex usage notes](#lockingmutex-usage-notes)
- [Threads](#threads)
- [Ignoring IDE/editor files](#ignoring-ideeditor-files)
- [Development guidelines](#development-guidelines)
- [General Bitcoin Core](#general-bitcoin-core)
- [Wallet](#wallet)
- [General C++](#general-c)
- [C++ data structures](#c-data-structures)
- [Strings and formatting](#strings-and-formatting)
- [Variable names](#variable-names)
- [Threads and synchronization](#threads-and-synchronization)
- [Source code organization](#source-code-organization)
- [GUI](#gui)
- [Subtrees](#subtrees)
- [Git and GitHub tips](#git-and-github-tips)
- [Scripted diffs](#scripted-diffs)
- [RPC interface guidelines](#rpc-interface-guidelines)
<!-- markdown-toc end -->
Coding Style
---------------
Various coding styles have been used during the history of the codebase, Various coding styles have been used during the history of the codebase,
and the result is not very consistent. However, we're now trying to converge to and the result is not very consistent. However, we're now trying to converge to
a single style, which is specified below. When writing patches, favor the new a single style, which is specified below. When writing patches, favor the new
@ -138,43 +175,44 @@ Documentation can be generated with `make docs` and cleaned up with `make clean-
Development tips and tricks Development tips and tricks
--------------------------- ---------------------------
**compiling for debugging** ### Compiling for debugging
Run configure with the --enable-debug option, then make. Or run configure with Run configure with `--enable-debug` to add additional compiler flags that
CXXFLAGS="-g -ggdb -O0" or whatever debug flags you need. produce better debugging builds.
**compiling for gprof profiling** ### Compiling for gprof profiling
Run configure with the --enable-gprof option, then make. Run configure with the `--enable-gprof` option, then make.
**debug.log** ### debug.log
If the code is behaving strangely, take a look in the debug.log file in the data directory; If the code is behaving strangely, take a look in the debug.log file in the data directory;
error and debugging messages are written there. error and debugging messages are written there.
The -debug=... command-line option controls debugging; running with just -debug or -debug=1 will turn The `-debug=...` command-line option controls debugging; running with just `-debug` or `-debug=1` will turn
on all categories (and give you a very large debug.log file). on all categories (and give you a very large debug.log file).
The Qt code routes qDebug() output to debug.log under category "qt": run with -debug=qt The Qt code routes `qDebug()` output to debug.log under category "qt": run with `-debug=qt`
to see it. to see it.
**testnet and regtest modes** ### Testnet and Regtest modes
Run with the -testnet option to run with "play bitcoins" on the test network, if you Run with the `-testnet` option to run with "play bitcoins" on the test network, if you
are testing multi-machine code that needs to operate across the internet. are testing multi-machine code that needs to operate across the internet.
If you are testing something that can run on one machine, run with the -regtest option. If you are testing something that can run on one machine, run with the `-regtest` option.
In regression test mode, blocks can be created on-demand; see test/functional/ for tests In regression test mode, blocks can be created on-demand; see [test/functional/](/test/functional) for tests
that run in -regtest mode. that run in `-regtest` mode.
**DEBUG_LOCKORDER** ### DEBUG_LOCKORDER
Bitcoin Core is a multithreaded application, and deadlocks or other multithreading bugs Bitcoin Core is a multi-threaded application, and deadlocks or other
can be very difficult to track down. Compiling with -DDEBUG_LOCKORDER (configure multi-threading bugs can be very difficult to track down. The `--enable-debug`
CXXFLAGS="-DDEBUG_LOCKORDER -g") inserts run-time checks to keep track of which locks configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts
are held, and adds warnings to the debug.log file if inconsistencies are detected. run-time checks to keep track of which locks are held, and adds warnings to the
debug.log file if inconsistencies are detected.
**Valgrind suppressions file** ### Valgrind suppressions file
Valgrind is a programming tool for memory debugging, memory leak detection, and Valgrind is a programming tool for memory debugging, memory leak detection, and
profiling. The repo contains a Valgrind suppressions file profiling. The repo contains a Valgrind suppressions file
@ -189,7 +227,7 @@ $ valgrind --suppressions=contrib/valgrind.supp --leak-check=full \
$ valgrind -v --leak-check=full src/bitcoind -printtoconsole $ valgrind -v --leak-check=full src/bitcoind -printtoconsole
``` ```
**compiling for test coverage** ### Compiling for test coverage
LCOV can be used to generate a test coverage report based upon `make check` LCOV can be used to generate a test coverage report based upon `make check`
execution. LCOV must be installed on your system (e.g. the `lcov` package execution. LCOV must be installed on your system (e.g. the `lcov` package
@ -209,18 +247,18 @@ Locking/mutex usage notes
------------------------- -------------------------
The code is multi-threaded, and uses mutexes and the The code is multi-threaded, and uses mutexes and the
LOCK/TRY_LOCK macros to protect data structures. `LOCK` and `TRY_LOCK` macros to protect data structures.
Deadlocks due to inconsistent lock ordering (thread 1 locks cs_main Deadlocks due to inconsistent lock ordering (thread 1 locks `cs_main` and then
and then cs_wallet, while thread 2 locks them in the opposite order: `cs_wallet`, while thread 2 locks them in the opposite order: result, deadlock
result, deadlock as each waits for the other to release its lock) are as each waits for the other to release its lock) are a problem. Compile with
a problem. Compile with -DDEBUG_LOCKORDER to get lock order `-DDEBUG_LOCKORDER` (or use `--enable-debug`) to get lock order inconsistencies
inconsistencies reported in the debug.log file. reported in the debug.log file.
Re-architecting the core code so there are better-defined interfaces Re-architecting the core code so there are better-defined interfaces
between the various components is a goal, with any necessary locking between the various components is a goal, with any necessary locking
done by the components (e.g. see the self-contained CBasicKeyStore class done by the components (e.g. see the self-contained `CBasicKeyStore` class
and its cs_KeyStore lock for example). and its `cs_KeyStore` lock for example).
Threads Threads
------- -------