diff --git a/doc/unit-tests.md b/doc/unit-tests.md index 651d41818d..adf1b3c0b7 100644 --- a/doc/unit-tests.md +++ b/doc/unit-tests.md @@ -1,67 +1,88 @@ ### Compiling/running unit tests -Unit tests will be automatically compiled if dependencies were met in `./configure` -and tests weren't explicitly disabled. +Unit tests are not part of the default build but can be built on demand. -After configuring, they can be run with `make check`. +All the unit tests can be built and run with a single command: `ninja check`. -To run the bitcoind tests manually, launch `src/test/test_bitcoin`. +#### bitcoind unit tests -To add more bitcoind tests, add `BOOST_AUTO_TEST_CASE` functions to the existing -.cpp files in the `src/test/` directory or add new .cpp files that -implement new BOOST_AUTO_TEST_SUITE sections. +The `bitcoind` unit tests can be built with `ninja test_bitcoin`. +They can also be built and run in a single command with `ninja check-bitcoin`. -To run the bitcoin-qt tests manually, launch `src/qt/test/test_bitcoin-qt` +To run the `bitcoind` tests manually, launch `src/test/test_bitcoin`. -To add more bitcoin-qt tests, add them to the `src/qt/test/` directory and +To add more `bitcoind` tests, add `BOOST_AUTO_TEST_CASE` functions to the +existing .cpp files in the `src/test/` directory or add new .cpp files that +implement new `BOOST_AUTO_TEST_SUITE` sections. + +#### bitcoin-qt unit tests + +The `bitcoin-qt` tests can be built with `ninja test_bitcoin-qt` or +built and run in a single command with `ninja check-bitcoin-qt`. + +To run the `bitcoin-qt` tests manually, launch `src/qt/test/test_bitcoin-qt`. + +To add more `bitcoin-qt` tests, add them to the `src/qt/test/` directory and the `src/qt/test/test_main.cpp` file. +#### bitcoin-seeder unit tests + +The `bitcoin-seeder` unit tests can be built with `ninja test_bitcoin-seeder` or +built and run in a single command with `ninja check-bitcoin-seeder`. + +To run the `bitcoin-seeder` tests manually, launch +`src/seeder/test/test_bitcoin-seeder`. + +To add more `bitcoin-seeder` tests, add `BOOST_AUTO_TEST_CASE` functions to the +existing .cpp files in the `src/seeder/test/` directory or add new .cpp files +that implement new `BOOST_AUTO_TEST_SUITE` sections. + ### Running individual tests -test_bitcoin has some built-in command-line arguments; for -example, to run just the getarg_tests verbosely: +`test_bitcoin` has some built-in command-line arguments; for +example, to run just the `getarg_tests` verbosely: test_bitcoin --log_level=all --run_test=getarg_tests ... or to run just the doubledash test: test_bitcoin --run_test=getarg_tests/doubledash Run `test_bitcoin --help` for the full list. ### Note on adding test cases The build system is setup to compile an executable called `test_bitcoin` that runs all of the unit tests. The main source file is called test_bitcoin.cpp. To add a new unit test file to our test suite you need -to add the file to `src/Makefile.test.include`. The pattern is to create +to add the file to `src/test/CMakeLists.txt`. The pattern is to create one test file for each class or source file for which you want to create unit tests. The file naming convention is `_tests.cpp` and such files should wrap their tests in a test suite called `_tests`. For an example of this pattern, examine `uint256_tests.cpp`. For further reading, I found the following website to be helpful in explaining how the boost unit test framework works: [https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/](https://legalizeadulthood.wordpress.com/2009/07/04/c-unit-tests-with-boost-test-part-1/) ### Debugging unit tests Simple example of debugging unit tests with GDB on Linux: ``` cd /build/src/test gdb test_bitcoin break interpreter.cpp:295 # No path is necessary, just the file name and line number run # GDB hits the breakpoint p/x opcode # print the value of the variable (in this case, opcode) in hex c # continue ``` Simple example of debugging unit tests with LLDB (OSX or Linux): ``` cd /build/src/test lldb -- test_bitcoin break set --file interpreter.cpp --line 295 run ``` diff --git a/doc/zmq.md b/doc/zmq.md index 5d67df9d22..7095dc8a18 100644 --- a/doc/zmq.md +++ b/doc/zmq.md @@ -1,106 +1,105 @@ # Block and Transaction Broadcasting with ZeroMQ [ZeroMQ](http://zeromq.org/) is a lightweight wrapper around TCP connections, inter-process communication, and shared-memory, providing various message-oriented semantics such as publish/subscribe, request/reply, and push/pull. -The Bitcoin Core daemon can be configured to act as a trusted "border +The Bitcoin ABC daemon can be configured to act as a trusted "border router", implementing the bitcoin wire protocol and relay, making consensus decisions, maintaining the local blockchain database, broadcasting locally generated transactions into the network, and providing a queryable RPC interface to interact on a polled basis for requesting blockchain related data. However, there exists only a limited service to notify external software of events like the arrival of new blocks or transactions. The ZeroMQ facility implements a notification interface through a set of specific notifiers. Currently there are notifiers that publish blocks and transactions. This read-only facility requires only the connection of a corresponding ZeroMQ subscriber port in receiving software; it is not authenticated nor is there any two-way protocol involvement. Therefore, subscribers should validate the received data since it may be out of date, incomplete or even invalid. ZeroMQ sockets are self-connecting and self-healing; that is, connections made between two endpoints will be automatically restored after an outage, and either end may be freely started or stopped in any order. Because ZeroMQ is message oriented, subscribers receive transactions and blocks all-at-once and do not need to implement any sort of buffering or reassembly. ## Prerequisites -The ZeroMQ feature in Bitcoin Core requires ZeroMQ API version 4.x or +The ZeroMQ feature in Bitcoin ABC requires ZeroMQ API version 4.x or newer. Typically, it is packaged by distributions as something like *libzmq3-dev*. The C++ wrapper for ZeroMQ is *not* needed. In order to run the example Python client scripts in contrib/ one must also install *python3-zmq*, though this is not necessary for daemon operation. ## Enabling -By default, the ZeroMQ feature is automatically compiled in if the -necessary prerequisites are found. To disable, use --disable-zmq -during the *configure* step of building bitcoind: +By default, the ZeroMQ feature is automatically compiled. +To disable, use -DBUILD_BITCOIN_ZMQ=OFF to `cmake` when building bitcoind: - $ ./configure --disable-zmq (other options) + $ cmake -GNinja .. -DBUILD_BITCOIN_ZMQ=OFF [...] To actually enable operation, one must set the appropriate options on the command line or in the configuration file. ## Usage Currently, the following notifications are supported: -zmqpubhashtx=address -zmqpubhashblock=address -zmqpubrawblock=address -zmqpubrawtx=address The socket type is PUB and the address must be a valid ZeroMQ socket address. The same address can be used in more than one notification. For instance: $ bitcoind -zmqpubhashtx=tcp://127.0.0.1:28332 \ -zmqpubrawtx=ipc:///tmp/bitcoind.tx.raw Each PUB notification has a topic and body, where the header corresponds to the notification type. For instance, for the notification `-zmqpubhashtx` the topic is `hashtx` (no null terminator) and the body is the transaction hash (32 bytes). These options can also be provided in bitcoin.conf. ZeroMQ endpoint specifiers for TCP (and others) are documented in the [ZeroMQ API](http://api.zeromq.org/4-0:_start). Client side, then, the ZeroMQ subscriber socket must have the ZMQ_SUBSCRIBE option set to one or either of these prefixes (for instance, just `hash`); without doing so will result in no messages arriving. Please see `contrib/zmq/zmq_sub.py` for a working example. ## Remarks From the perspective of bitcoind, the ZeroMQ socket is write-only; PUB sockets don't even have a read function. Thus, there is no state introduced into bitcoind directly. Furthermore, no information is broadcast that wasn't already received from the public P2P network. No authentication or authorization is done on connecting clients; it is assumed that the ZeroMQ port is exposed only to trusted entities, using other means such as firewalling. Note that when the block chain tip changes, a reorganisation may occur and just the tip will be notified. It is up to the subscriber to retrieve the chain from the last known block to the new tip. There are several possibilities that ZMQ notification can get lost during transmission depending on the communication type you are using. Bitcoind appends an up-counting sequence number to each notification which allows listeners to detect lost notifications. diff --git a/src/qt/README.md b/src/qt/README.md index 554cc1eaf0..de39355a81 100644 --- a/src/qt/README.md +++ b/src/qt/README.md @@ -1,95 +1,95 @@ This directory contains the BitcoinQT graphical user interface (GUI). It uses the cross platform framework [QT](https://www1.qt.io/developers/). The current precise version for QT 5 is specified in [qt.mk](/depends/packages/qt.mk). ## Compile and run See build instructions ([macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [Unix](/doc/build-unix.md), etc). To run: ```sh ./src/qt/bitcoin-qt ``` ## Files and directories ### forms Contains [Designer UI](http://doc.qt.io/qt-5.9/designer-using-a-ui-file.html) files. They are created with [Qt Creator](#use-qt-Creator-as IDE), but can be edited using any text editor. ### locale Contains translations. They are periodically updated. The process is described [here](/doc/translation_process.md). ### res Resources such as the icon. ### test -Tests. +Tests (see [the unit tests documentation](/doc/unit-tests.md)). ### bitcoingui.(h/cpp) Represents the main window of the Bitcoin UI. ### \*model.(h/cpp) The model. When it has a corresponding controller, it generally inherits from [QAbstractTableModel](http://doc.qt.io/qt-5/qabstracttablemodel.html). Models that are used by controllers as helpers inherit from other QT classes like [QValidator](http://doc.qt.io/qt-5/qvalidator.html). ClientModel is used by the main application `bitcoingui` and several models like `peertablemodel`. ### \*page.(h/cpp) A controller. `:NAMEpage.cpp` generally includes `:NAMEmodel.h` and `forms/:NAME.page.ui` with a similar `:NAME`. ### \*dialog.(h/cpp) Various dialogs, e.g. to open a URL. Inherit from [QDialog](http://doc.qt.io/qt-5.5/qdialog.html). ### paymentserver.(h/cpp) Used to process BIP21 and BIP70 payment URI / requests. Also handles URI based application switching (e.g. when following a bitcoincash:... link from a browser). ### walletview.(h/cpp) Represents the view to a single wallet. ### Other .h/cpp files * UI elements like BitcoinAmountField, which inherit from QWidget. * `bitcoinstrings.cpp`: automatically generated * `bitcoinunits.(h/cpp)`: BCH / mBCH / etc handling * `callback.h` * `guiconstants.h`: UI colors, app name, etc * `guiutil.h`: several helper functions * `macdockiconhandler.(h/cpp)` * `macdockiconhandler.(h/cpp)`: display notifications in macOS ## Contribute See [CONTRIBUTING.md](/CONTRIBUTING.md) for general guidelines. Specifically for QT: * don't change `local/bitcoin_en.ts`; this happens [automatically](/doc/translation_process.md#writing-code-with-translations) ## Using Qt Creator as IDE You can use Qt Creator as an IDE. This is especially useful if you want to change the UI layout. Download and install the community edition of [Qt Creator](https://www.qt.io/download/). Uncheck everything except Qt Creator during the installation process. Instructions for macOS: 1. Make sure you installed everything through Homebrew mentioned in the [macOS build instructions](/doc/build-osx.md) -2. Use `./configure` with the `--enable-debug` flag +2. Use `cmake` with the `-DCMAKE_BUILD_TYPE=Debug` flag 3. In Qt Creator do "New Project" -> Import Project -> Import Existing Project 4. Enter "bitcoin-qt" as project name, enter src/qt as location 5. Leave the file selection as it is 6. Confirm the "summary page" 7. In the "Projects" tab select "Manage Kits..." 8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler 9. Select LLDB as debugger (you might need to set the path to your installation) 10. Start debugging with Qt Creator (you might need to the executable to "bitcoin-qt" under "Run", which is where you can also add command line arguments)